Real Twig allows QSM variable names to be standardized across
TreeQSM, SimpleForest, Treegraph, and aRchi. This is done with the
standardize_qsm() function, and creates a more consistent
experience when working with QSMs. Below are detailed definitions of the
variable names using the rTwig QSM format.
start: This defines the x, y, z
coordinates at the center of the cylinder’s base.
axis: This defines the x, y, z axis
formed between the cylinder’s base and top.
end: This defines the x, y, z
coordinates at the center of the cylinder’s top.
id: The first cylinder id is 1 and is
the base of the tree. The largest id value is equal to the number of
rows in the data frame.
parent: This shows the relationships
between individual cylinders in the QSM. The parent of the first
cylinder is always zero, because the base of the tree has no parent.
Within a branch, parent cylinders are always one less than their child.
At the base of a branch, the parent cylinder is the cylinder the branch
is connected to.
radius: This is the radius of the
cylinder in meters.
raw_radius: This is the radius of the
cylinder before any possible modifications. If using TreeQSM, this is
always the UnmodRadius column. If using SimpleForest or
Treegraph, this is a copy of the radius before Real Twig is run. Real
Twig always uses this radius in its corrections.
modified: This is an average index of
if the cylinder radius was an outlier and modified with Real Twig across
the QSM paths. A value of 0 indicates that the cylinder was never
modified in any path, while a value of 1 indicates that it was modified
in every path. A value in between 0 and 1 was modified in only some, but
not all of the paths.
length: This is the length of the
cylinder in meters.
branch: A branch is defined as starting
at a new branch order and continuing until a twig is reached. This
definition is what TreeQSM and Treegraph use. SimpleForest branches are
converted to this definition when standardizing the QSM. The first
branch is always the main stem under the rTwig format. Treegraph QSMs
retain their definition of branches. TreeQSM and SimpleForest are
numbered consecutively in order of the cylinder ids.
branch_position: This is an index of
the cylinder’s position within a branch. This is the same as TreeQSM’s
PositionInBranch definition. The first position is always the
base of the branch, and the last position is always a twig or the branch
end in the case of a broken branch.
branch_order: This is the order of
every branch. The smallest branch order zero is always the main stem.
First order branches are connected to the main stem, and so on a so
forth for higher order branches. A new branch order always begins at a
new branching fork, continues to a twig or end of a broken branch, and
is one greater than the parent order. This definition is consistent
between TreeQSM, SimpleForest, and Treegraph, but the rTwig format
always defines the main stem as order zero for consistency.
reverse_order: This is the reverse
branch order (RBO). Traditional branch ordering is relative to the main
stem, and does not tell us anything about the position or size of the
branch. Small twigs and large branches can both be first order branches
if they are connected to the main stem under the traditional definition.
RBO solves this problem by considering the relative position of branches
within a QSM. RBO assigns a value of one at the end of twigs or broken
branches, and works backwards until the base of the tree is reached,
which is assigned the highest RBO. The RBO of any branch is the maximum
segment (internode) depth relative to the twigs in a tree.
branch_alt: This is the alternate
branch index. Alternate branch zero is always the main stem. The rest of
the branches are first order branches and all of their children. This is
similar to cutting the first order branches off with a saw and labeling
them consecutively. If using a SimpleForest QSM, this is the old
branchID column updated so that the main stem is index
zero.
segment: A segment (internode) is a
portion of a tree between branching forks (nodes). A new segment begins
at every branch fork. Cylinders are a part of a segment until the
cylinder has more than one child and a new segment is created. The rTwig
format always defines the base of the tree as the first segment.
parent_segment: This shows the
relationships between segments in the QSM. The parent segment of the
first segment is always zero, because the first segment (the base of the
tree) has no parent segment. The parent segment is the node the current
segment forked from.
total_children: This is the total
number of cylinders supported by the given cylinder. This is useful to
find where branches fork. A value of one means that there are no
branching forks. A value of two means that there is one branching fork,
etc.
growth_length: This is the growth
length in meters of any given cylinder. Growth length can be defined as
the sum of the lengths of the cylinders supported by the given cylinder.
We can visualize growth length by cutting a tree with a saw at any given
point. The cumulative length of this cut portion is the growth length
where the part of the tree was cut. The growth length of the base of the
tree is the sum of the lengths of all the cylinders in the QSM. The
growth length of a twig is simply the length of its cylinder. Growth
length reflects a measurement that could be taken on a real tree, but is
easier to obtain with QSMs.
base_distance: This is the distance in
meters of any given cylinder from the base of the tree. This distance is
calculated by taking the simplest complete path from the given cylinder
to the base of the tree.
twig_distance: This is the average
distance in meters a given cylinder is away from all supported twigs.
This is calculated by finding all complete simple paths from the given
cylinder to the supported twigs, summing the lengths, and then dividing
by the number of paths.
vessel_volume: This is the theoretical
cumulative volume of living vessels supported by a given cylinder based
on allometric scaling theory. It is the sum of pipe_area *
length for all supported cylinders.
pipe_area: This is the theoretical
cross-sectional area of a given cylinder based on allometric scaling
theory. The units and values are the total number of supported
twigs.
pipe_radius: This is the theoretical
radius of a given cylinder based on allometric scaling theory. The units
and values are the square root of the total number of supported
twigs.