Summation of effort estimates in columnview dblock

Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

Dear Org Developers,

I'm using Org 9.7.9, and I'm seeing behaviour of the (undocumented?)
"%Effort" vs. "%Effort{:}" in the column view dblock, which confuses me.

Consider this example:
---------------------------- Begin Quote -----------------------------
#+BEGIN: columnview :maxlevel 1 :indent t :format "%ITEM(Task) %EFFORT(Estimated) %EFFORT(Estimated Total){:}" :id global
| Task   | Estimated | Estimated Total |
|--------+-----------+-----------------|
| Task 1 |        2d | 7d 0:00         |
#+END:

#+BEGIN: columnview :maxlevel 2 :indent t :format "%ITEM(Task) %EFFORT(Estimated) %EFFORT(Estimated Total){:}" :id global
| Task         | Estimated | Estimated Total |
|--------------+-----------+-----------------|
| Task 1       |        2d |         7d 0:00 |
| \_  Task 1.1 |        3d |              3d |
| \_  Task 1.2 |        4d |              4d |
#+END:

* Task 1
:PROPERTIES:
:EFFORT:   2d
:END:

** Task 1.1
:PROPERTIES:
:EFFORT:   3d
:END:

** Task 1.2
:PROPERTIES:
:EFFORT:   4d
:END:
----------------------------- End Quote ------------------------------

I would have expected the estimated total (rightmost column) for "Task
1" (first body row) in both dblocks to be 9 days (instead of seven)?

What am I missing?


Many thanks in advance and cheers,

  --alexander

Re: Summation of effort estimates in columnview dblock

[Ihor Radchenko]

Alexander Adolf via "General discussions about Org-mode."
<emacs-orgmode@gnu.org> writes:

> I'm using Org 9.7.9, and I'm seeing behaviour of the (undocumented?)
> "%Effort" vs. "%Effort{:}" in the column view dblock, which confuses me.

The manual says:

    SUMMARY-TYPE
         The summary type.  If specified, the column values for parent nodes
         are computed from the children(1).

In other words, Org mode computes the value of the property for your
Task 1, from Task 1.1, and Task 1.2.  Whatever is inside Task 1 does not
matter.  In fact, it might be overwritten in some cases.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

Hello Ihor,

Many thanks for your swift response.

Ihor Radchenko <yantar92@posteo.net> writes:

> Alexander Adolf via "General discussions about Org-mode."
> <emacs-orgmode@gnu.org> writes:
>
>> I'm using Org 9.7.9, and I'm seeing behaviour of the (undocumented?)
>> "%Effort" vs. "%Effort{:}" in the column view dblock, which confuses me.
>
> The manual says:
>
>     SUMMARY-TYPE
>          The summary type.  If specified, the column values for parent nodes
>          are computed from the children(1).

The manual leaves it to the reader to figure out how the computation
happens. Nor does it mention that different column types do use
different computations, nor where to find information about the
computation applied by each column.

Btw, on the same manual page you are quoting, there is the following
footnote:
---------------------------- Begin Quote -----------------------------
(54)
If more than one summary type applies to the same property, the parent
values are computed according to the first of them.
----------------------------- End Quote ------------------------------

At least for EFFORT, this seems ambiguous. I can have

    :format "%EFFORT %EFFORT{:}"

and both columns are present, and computed differently, whereas the
footnote can easily be read as hinting to the opposite. In fact, the
footnote is correct for all time format properties _except_ EFFORT.

> In other words, Org mode computes the value of the property for your
> Task 1, from Task 1.1, and Task 1.2.  Whatever is inside Task 1 does not
> matter.

This is true for EFFORT, and all other time format (real) property
columns, but not for CLOCKSUM columns.

> In fact, it might be overwritten in some cases.

That's true.

The manual refrains from both, mentioning this fact, and from explaining
in which cases overwriting happens, however.


I can understand that there are - more or less - subtle differences, as
more columns were added over time, each with a different use-case in
mind. In hindsight, some use-cases may seem regrettably narrow, but
that's were we are; it's history.

What has added to my perceived need of help, prompting me to start this
thread, is that the manual is extremely tight lips in this area.

It would thus seem helpful to readers (hope not just myself), if the
"column attributes" section (the one with the SUMMARY-TYPE definition
you quoted) could be extended:

- With a new paragraph or two at the very end explaining how the normal
  ("%Property"), and colon summations ("%Property{:}") of time format
  properties are done, and what gets overwritten when. The section now
  ends with an example containing such a column, so the explanation
  would fit nicely there, IMHO.

- Right after that, with another new paragraph explaining how the
  summation for CLOCKSUM and CLOCKSUM_T is done in contrast, and
  mentioning that nothing is ever overwritten for these.

- The section should also mention that the footnote # 54, which I quoted
  above, does not apply to the (special-ish) EFFORT property.


Many thanks and looking forward to your thoughts,

  --alexander

Re: Summation of effort estimates in columnview dblock

[Ihor Radchenko]

Alexander Adolf <alexander.adolf@condition-alpha.com> writes:

>> The manual says:
>>
>>     SUMMARY-TYPE
>>          The summary type.  If specified, the column values for parent nodes
>>          are computed from the children(1).
>
> The manual leaves it to the reader to figure out how the computation
> happens. Nor does it mention that different column types do use
> different computations, nor where to find information about the
> computation applied by each column.

I agree that the manual can be improved. It would be nice if someone
actively using column views contributed such an improvement ;)

> Btw, on the same manual page you are quoting, there is the following
> footnote:
> ---------------------------- Begin Quote -----------------------------
> (54)
> If more than one summary type applies to the same property, the parent
> values are computed according to the first of them.
> ----------------------------- End Quote ------------------------------
>
> At least for EFFORT, this seems ambiguous. I can have
>
>     :format "%EFFORT %EFFORT{:}"
>
> and both columns are present, and computed differently, whereas the
> footnote can easily be read as hinting to the opposite. In fact, the
> footnote is correct for all time format properties _except_ EFFORT.

Not sure here. %EFFORT should not count. I tried the following:

#+COLUMNS: %EFFORT{mean} %EFFORT{+}
* Foo
:PROPERTIES:
:EFFORT:   15.0 <-- gets updated
:END:
** Bar
:PROPERTIES:
:EFFORT:   20
:END:
** Baz
:PROPERTIES:
:EFFORT:  10
:END:

>> In other words, Org mode computes the value of the property for your
>> Task 1, from Task 1.1, and Task 1.2.  Whatever is inside Task 1 does not
>> matter.
>
> This is true for EFFORT, and all other time format (real) property
> columns, but not for CLOCKSUM columns.

Yes, same for other special properties - they cannot be set in
properties drawer and are handled differently.

> What has added to my perceived need of help, prompting me to start this
> thread, is that the manual is extremely tight lips in this area.
>
> It would thus seem helpful to readers (hope not just myself), if the
> "column attributes" section (the one with the SUMMARY-TYPE definition
> you quoted) could be extended:
>
> - With a new paragraph or two at the very end explaining how the normal
>   ("%Property"), and colon summations ("%Property{:}") of time format
>   properties are done, and what gets overwritten when. The section now
>   ends with an example containing such a column, so the explanation
>   would fit nicely there, IMHO.

+1

> - Right after that, with another new paragraph explaining how the
>   summation for CLOCKSUM and CLOCKSUM_T is done in contrast, and
>   mentioning that nothing is ever overwritten for these.

+1

> - The section should also mention that the footnote # 54, which I quoted
>   above, does not apply to the (special-ish) EFFORT property.

It looks like it does apply, AFAIU.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

Ihor Radchenko <yantar92@posteo.net> writes:

> Alexander Adolf <alexander.adolf@condition-alpha.com> writes:
> [...]
>> ---------------------------- Begin Quote -----------------------------
>> (54)
>> If more than one summary type applies to the same property, the parent
>> values are computed according to the first of them.
>> ----------------------------- End Quote ------------------------------
>>
>> At least for EFFORT, this seems ambiguous. I can have
>>
>>     :format "%EFFORT %EFFORT{:}"
>>
>> and both columns are present, and computed differently, whereas the
>> footnote can easily be read as hinting to the opposite. In fact, the
>> footnote is correct for all time format properties _except_ EFFORT.
>
> Not sure here. %EFFORT should not count. I tried the following:
>
> #+COLUMNS: %EFFORT{mean} %EFFORT{+}
> * Foo
> :PROPERTIES:
> :EFFORT:   15.0 <-- gets updated
> :END:
> ** Bar
> :PROPERTIES:
> :EFFORT:   20
> :END:
> ** Baz
> :PROPERTIES:
> :EFFORT:  10
> :END:
> [...]

Consider this example:

---------------------------- Begin Quote -----------------------------
#+BEGIN: columnview :maxlevel 2 :indent t :format "%ITEM(Task) %EFFORT(Estimated) %EFFORT(Estimated Total){:} %Time_Estimate(TE) %Time_Estimate(TE 2){:}  %CLOCKSUM(Clocked) %CLOCKSUM(Clocked Total){:}" :id global
| Task         | Estimated | Estimated Total | TE |    TE 2 | Clocked | Clocked Total |
|--------------+-----------+-----------------+----+---------+---------+---------------|
| Task 1       |        2d |         7d 0:00 | 2d | 7d 0:00 | 9d 0:00 | 9d 0:00       |
| \_  Task 1.1 |        3d |              3d | 3d |      3d | 3d 0:00 | 3d 0:00       |
| \_  Task 1.2 |        4d |              4d | 4d |      4d | 4d 0:00 | 4d 0:00       |
#+END:

* Task 1
:PROPERTIES:
:EFFORT:   2d
:TIME_ESTIMATE: 2d
:END:
:LOGBOOK:
CLOCK:  => 16:00
:END:

** Task 1.1
:PROPERTIES:
:EFFORT:   3d
:Time_Estimate: 3d
:END:
:LOGBOOK:
CLOCK:  => 24:00
:END:

** Task 1.2
:PROPERTIES:
:EFFORT:   4d
:Time_Estimate: 4d
:END:
:LOGBOOK:
CLOCK:  => 32:00
:END:
----------------------------- End Quote ------------------------------

The EFFORT and TIME_ESTIMATE properties for "Task 1" will never get
updated for as long as the column specification without summary comes
first. Swap the order of columns for EFFORT, or TIME_ESTIMATE, and the
respective property of "Task 1" will get updated.

Thus, the computation of the parent values is done as expected. The only
thing that seems determined by the first column specification for a
property, is the updating of the parent property's value.

In that light, I think it could seem helpful, in addition to the three
other changes I had suggested, to update the wording of footnote 54,
too. "Parent values" seems ambiguous, as it could be read as referring
to the values in the table, whereas my experiments seem to hint to it
rather referring to the value of the parent's property.


Looking forward to your thoughts,

  --alexander

Re: Summation of effort estimates in columnview dblock

[Ihor Radchenko]

Alexander Adolf <alexander.adolf@condition-alpha.com> writes:

>> Not sure here. %EFFORT should not count. I tried the following:
>>
>> #+COLUMNS: %EFFORT{mean} %EFFORT{+}
> ...
> Consider this example:
> ...
> The EFFORT and TIME_ESTIMATE properties for "Task 1" will never get
> updated for as long as the column specification without summary comes
> first. Swap the order of columns for EFFORT, or TIME_ESTIMATE, and the
> respective property of "Task 1" will get updated.
>
> Thus, the computation of the parent values is done as expected. The only
> thing that seems determined by the first column specification for a
> property, is the updating of the parent property's value.

I confirm.
This is because the underlying code that limits the updates to "first
occurrence", suppress updates even if the first occurrence does not have
any summary.

I'd call it a bug. Although, I am not a big fan of this idea with
modifying the headings by side effect.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> [...]
> I agree that the manual can be improved. It would be nice if someone
> actively using column views contributed such an improvement ;)
> [...]

Ok, I've given it a try.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-better-explain-columnview-column-.patch --]
[-- Type: text/x-patch, Size: 4274 bytes --]

From 4bb89a24269ee2ef42ed2b1c5713faa37b33f72d Mon Sep 17 00:00:00 2001
From: Alexander Adolf <alexander.adolf@condition-alpha.com>
Date: Sat, 17 Aug 2024 18:29:51 +0200
Subject: [PATCH] doc/org-manual.org: better explain columnview column summary
 types

* doc/org-manual.org (Column attributes): Shed more words on how
summary types for columnview columns work, which property values are
taken into account, and which property values get updated in the
buffer under what circumstances.
---
 doc/org-manual.org | 39 +++++++++++++++++++++++++++++++++++----
 etc/ORG-NEWS       |  6 ++++++
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebca..b435a4526 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5734,10 +5734,8 @@ optional.  The individual parts have the following meaning:
 
 - {{{var(SUMMARY-TYPE)}}} ::
 
-  The summary type.  If specified, the column values for parent nodes
-  are computed from the children[fn:: If more than one summary type
-  applies to the same property, the parent values are computed
-  according to the first of them.].
+  The summary type.  If specified, the column and property values for
+  ancestor nodes are computed from their descendants.
 
   Supported summary types are:
 
@@ -5810,6 +5808,39 @@ children have been checked.  The =CLOCKSUM= and =CLOCKSUM_T= columns
 are special, they list the sums of CLOCK intervals in the subtree,
 either for all clocks or just for today.
 
+When using summary types for non-special properties like the
+=Time_Estimate= column in the example, the collection of data for the
+summary in each subtree within scope will start at the furthest
+descendant nodes which have the respective property.  When any of
+their sibling nodes also have the property in question, all the
+siblings' values of the property are used to compute the summary
+result according to the summary type specified.  Then the closest
+ancestor node which also has the respective property is located, and
+the buffer is modified as the value of that node's property is updated
+with the summary result of its descendant nodes.  This process is
+repeated starting from each updated node, until the top of each
+subtree has been reached, and all branches of the subtree have been
+traversed.  Since the property values of ancestor nodes get updated in
+this process, only the furthest descendant nodes which have the
+respective property along each subtree axis will contribute to the
+summary results.
+
+When a non-special property appears more than once in a columns
+definition, and with different summary type specifications (including
+with none), the values of that property present on any ancestor nodes
+will be updated according to the summary type specification (if any)
+of the first instance of the property in the columns definition.
+Hence, when the first occurrence of a property in a columns definition
+has no summary type specification, the property values of ancestor
+nodes will not be updated.
+
+When using summary types with columns for the special properties
+=CLOCKSUM= and =CLOCKSUM_T=, the summary process will be different.
+First, as these are special properties that are not stored in property
+drawers, no updates will be made to any nodes involved.  Secondly, the
+summary value will be computed not just from the furthest descendant
+nodes, but from the special property values of all nodes in a subtree.
+
 *** Using column view
 :PROPERTIES:
 :DESCRIPTION: How to create and use column view.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 6f858f3ca..3e81f0f46 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -187,6 +187,12 @@ This way, attachments will remain accessible when opening symlinked Org file.
 When no attach dir exists, Org mode will still prefer creating it in
 the "default" directory - where the symlink is located.
 
+*** improved description of how summary types in column definitions for columnview work
+
+Made the manual more explicit about how summary types work for
+non-special and special properties, and when which property's value
+gets updated in the buffer when a columnview is updated.
+
 * Version 9.7
 
 ** Important announcements and breaking changes
-- 
2.39.3 (Apple Git-146)

Re: Summation of effort estimates in columnview dblock

[Ihor Radchenko]

Alexander Adolf <alexander.adolf@condition-alpha.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> [...]
>> I agree that the manual can be improved. It would be nice if someone
>> actively using column views contributed such an improvement ;)
>> [...]
>
> Ok, I've given it a try.

Thanks!

> +When using summary types for non-special properties like the
> +=Time_Estimate= column in the example, the collection of data for the
> +summary in each subtree within scope will start at the furthest
> ...

Several comments:

1. Nitpick: siblings's (it is current Emacs grammar convention in the manuals)
2. Please add some examples with illustration. Now, this description
   feels too dense

> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS

No need. This change is not introducing anything new feature-wise.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

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


Thanks for your comments!

Ihor Radchenko <yantar92@posteo.net> writes:

> [...]
> Several comments:
>
> 1. Nitpick: siblings's (it is current Emacs grammar convention in the
> manuals)

Fixed.

> 2. Please add some examples with illustration. Now, this description
>    feels too dense

Having written International technical standards for 20 years, I
consider this flattery. ;-))

Example included.

>> --- a/etc/ORG-NEWS
>> +++ b/etc/ORG-NEWS
>
> No need. This change is not introducing anything new feature-wise.
> [...]

Removed.

Fingers crossed,

  --alexander


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-better-explain-columnview-column-.patch --]
[-- Type: text/x-patch, Size: 8092 bytes --]

From d9e467207f333fd925bd9090228808da54205280 Mon Sep 17 00:00:00 2001
From: Alexander Adolf <alexander.adolf@condition-alpha.com>
Date: Sat, 17 Aug 2024 18:29:51 +0200
Subject: [PATCH] doc/org-manual.org: better explain columnview column summary
 types

* doc/org-manual.org (Column attributes): Shed more words on how
summary types for columnview columns work, which property values are
taken into account, and which property values get updated in the
buffer under what circumstances.
---
 doc/org-manual.org | 211 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 207 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebca..97ae0867c 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5734,10 +5734,8 @@ optional.  The individual parts have the following meaning:
 
 - {{{var(SUMMARY-TYPE)}}} ::
 
-  The summary type.  If specified, the column values for parent nodes
-  are computed from the children[fn:: If more than one summary type
-  applies to the same property, the parent values are computed
-  according to the first of them.].
+  The summary type.  If specified, the column and property values for
+  ancestor nodes are computed from their descendants.
 
   Supported summary types are:
 
@@ -5810,6 +5808,211 @@ children have been checked.  The =CLOCKSUM= and =CLOCKSUM_T= columns
 are special, they list the sums of CLOCK intervals in the subtree,
 either for all clocks or just for today.
 
+When using summary types for non-special properties like the
+=Time_Estimate= column in the example, the collection of data for the
+summary in each subtree within scope will start at the furthest
+descendant nodes which have the respective property.  When any of
+their sibling nodes also have the property in question, all the
+siblings's values of the property are used to compute the summary
+result according to the summary type specified.  Then the closest
+ancestor node which also has the respective property is located, and
+the buffer is modified as the value of that node's property is updated
+with the summary result of its descendant nodes.  This process is
+repeated starting from each updated node, until the top of each
+subtree has been reached, and all branches of the subtree have been
+traversed.  Since the property values of ancestor nodes get updated in
+this process, only the furthest descendant nodes which have the
+respective property along each subtree axis will contribute to the
+summary results.
+
+When a non-special property appears more than once in a columns
+definition, and with different summary type specifications (including
+with none), the values of that property present on any ancestor nodes
+will be updated according to the summary type specification (if any)
+of the first instance of the property in the columns definition.
+Hence, when the first occurrence of a property in a columns definition
+has no summary type specification, the property values of ancestor
+nodes will not be updated.
+
+When using summary types with columns for the special properties
+=CLOCKSUM= and =CLOCKSUM_T=, the summary process will be different.
+First, as these are special properties that are not stored in property
+drawers, no updates will be made to any nodes involved.  Secondly, the
+summary value will be computed not just from the furthest descendant
+nodes, but from the special property values of all nodes in a subtree.
+
+The following example illustrates how special, and non-special
+properties contribute to the summary results, and how the property
+values of the headlines get updated.  Consider the following buffer
+contents (the =#+BEGIN= must be on a single line, and is wrapped here
+for readability only):
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+When the colmnview dynamic block is now updated by {{{kbd(C-c C-c)}}}
+or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) with the cursor
+somewhere on the =#+BEGIN= line, the buffer contents shown below will
+result.  Note how the values of the =EFFORT= property of =Task 1= and
+=Task 1.1= were updated to eleven days, and to seven days
+respectively.  Note also, how the =CLOCKSUM= of thirteen days for
+=Task 1= includes the two days which were clocked on the headline
+itself.  Comparing the two estimated, and the two clocksum columns
+with each other in the table shows how the first summary type
+specification determines the summary calculation for a given property.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+| Task             | Estimated Total | Estimated | Clocked Total | Clocked  |
+|------------------+-----------------+-----------+---------------+----------|
+| Task 1           |        11d 0:00 |  11d 0:00 | 13d 0:00      | 13d 0:00 |
+| \_  Task 1.1     |         7d 0:00 |   7d 0:00 | 7d 0:00       | 7d 0:00  |
+| \_    Task 1.1.1 |              3d |        3d | 3d 0:00       | 3d 0:00  |
+| \_    Task 1.1.2 |              4d |        4d | 4d 0:00       | 4d 0:00  |
+| \_  Task 1.2     |              4d |        4d | 4d 0:00       | 4d 0:00  |
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   11d 0:00
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   7d 0:00
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+        CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+Starting again from the same initial example buffer content, but with
+a modified =#+BEGIN= line that swaps the order of the two estimated,
+and the two clocksum columns, the result of updating the columnview
+dynamic block will be as shown below.  Note the different results in
+the estimated column without a summary type.  Also note that the
+=EFFORT= properties of the =Task 1= and =Task 1.1= headlines were not
+updated in this case, because the first column specification for the
+=EFFORT= property has no summary type.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated) %EFFORT(Estimated Total){:} \
+          %CLOCKSUM(Clocked) %CLOCKSUM(Clocked Total){:}" :id global
+| Task             | Estimated | Estimated Total | Clocked  | Clocked Total |
+|------------------+-----------+-----------------+----------+---------------|
+| Task 1           |        2d |        11d 0:00 | 13d 0:00 | 13d 0:00      |
+| \_  Task 1.1     |        2d |         7d 0:00 | 7d 0:00  | 7d 0:00       |
+| \_    Task 1.1.1 |        3d |              3d | 3d 0:00  | 3d 0:00       |
+| \_    Task 1.1.2 |        4d |              4d | 4d 0:00  | 4d 0:00       |
+| \_  Task 1.2     |        4d |              4d | 4d 0:00  | 4d 0:00       |
+#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
 *** Using column view
 :PROPERTIES:
 :DESCRIPTION: How to create and use column view.
-- 
2.39.3 (Apple Git-146)

[PATCH] Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

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

Ping?

(NOTE: Updated documentation patch below has one very minor typo fixed. END NOTE)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-better-explain-columnview-column-.patch --]
[-- Type: text/x-patch, Size: 8093 bytes --]

From 1a862dd5af174af480cedf35fbed94a7e4dfb69b Mon Sep 17 00:00:00 2001
From: Alexander Adolf <alexander.adolf@condition-alpha.com>
Date: Sat, 17 Aug 2024 18:29:51 +0200
Subject: [PATCH] doc/org-manual.org: better explain columnview column summary
 types

* doc/org-manual.org (Column attributes): Shed more words on how
summary types for columnview columns work, which property values are
taken into account, and which property values get updated in the
buffer under what circumstances.
---
 doc/org-manual.org | 211 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 207 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 6cf51ebca..18fc9a4fa 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5734,10 +5734,8 @@ optional.  The individual parts have the following meaning:
 
 - {{{var(SUMMARY-TYPE)}}} ::
 
-  The summary type.  If specified, the column values for parent nodes
-  are computed from the children[fn:: If more than one summary type
-  applies to the same property, the parent values are computed
-  according to the first of them.].
+  The summary type.  If specified, the column and property values for
+  ancestor nodes are computed from their descendants.
 
   Supported summary types are:
 
@@ -5810,6 +5808,211 @@ children have been checked.  The =CLOCKSUM= and =CLOCKSUM_T= columns
 are special, they list the sums of CLOCK intervals in the subtree,
 either for all clocks or just for today.
 
+When using summary types for non-special properties like the
+=Time_Estimate= column in the example, the collection of data for the
+summary in each subtree within scope will start at the furthest
+descendant nodes which have the respective property.  When any of
+their sibling nodes also have the property in question, all the
+siblings's values of the property are used to compute the summary
+result according to the summary type specified.  Then the closest
+ancestor node which also has the respective property is located, and
+the buffer is modified as the value of that node's property is updated
+with the summary result of its descendant nodes.  This process is
+repeated starting from each updated node, until the top of each
+subtree has been reached, and all branches of the subtree have been
+traversed.  Since the property values of ancestor nodes get updated in
+this process, only the furthest descendant nodes which have the
+respective property along each subtree axis will contribute to the
+summary results.
+
+When a non-special property appears more than once in a columns
+definition, and with different summary type specifications (including
+with none), the values of that property present on any ancestor nodes
+will be updated according to the summary type specification (if any)
+of the first instance of the property in the columns definition.
+Hence, when the first occurrence of a property in a columns definition
+has no summary type specification, the property values of ancestor
+nodes will not be updated.
+
+When using summary types with columns for the special properties
+=CLOCKSUM= and =CLOCKSUM_T=, the summary process will be different.
+First, as these are special properties that are not stored in property
+drawers, no updates will be made to any nodes involved.  Secondly, the
+summary value will be computed not just from the furthest descendant
+nodes, but from the special property values of all nodes in a subtree.
+
+The following example illustrates how special, and non-special
+properties contribute to the summary results, and how the property
+values of the headlines get updated.  Consider the following buffer
+contents (the =#+BEGIN= must be on a single line, and is wrapped here
+for readability only):
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+When the colmnview dynamic block is now updated by {{{kbd(C-c C-c)}}}
+or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) with the cursor
+somewhere on the =#+BEGIN= line, the buffer contents shown below will
+result.  Note how the values of the =EFFORT= property of =Task 1= and
+=Task 1.1= were updated to eleven days, and to seven days
+respectively.  Note also, how the =CLOCKSUM= of thirteen days for
+=Task 1= includes the two days which were clocked on the headline
+itself.  Comparing the two estimated, and the two clocksum columns
+with each other in the table shows how the first summary type
+specification determines the summary calculation for a given property.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated Total){:} %EFFORT(Estimated) \
+          %CLOCKSUM(Clocked Total){:} %CLOCKSUM(Clocked)" :id global
+| Task             | Estimated Total | Estimated | Clocked Total | Clocked  |
+|------------------+-----------------+-----------+---------------+----------|
+| Task 1           |        11d 0:00 |  11d 0:00 | 13d 0:00      | 13d 0:00 |
+| \_  Task 1.1     |         7d 0:00 |   7d 0:00 | 7d 0:00       | 7d 0:00  |
+| \_    Task 1.1.1 |              3d |        3d | 3d 0:00       | 3d 0:00  |
+| \_    Task 1.1.2 |              4d |        4d | 4d 0:00       | 4d 0:00  |
+| \_  Task 1.2     |              4d |        4d | 4d 0:00       | 4d 0:00  |
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   11d 0:00
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   7d 0:00
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+        CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
+Starting again from the same initial example buffer content, but with
+a modified =#+BEGIN= line that swaps the order of the two estimated,
+and the two clocksum columns, the result of updating the columnview
+dynamic block will be as shown below.  Note the different results in
+the estimated column without a summary type.  Also note that the
+=EFFORT= properties of the =Task 1= and =Task 1.1= headlines were not
+updated in this case, because the first column specification for the
+=EFFORT= property has no summary type.
+
+#+begin_example
+,#+BEGIN: columnview :indent t :format "%ITEM(Task) \
+          %EFFORT(Estimated) %EFFORT(Estimated Total){:} \
+          %CLOCKSUM(Clocked) %CLOCKSUM(Clocked Total){:}" :id global
+| Task             | Estimated | Estimated Total | Clocked  | Clocked Total |
+|------------------+-----------+-----------------+----------+---------------|
+| Task 1           |        2d |        11d 0:00 | 13d 0:00 | 13d 0:00      |
+| \_  Task 1.1     |        2d |         7d 0:00 | 7d 0:00  | 7d 0:00       |
+| \_    Task 1.1.1 |        3d |              3d | 3d 0:00  | 3d 0:00       |
+| \_    Task 1.1.2 |        4d |              4d | 4d 0:00  | 4d 0:00       |
+| \_  Task 1.2     |        4d |              4d | 4d 0:00  | 4d 0:00       |
+,#+END:
+
+,* Task 1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+:LOGBOOK:
+CLOCK:  => 48:00
+:END:
+
+,** Task 1.1
+:PROPERTIES:
+:EFFORT:   2d
+:END:
+
+,*** Task 1.1.1
+:PROPERTIES:
+:EFFORT:   3d
+:END:
+:LOGBOOK:
+CLOCK:  => 72:00
+:END:
+
+,*** Task 1.1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+
+,** Task 1.2
+:PROPERTIES:
+:EFFORT:   4d
+:END:
+:LOGBOOK:
+CLOCK:  => 96:00
+:END:
+#+end_example
+
 *** Using column view
 :PROPERTIES:
 :DESCRIPTION: How to create and use column view.
-- 
2.39.3 (Apple Git-146)

Re: [PATCH] Re: Summation of effort estimates in columnview dblock

[Ihor Radchenko]

Alexander Adolf <alexander.adolf@condition-alpha.com> writes:

> From 1a862dd5af174af480cedf35fbed94a7e4dfb69b Mon Sep 17 00:00:00 2001
> From: Alexander Adolf <alexander.adolf@condition-alpha.com>
> Date: Sat, 17 Aug 2024 18:29:51 +0200
> Subject: [PATCH] doc/org-manual.org: better explain columnview column summary
>  types
> ...
> +When using summary types for non-special properties like the
> +=Time_Estimate= column in the example, the collection of data for the
> ...
> +The following example illustrates how special,

I'd start from a simplified description of what is happening, followed
by the example, and then formal definition.

Otherwise, reading from top to button is still difficult.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH] Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

Ihor Radchenko <yantar92@posteo.net> writes:

> [...]
>> +When using summary types for non-special properties like the
>> +=Time_Estimate= column in the example, the collection of data for the
>> ...
>> +The following example illustrates how special,
>
> I'd start from a simplified description of what is happening, followed
> by the example, and then formal definition.
>
> Otherwise, reading from top to button is still difficult.
> [...]

It remains tricky to explain, as there quite a couple of ifs and whens.
As an aside: my experience seems to suggest that the product of
"complexity of implementation" and "complexity of documentation" is
likely constant.

What I suggested seems like an improvement over the status-quo, as it
explains things that are currently not mentioned. Frankly, I don't
intend to spend more time on this. Thus, in case you wanted to give it a
try to improve it, I'd certainly welcome that.


Hoping to have helped,

  --alexander

Re: [PATCH] Re: Summation of effort estimates in columnview dblock

[Alexander Adolf via General discussions about Org-mode.]

Ihor Radchenko <yantar92@posteo.net> writes:

> [...]
> I'd start from a simplified description of what is happening, followed
> by the example, and then formal definition.
>
> Otherwise, reading from top to button is still difficult.
> [...]

Here is another take: instead of the lengthy explanations I had offered
previously, what about instead just adding the below lines at the end of
the "Property Inheritance" section:

---------------------------- Begin Quote -----------------------------

- ~EFFORT~ ::

  #+cindex: @samp{EFFORT}, property
  For column views, an estimated effort set through an =EFFORT=
  property also applies to its ancestors.  =EFFORT= properties present
  on any ancestors may get updated depending on the summary types for
  =EFFORT= columns in the column view.

----------------------------- End Quote ------------------------------


Cheers,

  --alexander