GroIMP wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== GROGRA Functions for structural analysis ======

GroIMP contains some of the functions from its predecessor GROGRA which can be used to statistically analyze the current structure (e.g. with regard to lengths, angles, ect.). These functions can be found under <key>Panels</key> -> <key>RGG Panels</key> -> <key>GROGRA Functions</key>:
{{:tutorials:grogra_panel.png?400|}}

Some of these functions are also explained in this {{ :tutorials:grogra_reference_guide.pdf | initial GROGRA documentation }} (page 98f.) and some further expansions in this {{ :tutorials:dzierzon_et_al_2003.pdf | paper}} (https://doi.org/10.14214/sf.510) and also {{ :tutorials:oppelt_kurth_godbold_2001.pdf | here}} (only topological analysis). This wiki provides a compressed form of the information in these sources, which are partially outdated. For example, not all the functions mentioned in the GROGRA documentation are 1:1 available in GroIMP. Also some of the the features of the different functions appear to be broken or they don't work at all (at least with the basic RGG model tree). This is because they were designed for some specific purpose that was lost over time. So use them at your own discretion. If you are really interested in one specific function, I recommend to check out the source code of the functions [[https://gitlab.com/grogra/groimp-plugins/RGG/-/blob/master/src/main/java/de/grogra/grogra/Analysis.java?ref_type=heads | here]] to learn what it actually does. If you find information that is not covered already by this wiki, please add it!

===== Available functions, their purpose and output =====
{{:tutorials:functions.png?400|}}

The functions are applied by clicking on their name in the <key>Analysis</key> drop-down menu. They all output a table that can be saved as e.g. .txt or .csv for further analysis in e.g. R via <key>data</key> -> <key>exporttable</key>. The <key>Analysis (shiny)</key> menu provides the same functions and is supposed to somehow integrate with R, but I could not figure out how it works. Please add this info if you find it. {{:tutorials:guertler_msc.pdf |  This thesis}} provides some information on that but it did not really help me (under Windows).

This is what you can do:

==== List of all shoots ====
Gives basic information for every shoot: ID, predecessor, length, diameter, geometric coordinates ect. Similar to a dtd or QSM modelling tool data format.

==== Elementary ====
Gives fundamental parameters aggregated over the entire structure: number of elementary units, number of terminal units, total length, volume, surface area and others. Most of these parameters are self-explanatory. The "average contraction factor" is the mean value of the ratios l/l_m, where l is the length of an elementary unit not prolonging the axis of its mother unit, and l_m the length of the mother unit. (Prolongation of an axis is assumed if both units have the same branching order.) The "average branching angle" does also refer only to non-prolonging,
i.e. properly branching units.

==== Pathlength analysis ====
Table enabling analysis of diameter-pathlength relation according to {{ :tutorials:mechanical_design.pdf | McMahon and Kronauer}}
(1976) (https://doi.org/10.1016/0022-5193(76)90182-X) and other approaches for tapering. It gives for each elementary unit:
  * Number of the elementary unit.
  * Diameter db of the unit.
  * Average length of all paths emerging from that unit and going to a terminal unit (= unit without daughters).
  * Length of the longest path of that kind.
  * Number of the terminal unit where the longest path ends.

==== Basic tree parameters ====
<color #ed1c24>No documentation found</color>
Appears similar to the Elementary analysis, but with some additional variables related to crown geometry and something called S1.

==== Coordinates ====
<color #ed1c24>No documentation found</color>
From looking at the source code, gives the x- and y-coordinates for the base of every shoot.

==== Diameter table ====
<color #ed1c24>No documentation found</color>
Appears to give for each shoot that has some daughters the diameters of these daughters.

==== Elementary analysis of several trees ====
Similar to the basic elementary analysis but even more compressed and intended to be used on multiple structures at once. Contains a BHD variable, which might be interesting (<color #ed1c24>BHD appears to be broken, let me know if it works for you</color>)

==== Branching positions ====
According to the Dzierzon et al. paper, gives for each elementary unit: number of daughter units and their positions (for further processing). Actually, it appears to only give the number of daughters for each unit.

==== Number of daughter shoots ====
Gives a table of elementary units with non-negative branching order (Similar to the list of shoots). Each line of the table corresponds to an elementary unit (shoot). However, this function also gives some interesting additional information:

  * The age a of the unit, calculated as a = gmax - g, where g is the generative distance of the unit and gmax the maximal generative distance appearing in the structure which is analyzed,
  * The number of daughter units of the unit (including axis-prolonging daughters)
  * The number of subapical daughter units of the unit, i.e. daughter shoots with q-value less than 0.2 and branching order b + 1 (non-prolonging) (q is a real number between 0 and 1 representing the relative position of the unit's basis along the mother unit (0 = unit emerges at the top of the mother unit, 1 = unit emerges at its bottom), see p.80 of the GROGRA guide for these kind of shoot parameters if you encounter them elsewhere)
  * The number of medial daughter units of the unit, i.e. daughter shoots with 0.2 <= q < 0.8
  * The number of basal daughter units of the unit, i.e. daughter shoots with q >= 0.8.

Note that the number of subapical, medial, and basal shoots must not sum up to the number of daughter units of the unit, because there can be a daughter unit prolonging the axis of the current unit (i.e. having the same branching order b). Elementary units with negative branching order (e.g., the fictitious basal shoots of dtd-read or hand specied structures) are not analyzed and do not appear as lines in the table.

==== Shoot population ====
<color #ed1c24>No documentation found and appears to be broken? Doesn't do anything in my testing</color>

==== Length and angles ====
GroIMP will ask for a "Cluster distance" in m. This distance refers to an iterative algorithm which will be applied to each elementary unit of the analyzed structure, and which has the purpose to collect all daughter units of that unit lying sufficiently close together into a "cluster", identifiable by a cluster index. The cluster index 0 is reserved for axis-prolonging daughters, i.e. units having the same branching order as the unit considered. The clusters of side branches are numbered by 1, 2, ... according to the position of the cluster at the elementary unit (the more basal the position, the higher the number).

The clustering algorithm is performed for each elementary unit in the following manner: First, the absolute positions of all daughter unit basal points at the unit at work are collected in an ordered list. Then, the two entries in the list having the smallest distance from each other are replaced by their mean value, if their distance is smaller than the clustering distance. This step is repeated until all mutual distances of entries are greater or equal the clustering distance. At last, all daughter units with identical entries are conceived as belonging to the same cluster and get the same cluster index.

The output table hold this cluster index for each element besides additional information regarding the position of the cluster, the relative position of the element within the cluster and attributes of elements in fairly unique topological relationships to the respective unit: this analysis holds the concept of a "big brother" and "cousin" element. Reference the GROGRA guide p.102f. for further explanations on this concept, here are just the figures explaining what a big brother and a cousin is so you know if this might be relevant for you:
{{:tutorials:bigbrother_of_u.png?100| Big brother (b) of unit u}}
Big brother (b) of unit u
{{:tutorials:cousin_of_u.png?100| Cousin (c) of unit u}}
Cousin (c ) of unit u

==== Crown layers ====
<color #ed1c24>No documentation found and appears to be broken</color>
GroIMP will ask for user input to define the height of horizontal "slices" in which the structure will be analyzed. When you decline the equidistant layers, it will ask for 3 layer bounds resulting in 4 layers total. When using equidistant layers, you can specify the the layer height but it will always result in a 20m overall zone. The output should apparently contain the sum of element lengths in each layer, but in my testing all the sum only appears in layer #1, all other layers have 0 length sum.


==== Stem analysis ====
This function provides a table with a discretized description of the main stem (= segments of branching order 0) with diameter information for different heights (= Stem taper table). In the 90s, there was a program for the Silicon Graphics workstation called GROBOL (growth of boles engine), which could display and analyze the stem using this table (I am only mentioning this here because this software pops up in the sources occasionally, but don't bother searching for it). 
==== Distribution analysis ====
Frequency tables: elementary units, compound units, axes, el. units per compound unit etc., in total and for each branching order. <color #ed1c24>Appears to be a bit broken, can produce some unexpected results!</color>
==== Topological analysis ====
Number of components, number of (graph-theoretical) links, maximal and average topological depth and other topological parameters, see {{ :tutorials:oppelt_kurth_godbold_2001.pdf | Oppelt et al. (2001)}}
==== Axes analysis ====
<color #ed1c24>Extremely broken, crashes my GroIMP every time.</color> Is supposed to give parameters for each axis, including average interbranch distance and its standard deviation.