emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* how to document/comment a complex org table formula
@ 2021-07-04 19:14 Uwe Brauer
  2021-07-05 14:13 ` Eric S Fraga
  2021-07-05 17:12 ` Karl Voit
  0 siblings, 2 replies; 14+ messages in thread
From: Uwe Brauer @ 2021-07-04 19:14 UTC (permalink / raw)
  To: emacs-orgmode


Hi 

It turns out that I have to deal with a bit more complex table formula
of the form 

#+begin_src elisp
#+TBLFM: $6=if($2>10,($2-10)*@2$7,0)+ min(10,$2)*@2$2+ min(10,$3)*@2$3 + if($4>10,($4-10)*@2$7,$4)+min(10,$4)*@2$4 +@2$5*$5;f1 
#+end_src

Is there any way to document or comment such a formula, since I am sure
that within days I don't remember why I chose that formula?

Regards

Uwe Brauer  



^ permalink raw reply	[flat|nested] 14+ messages in thread

* how to document/comment a complex org table formula
@ 2021-07-05  5:31 CHARPENTIER Emmanuel via General discussions about Org-mode.
  2021-07-05  6:29 ` Uwe Brauer
  0 siblings, 1 reply; 14+ messages in thread
From: CHARPENTIER Emmanuel via General discussions about Org-mode. @ 2021-07-05  5:31 UTC (permalink / raw)
  To: oub@mat.ucm.es; +Cc: emacs-orgmode@gnu.org

Limbic answer : 
  - create an emacs-lisp function doing what you want
  - comment /ad libitum/
  - call this function in your spreadsheet.

HTH,

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05  5:31 CHARPENTIER Emmanuel via General discussions about Org-mode.
@ 2021-07-05  6:29 ` Uwe Brauer
  2021-07-08 20:19   ` Nick Dokos
  0 siblings, 1 reply; 14+ messages in thread
From: Uwe Brauer @ 2021-07-05  6:29 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 371 bytes --]

>>> "GdaO" == General discussions about Org-mode <CHARPENTIER> writes:

> Limbic answer : 
>   - create an emacs-lisp function doing what you want
>   - comment /ad libitum/
>   - call this function in your spreadsheet.

I hoped such a function already existed and somebody would point it out
to me (I searched the package-list-package list but nothing came up)

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-04 19:14 how to document/comment a complex org table formula Uwe Brauer
@ 2021-07-05 14:13 ` Eric S Fraga
  2021-07-05 14:45   ` Uwe Brauer
  2021-07-05 14:55   ` Tim Visher
  2021-07-05 17:12 ` Karl Voit
  1 sibling, 2 replies; 14+ messages in thread
From: Eric S Fraga @ 2021-07-05 14:13 UTC (permalink / raw)
  To: emacs-orgmode

Sorry; I cannot help you directly.

My rule of thumb is that if formulas are getting too complex to
understand/recall clearly, it's time to use a proper programming
language instead.  The nice thing about org is you can have tables as
inputs to and outputs of src blocks...

My papers often have awk source blocks that process tables to generate
statistics for some (numerical) experiments.

Spreadsheets, org tables being an example of such, are brilliant tools
for simple calculations but are pretty much "write only programming
languages".

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-577-gf76d4d
: Latest paper written in org: https://arxiv.org/abs/2106.05096


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 14:13 ` Eric S Fraga
@ 2021-07-05 14:45   ` Uwe Brauer
  2021-07-05 14:55   ` Tim Visher
  1 sibling, 0 replies; 14+ messages in thread
From: Uwe Brauer @ 2021-07-05 14:45 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 1022 bytes --]

>>> "ESF" == Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Sorry; I cannot help you directly.
> My rule of thumb is that if formulas are getting too complex to
> understand/recall clearly, it's time to use a proper programming
> language instead.  The nice thing about org is you can have tables as
> inputs to and outputs of src blocks...

> My papers often have awk source blocks that process tables to generate
> statistics for some (numerical) experiments.

> Spreadsheets, org tables being an example of such, are brilliant tools
> for simple calculations but are pretty much "write only programming
> languages".

I agree, the problem is I have to collaborate with colleagues and they
use excel. I still struggle to understand their formula, so I thought it
would be a good idea to comment the terms I understand but even if I
call

org-edit-special, I cannot add comments, well I can but they are
destroyed when I turn back to the main file. Other tools such as
virtual-comment do not work neither in such a buffer.


[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 14:13 ` Eric S Fraga
  2021-07-05 14:45   ` Uwe Brauer
@ 2021-07-05 14:55   ` Tim Visher
  2021-07-05 15:20     ` Jude DaShiell
                       ` (2 more replies)
  1 sibling, 3 replies; 14+ messages in thread
From: Tim Visher @ 2021-07-05 14:55 UTC (permalink / raw)
  To: Org Mode List

[-- Attachment #1: Type: text/plain, Size: 1828 bytes --]

On Mon, Jul 5, 2021 at 10:14 AM Eric S Fraga <e.fraga@ucl.ac.uk> wrote:

> Sorry; I cannot help you directly.
>
> My rule of thumb is that if formulas are getting too complex to
> understand/recall clearly, it's time to use a proper programming
> language instead.  The nice thing about org is you can have tables as
> inputs to and outputs of src blocks...
>
> My papers often have awk source blocks that process tables to generate
> statistics for some (numerical) experiments.
>
> Spreadsheets, org tables being an example of such, are brilliant tools
> for simple calculations but are pretty much "write only programming
> languages".
>

I had never heard of using an org table as input into a source block.
That's really interesting.

The OP also poses an interesting idea that I have occasionally wanted. I
have generally accomplished this by simply including the documentation
above or below the table. In other words just having human text around it
that says 'This =formula= bit is because of X'.

But the idea of a multiline TBLFM syntax seems to be already be almost
supported. I was mildly shocked to find that this mostly works

```
|---+---|
| a | 1 |
| b | 3 |
|---+---|
|   | 4 |
#+TBLFM: @2$2=@-1*3
#+TBLFM: @3$2=vsum(@I..II)
```

Note that I don't need the usual `::` separation between formulas. Where it
breaks down is that I can't seem to reevaluate the whole table's formula by
whacking `C-u C-c C-c` anymore and, obviously, there's no syntax for adding
comments. Also I doubt that I'd be able to use any of org's keys for
editing formulas. I wonder how hard it would be to extend org's
understanding of the TBLFM to allow for this kind of syntax.

Once you had it then adding a comment character to it should be very simple.

--

In Christ,

Timmy V.

https://blog.twonegatives.com
http://five.sentenc.es

[-- Attachment #2: Type: text/html, Size: 2645 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 14:55   ` Tim Visher
@ 2021-07-05 15:20     ` Jude DaShiell
  2021-07-05 17:10       ` Uwe Brauer
  2021-07-05 15:39     ` Eric S Fraga
  2021-07-05 17:08     ` Uwe Brauer
  2 siblings, 1 reply; 14+ messages in thread
From: Jude DaShiell @ 2021-07-05 15:20 UTC (permalink / raw)
  To: Tim Visher, Org Mode List

Why not use functional narrative form to document complex formulas?
formula name:
formula function:
formula uses:
formula returns:
usually one line of text for each of those.  I know, this comes from
structured programming where no block of actual code is supposed to go
above 50 lines and that for many people cramps their styles.  It makes
maintenance a little easier though.


On Mon, 5 Jul 2021, Tim Visher wrote:

> On Mon, Jul 5, 2021 at 10:14 AM Eric S Fraga <e.fraga@ucl.ac.uk> wrote:
>
> > Sorry; I cannot help you directly.
> >
> > My rule of thumb is that if formulas are getting too complex to
> > understand/recall clearly, it's time to use a proper programming
> > language instead.  The nice thing about org is you can have tables as
> > inputs to and outputs of src blocks...
> >
> > My papers often have awk source blocks that process tables to generate
> > statistics for some (numerical) experiments.
> >
> > Spreadsheets, org tables being an example of such, are brilliant tools
> > for simple calculations but are pretty much "write only programming
> > languages".
> >
>
> I had never heard of using an org table as input into a source block.
> That's really interesting.
>
> The OP also poses an interesting idea that I have occasionally wanted. I
> have generally accomplished this by simply including the documentation
> above or below the table. In other words just having human text around it
> that says 'This =formula= bit is because of X'.
>
> But the idea of a multiline TBLFM syntax seems to be already be almost
> supported. I was mildly shocked to find that this mostly works
>
> ```
> |---+---|
> | a | 1 |
> | b | 3 |
> |---+---|
> |   | 4 |
> #+TBLFM: @2$2=@-1*3
> #+TBLFM: @3$2=vsum(@I..II)
> ```
>
> Note that I don't need the usual `::` separation between formulas. Where it
> breaks down is that I can't seem to reevaluate the whole table's formula by
> whacking `C-u C-c C-c` anymore and, obviously, there's no syntax for adding
> comments. Also I doubt that I'd be able to use any of org's keys for
> editing formulas. I wonder how hard it would be to extend org's
> understanding of the TBLFM to allow for this kind of syntax.
>
> Once you had it then adding a comment character to it should be very simple.
>
> --
>
> In Christ,
>
> Timmy V.
>
> https://blog.twonegatives.com
> http://five.sentenc.es
>


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 14:55   ` Tim Visher
  2021-07-05 15:20     ` Jude DaShiell
@ 2021-07-05 15:39     ` Eric S Fraga
  2021-07-05 17:08     ` Uwe Brauer
  2 siblings, 0 replies; 14+ messages in thread
From: Eric S Fraga @ 2021-07-05 15:39 UTC (permalink / raw)
  To: Tim Visher; +Cc: Org Mode List

[-- Attachment #1: Type: text/plain, Size: 567 bytes --]

On Monday,  5 Jul 2021 at 10:55, Tim Visher wrote:
> I had never heard of using an org table as input into a source block.
> That's really interesting.

Attached, for illustration, is a simple example, extracted from a paper
I'm currently writing.  The "input" to the awk script is the table at
the top of the document.  The output, two columns of numbers, get
converted to an org table, at the bottom of the document, automatically.

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-577-gf76d4d
: Latest paper written in org: https://arxiv.org/abs/2106.05096

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: example.org --]
[-- Type: text/x-org, Size: 1082 bytes --]


#+name: values
|-----------------------|
|  0.006780639787578286 |
|  0.006780639787578433 |
|  0.008195683980621288 |
|  0.006780639787578433 |
|  0.006780639787578286 |
|  0.006780639787578286 |
|  0.008195683980621288 |
|  0.006780639787578433 |
|  0.006780639787578286 |
| 0.0071466305079598775 |
|   0.01154503021335327 |
|  0.006780639787578433 |
|  0.010129986020310415 |
|   0.00819568398062114 |
|  0.006780639787578433 |
| 0.0071466305079598775 |
| 0.0071466305079598775 |
|-----------------------|

The table of values above include cases where rounding errors lead to slightly different results for what are essentially the same result.  The following awk script looks at only the significant digits to identify similar results:

#+name: frequency
#+begin_src awk :stdin values
  {
      if ($1 != "hline") {
          s = substr($1,2,9)
          n[s] += 1;
      }
  }
  END {
      for (val in n) {
          printf "%7.5f %d\n", val, n[val]
      }
  }
#+end_src

#+results: frequency
|  0.0082 | 3 |
| 0.00678 | 9 |
| 0.01013 | 1 |
| 0.00715 | 3 |
| 0.01154 | 1 |

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 14:55   ` Tim Visher
  2021-07-05 15:20     ` Jude DaShiell
  2021-07-05 15:39     ` Eric S Fraga
@ 2021-07-05 17:08     ` Uwe Brauer
  2 siblings, 0 replies; 14+ messages in thread
From: Uwe Brauer @ 2021-07-05 17:08 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 2439 bytes --]

>>> "TV" == Tim Visher <tim.visher@gmail.com> writes:

> On Mon, Jul 5, 2021 at 10:14 AM Eric S Fraga <e.fraga@ucl.ac.uk> wrote:
>> Sorry; I cannot help you directly.
>> 
>> My rule of thumb is that if formulas are getting too complex to
>> understand/recall clearly, it's time to use a proper programming
>> language instead.  The nice thing about org is you can have tables as
>> inputs to and outputs of src blocks...
>> 
>> My papers often have awk source blocks that process tables to generate
>> statistics for some (numerical) experiments.
>> 
>> Spreadsheets, org tables being an example of such, are brilliant tools
>> for simple calculations but are pretty much "write only programming
>> languages".
>> 

> I had never heard of using an org table as input into a source block.
> That's really interesting.

> The OP also poses an interesting idea that I have occasionally wanted. I
> have generally accomplished this by simply including the documentation
> above or below the table. In other words just having human text around it
> that says 'This =formula= bit is because of X'.

> But the idea of a multiline TBLFM syntax seems to be already be almost
> supported. I was mildly shocked to find that this mostly works

> ```
> |---+---|
> | a | 1 |
> | b | 3 |
> |---+---|
> |   | 4 |

> #+TBLFM: @2$2=@-1*3
> #+TBLFM: @3$2=vsum(@I..II)

> ```

> Note that I don't need the usual `::` separation between formulas. Where it
> breaks down is that I can't seem to reevaluate the whole table's formula by
> whacking `C-u C-c C-c` anymore 

You have to put the cursor on the beginning of each #+TBLFM
and hit C-u C-c C-c

> and, obviously, there's no syntax for adding
> comments. Also I doubt that I'd be able to use any of org's keys for
> editing formulas. I wonder how hard it would be to extend org's
> understanding of the TBLFM to allow for this kind of syntax.

Well the following  works!

#+begin_src elisp
|----+----+----+---+---+----|
|  1 |  4 |  5 | 3 | 3 |  6 |
|  3 | 12 | 15 | 9 | 2 | 11 |
| 12 |  2 | 14 | 7 | 3 | 10 |
#+TBLFM: $3=vsum($1..$2);f1:: #one comment
#+TBLFM: $6=vsum($4..$5);f1:: #second comment
#+end_src


> Once you had it then adding a comment character to it should be very simple.

I hoped to add comments to the formula editor, but that most likely
requires text-properties or overlays or something of that sort.

Regards


[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 15:20     ` Jude DaShiell
@ 2021-07-05 17:10       ` Uwe Brauer
  2021-07-05 17:24         ` Jude DaShiell
  0 siblings, 1 reply; 14+ messages in thread
From: Uwe Brauer @ 2021-07-05 17:10 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 680 bytes --]

>>> "JD" == Jude DaShiell <jdashiel@panix.com> writes:

> Why not use functional narrative form to document complex formulas?
> formula name:
> formula function:
> formula uses:
> formula returns:


That would be also nice, however the problem I am facing to have a long
and complicated expression with a lot of ifs, maybe best practise would
be to split it and distribute it over various column and add comments as
in 

#+begin_src elisp
|----+----+----+---+---+----|
|  1 |  4 |  5 | 3 | 3 |  6 |
|  3 | 12 | 15 | 9 | 2 | 11 |
| 12 |  2 | 14 | 7 | 3 | 10 |
#+TBLFM: $3=vsum($1..$2);f1:: #one comment
#+TBLFM: $6=vsum($4..$5);f1:: #second comment
#+end_src

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-04 19:14 how to document/comment a complex org table formula Uwe Brauer
  2021-07-05 14:13 ` Eric S Fraga
@ 2021-07-05 17:12 ` Karl Voit
  2021-07-05 19:35   ` Uwe Brauer
  1 sibling, 1 reply; 14+ messages in thread
From: Karl Voit @ 2021-07-05 17:12 UTC (permalink / raw)
  To: emacs-orgmode

Hi Uwe,

* Uwe Brauer <oub@mat.ucm.es> wrote:
>
> Is there any way to document or comment such a formula, since I am sure
> that within days I don't remember why I chose that formula?

This is not a solution for really complex formulas. However, please
do note that standard org has:

Named references: https://orgmode.org/manual/References.html
Name assignment:
https://orgmode.org/manual/Advanced-features.html#Advanced-features

For some cases, this may help.

-- 
get mail|git|SVN|photos|postings|SMS|phonecalls|RSS|CSV|XML into Org-mode:
       > get Memacs from https://github.com/novoid/Memacs <
Personal Information Management > http://Karl-Voit.at/tags/pim/
Emacs-related > http://Karl-Voit.at/tags/emacs/



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 17:10       ` Uwe Brauer
@ 2021-07-05 17:24         ` Jude DaShiell
  0 siblings, 0 replies; 14+ messages in thread
From: Jude DaShiell @ 2021-07-05 17:24 UTC (permalink / raw)
  To: Uwe Brauer, emacs-orgmode

So long as each piece of documentation has a continuation pointer to the
next piece of documentation in the chain I think that would work.


On Mon, 5 Jul 2021, Uwe Brauer wrote:

> >>> "JD" == Jude DaShiell <jdashiel@panix.com> writes:
>
> > Why not use functional narrative form to document complex formulas?
> > formula name:
> > formula function:
> > formula uses:
> > formula returns:
>
>
> That would be also nice, however the problem I am facing to have a long
> and complicated expression with a lot of ifs, maybe best practise would
> be to split it and distribute it over various column and add comments as
> in
>
> #+begin_src elisp
> |----+----+----+---+---+----|
> |  1 |  4 |  5 | 3 | 3 |  6 |
> |  3 | 12 | 15 | 9 | 2 | 11 |
> | 12 |  2 | 14 | 7 | 3 | 10 |
> #+TBLFM: $3=vsum($1..$2);f1:: #one comment
> #+TBLFM: $6=vsum($4..$5);f1:: #second comment
> #+end_src
>


^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05 17:12 ` Karl Voit
@ 2021-07-05 19:35   ` Uwe Brauer
  0 siblings, 0 replies; 14+ messages in thread
From: Uwe Brauer @ 2021-07-05 19:35 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 600 bytes --]

>>> "KV" == Karl Voit <devnull@Karl-Voit.at> writes:

Hi Karl,


> Hi Uwe,
> * Uwe Brauer <oub@mat.ucm.es> wrote:
>> 
>> Is there any way to document or comment such a formula, since I am sure
>> that within days I don't remember why I chose that formula?

> This is not a solution for really complex formulas. However, please
> do note that standard org has:

> Named references: https://orgmode.org/manual/References.html
> Name assignment:
> https://orgmode.org/manual/Advanced-features.html#Advanced-features

Thanks, right. That is indeed helpful but not what I really need. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: how to document/comment a complex org table formula
  2021-07-05  6:29 ` Uwe Brauer
@ 2021-07-08 20:19   ` Nick Dokos
  0 siblings, 0 replies; 14+ messages in thread
From: Nick Dokos @ 2021-07-08 20:19 UTC (permalink / raw)
  To: emacs-orgmode

Uwe Brauer <oub@mat.ucm.es> writes:

>>>> "GdaO" == General discussions about Org-mode <CHARPENTIER> writes:
>
>> Limbic answer : 
>>   - create an emacs-lisp function doing what you want
>>   - comment /ad libitum/
>>   - call this function in your spreadsheet.
>
> I hoped such a function already existed and somebody would point it out
> to me (I searched the package-list-package list but nothing came up)
>

IIUC, the function would replace the formula, so it's really the
formula in a different guise, similar to what Eric F. was talking
about: implementing the formula as a source block. Both of them put
the code in some other place, where there is space to add comments.
IOW, it's not a general-purpose function. But I may be misconstruing
what Emmanuel was suggesting.

-- 
Nick

"There are only two hard problems in computer science: cache
invalidation, naming things, and off-by-one errors." -Martin Fowler



^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2021-07-08 20:26 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-04 19:14 how to document/comment a complex org table formula Uwe Brauer
2021-07-05 14:13 ` Eric S Fraga
2021-07-05 14:45   ` Uwe Brauer
2021-07-05 14:55   ` Tim Visher
2021-07-05 15:20     ` Jude DaShiell
2021-07-05 17:10       ` Uwe Brauer
2021-07-05 17:24         ` Jude DaShiell
2021-07-05 15:39     ` Eric S Fraga
2021-07-05 17:08     ` Uwe Brauer
2021-07-05 17:12 ` Karl Voit
2021-07-05 19:35   ` Uwe Brauer
  -- strict thread matches above, loose matches on Subject: below --
2021-07-05  5:31 CHARPENTIER Emmanuel via General discussions about Org-mode.
2021-07-05  6:29 ` Uwe Brauer
2021-07-08 20:19   ` Nick Dokos

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).