Re: [PATCH] inline src block results can be removed

[Andreas Leha <andreas.leha@med.uni-goettingen.de>]

Hi Daniele,

I think your wishlist is somewhere further down the road.  I usually
implement some of your points in the src_language.  I see that it would
be nice if org supported these use cases, but I would see them as part
of the LOB or maybe in some package in contrib rather than in core
org/babel.

For that, I'd argue removable inline results that can be exported
without special formatting would be all that is needed to support your
wishlist.


A few inline comments below.


Daniele Pizzolli <dan@toel.it> writes:
> On 2014-11-17 00:23, Nicolas Goaziou wrote:
>> "Charles C. Berry" writes:
>> 
>>> For now, I'd be willing to make patches that will allow removal of the
>>> inline src block results that do *not* involve these header args:
>
> []
>
>> IMO, we're too much focused on the implementation details. We ought to
>> agree on what should be done first. For example, considering
>> `org-babel-insert-result' and its RESULT-PARAMS argument, I think the
>> following makes sense:
>> 
>>   | Param   | Example output                    |
>>   |---------+-----------------------------------|
>>   | default | {{{results(42)}}}                 |
>>   | file    | {{{results(file:something.pdf)}}} |
>>   | list    |                                   |
>>   | raw     | 42                                |
>>   | drawer  |                                   |
>>   | org     | {{{results(src_org{...})}}}       |
>>   | html    | {{{results(@@html:...@@)}}}       |
>>   | latex   | {{{results(@@latex:...@@)}}}      |
>>   | code    | {{{results(src_xxx{...})}}}       |
>> 
>> Basically, it should be possible to remove any kind of result using
>> "results" macro, with the exception of "raw".  "list" and "drawer" can
>> be ignored since there is no inline equivalent.
>
> []
>
>> There's no rush, however. Non-removable results from inline source
>> blocks have been there for a long time.
>
> Hello all,
>
> I jump into this conversation because in the next months I will try to
> write a supplementary information annex using org-mode with Gnu R, so
> my idea on what should be done follows...
>
> I guess I will start my project using those patches.  Thanks!
>
> A brief review on how how results are presented (or usually
> anticipated) inline led me to the following wish list:
>
> * provide some facilities to keep track of the 'unit of measurement'
>
> Few numbers are pure numbers.  There is a little value added to the
> correctness of the work as a whole if I get the correct number from
> babel but I have hard coded the wrong unit of measure in the text.
>
> Please follow the examples.
>
> # Load used languages
>
> #+BEGIN_SRC emacs-lisp
> (org-babel-do-load-languages
> 'org-babel-load-languages
> '((emacs-lisp . nil)
> (octave . t)
> (R . t)))
> #+END_SRC
>
>
> Ideally, I think that reasonable solution would take table like the
> following:
>
> #+TBLNAME:speed-1
> | speed | speed_unit |
> |-------+------------|
> |    12 | km/s       |
>
> and output by default or through an easy to call syntax:
>
> #+BEGIN_EXAMPLE
> 12 km/s
> #+END_EXAMPLE
>
>
> I am not aware of any facilities provided by languages like R or
> octave to keep track of the unit of measure, If you have some please
> share.
>
> A more space wise representation, that add another layer of
> indirection would be to have a look-up table like the following:
>
> #+TBLNAME:speed-1-units-lookup
> | name   | unit |
> |--------+------|
> | speed  | km/s |
> | length | km   |
> | time   | s    |
>

I usually have an even more elaborate legend table like

| name | display | unit |
|------+---------+------|
| sp   | speed   | km/s |
| le   | length  | km   |
| ti   | time    | s    |

And sometimes even (some) translation support:

| name | display | de              | unit |
|------+---------+-----------------+------|
| sp   | speed   | Geschwindigkeit | km/s |
| le   | length  | Länge           | km   |
| ti   | time    | Zeit            | s    |

Only the table is in org, the handling is done not by org, but in R.


> But I am not sure that it's worth it, at least for those that are
> working with small data sets.
>
> * support for inline rendering of tables
>
> The most complex inline output I think I will need at some point
> follows:
>
> #+TBLNAME:data-set-1
> #+NAME:data-set-1
> | position | item1 | author1 | item2 | author2 | correlation |
> |----------+-------+---------+-------+---------+-------------|
> |        1 | i1    | a1      | j1    | b1      | c1          |
> |        2 | i2    | a2      | j2    | b2      | c2          |
> |        3 | i3    | a3      | j3    | b3      | c3          |
>
> #+NAME: block-1
> #+BEGIN_SRC R :session :colnames yes :exports none :var 
>
> data_set_1=data-set-1
> # Just to show that we use R
> data_set_2 <- data_set_1
> #+END_SRC
>
> #+RESULTS: block-1
> | position | item1 | author1 | item2 | author2 | correlation |
>
> |----------+-------+---------+-------+---------+-------------|
> |        1 | i1    | a1      | j1    | b1      | c1          |
> |        2 | i2    | a2      | j2    | b2      | c2          |
> |        3 | i3    | a3      | j3    | b3      | c3          |
>
>
> And I really like to be easily rendered as an inline string through
> some formatting specs e.g.:
>
> #+BEGIN_EXAMPLE
> #+PROPERTY: header-args: R :fmt '(%(position)i) %(item1)s by 
> /%(author1)s/ correlate to %(item2)s by /%(author2)s/  with a 
> correlation coefficient of %(correlation).2f'
> #+PROPERTY: header-args: R :rowsep (', ', ' and ')
>
> The preliminary results show that: src_R[:session :results 
> replace]{data_set_2}.
> #+END_EXAMPLE
>
>
> Will be rendered as:
>
> #+BEGIN_org
> The preliminary results show that:
> (1) i1 by /a1/ correlate to j1 by /b1/ with a correlation 
> coefficient of c1,
> (2) i2 by /a2/ correlate to j2 by /b2/ with a correlation 
> coefficient of c2 and
> (3) i3 by /a3/ correlate to j3 by /b3/ with a correlation 
> coefficient of c3.
> #+END_org
>

I am not sure how that would create a general use case.  I think the
language needed to glue the table elements is highly content dependent.
I'd do that per use case and via the language, i.e. in R, instead.


>
> For languages that does not support tables with headers we can stick
> with the positional formatting:
>
> #+NAME: block-2
> #+BEGIN_SRC octave :session :colnames yes :exports none :var 
>
> data_set_1=data-set-1
> ans = data_set_1;
> #+END_SRC
>
> # TODO: figure out why this does not work
>
> #+RESULTS: block-2
> : iii123aaa123jjj123bbb123ccc123
>
> #+BEGIN_EXAMPLE
> #+PROPERTY: header-args: octave :fmt '(%i) %s by /%s/ correlate to 
> %s by /%s/  with a correlation coefficient of %.2f'
> #+PROPERTY: header-args: octave :rowsep (', ', ' and ')
> The preliminary results show that: src_octave[:session :results 
> replace)]{ans}.
> #+END_EXAMPLE
>
> #+BEGIN_org
> The preliminary results show that:
> (1) i1 by /a1/ correlate to j1 by /b1/ with a correlation 
> coefficient of c1,
> (2) i2 by /a2/ correlate to j2 by /b2/ with a correlation 
> coefficient of c2 and
> (3) i3 by /a3/ correlate to j3 by /b3/ with a correlation 
> coefficient of c3.
> #+END_org
>
>
> * support for humanization
>
> A minor point would be supporting some humanization of the numbers
> using extended format placeholder to support:
>
> - number-as-word or number-as-cardinal :: 1 -> one
> - number-as-ordinal :: 2 -> second
> - number-as-pretty-fraction :: 2.3333 -> 2 + 1/3
> - number-as-word-fraction :: 2.3333 -> two and one third
> - number-as-natural-size :: 1000000 -> 1.0 MB
> - number-as-natural-size-binary :: 1000000 -> 976.6 KiB

There is some support for that in R (e.g. digits2text in
http://rattle.togaware.com/utility.R) as well, which should be easy to
wrap into an org block to call from your LOB.

>
> * auto formatting standard test result
>
> It would be nice to simplify the insertion of the result of standard
> test like Chi-square by taking the =R= result and rewrite in a
> sentence form:
>
> #+BEGIN_org
> \Chi-squared = 0.214, d.f. = 1, p-value < 0.05
> #+END_org
>
> But this is really lower priority because it will need a lot work to
> keep track of language and test specific parameters.

Are you aware of the 'ascii' R package?  That package focuses on
creating tables for various backend (including org) of a number of
scenarios.  I'd see such functionality again more on R's side.  Maybe as
a new package R2org?

>
> * Conclusion
>

HTH,
Andreas