Real Twig allows QSM variable names and metrics to be standardizedacross TreeQSM, SimpleForest, Treegraph, and aRchi. This is done withthestandardise_qsm() andtree_metrics()functions, creating a consistent experience when working with QSMs.Below are detailed definitions of the standard variable names inrTwig.
All of the variables shown here are created with theupdate_cylinders() function, which should be run as soon asa QSM is imported with rTwig. Unless,standardise_qsm() isrun, the variable names will vary depending on the particular QSMsoftware used.
start: This defines the x, y, zcoordinates at the center of the cylinder’s base.
axis: This defines the x, y, z axisformed between the cylinder’s base and top.
end: This defines the x, y, zcoordinates at the center of the cylinder’s top.
id: The first cylinder id is 1 and isthe base of the tree. The largest id value is equal to the number ofrows in the data frame.
parent: This shows the relationshipsbetween individual cylinders in the QSM. The parent of the firstcylinder 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 branchis connected to.
radius: This is the radius of thecylinder in meters.
raw_radius: This is the radius of thecylinder before any possible modifications. If using TreeQSM, this isalways theUnmodRadius column. If using SimpleForest orTreegraph, this is a copy of the radius before Real Twig is run. RealTwig always uses this radius in its corrections.
modified: This is an average index ofif the cylinder radius was an outlier and modified with Real Twig acrossthe QSM paths. A value of 0 indicates that the cylinder was nevermodified in any path, while a value of 1 indicates that it was modifiedin every path. A value in between 0 and 1 was modified in only some, butnot all of the paths.
length: This is the length of thecylinder in meters.
branch: A branch is defined as startingat a new branch order and continuing until a twig is reached. Thisdefinition is what TreeQSM and Treegraph use. SimpleForest branches areconverted to this definition when standardizing the QSM. The firstbranch is always the main stem under the rTwig format. Treegraph QSMsretain their definition of branches. TreeQSM and SimpleForest arenumbered consecutively in order of the cylinder ids.
branch_position: This is an index ofthe cylinder’s position within a branch. This is the same as TreeQSM’sPositionInBranch definition. The first position is always thebase of the branch, and the last position is always a twig or the branchend in the case of a broken branch.
branch_order: This is the order ofevery branch. The smallest branch order zero is always the main stem.First order branches are connected to the main stem, and so on a soforth for higher order branches. A new branch order always begins at anew branching fork, continues to a twig or end of a broken branch, andis one greater than the parent order. This definition is consistentbetween TreeQSM, SimpleForest, and Treegraph, but the rTwig formatalways defines the main stem as order zero for consistency.
reverse_order: This is the reversebranch order (RBO). Traditional branch ordering is relative to the mainstem, and does not tell us anything about the position or size of thebranch. Small twigs and large branches can both be first order branchesif they are connected to the main stem under the traditional definition.RBO solves this problem by considering the relative position of brancheswithin a QSM. RBO assigns a value of one at the end of twigs or brokenbranches, and works backwards until the base of the tree is reached,which is assigned the highest RBO. The RBO of any branch is the maximumsegment (internode) depth relative to the twigs in a tree.
branch_alt: This is the alternatebranch index. Alternate branch zero is always the main stem. The rest ofthe branches are first order branches and all of their children. This issimilar to cutting the first order branches off with a saw and labelingthem consecutively. If using a SimpleForest QSM, this is the oldbranchID column updated so that the main stem is indexzero.
segment: A segment (internode) is aportion of a tree between branching forks (nodes). A new segment beginsat every branch fork. Cylinders are a part of a segment until thecylinder has more than one child and a new segment is created. The rTwigformat always defines the base of the tree as the first segment.
parent_segment: This shows therelationships between segments in the QSM. The parent segment of thefirst segment is always zero, because the first segment (the base of thetree) has no parent segment. The parent segment is the node the currentsegment forked from.
total_children: This is the totalnumber of cylinders supported by the given cylinder. This is useful tofind where branches fork. A value of one means that there are nobranching forks. A value of two means that there is one branching fork,etc.
growth_length: This is the growthlength in meters of any given cylinder. Growth length can be defined asthe 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 givenpoint. The cumulative length of this cut portion is the growth lengthwhere the part of the tree was cut. The growth length of the base of thetree is the sum of the lengths of all the cylinders in the QSM. Thegrowth length of a twig is simply the length of its cylinder. Growthlength reflects a measurement that could be taken on a real tree, but iseasier to obtain with QSMs.
base_distance: This is the distance inmeters of any given cylinder from the base of the tree. This distance iscalculated by taking the simplest complete path from the given cylinderto the base of the tree.
twig_distance: This is the averagedistance in meters a given cylinder is away from all supported twigs.This is calculated by finding all complete simple paths from the givencylinder to the supported twigs, summing the lengths, and then dividingby the number of paths.
vessel_volume: This is the theoreticalcumulative volume of living vessels supported by a given cylinder basedon allometric scaling theory. It is the sum ofpipe_area *length for all supported cylinders.
pipe_area: This is the theoreticalcross-sectional area of a given cylinder based on allometric scalingtheory. The units and values are the total number of supportedtwigs.
pipe_radius: This is the theoreticalradius of a given cylinder based on allometric scaling theory. The unitsand values are the square root of the total number of supportedtwigs.
tree_metrics() generates multiple detailed metrics,which are described in detail below. Thetree,branch, andsegment data frames are summarieson an individual tree, branch, or segment level, while thetree_*_dist,branch_*_dist, andsegment_*_dist are summarised byheight,diameter,zenith,azimuth,angle, ororder. All of the outputs aredescribed in detail below:
tree_volume_m3: The total volume of thetree in cubic meters.
stem_volume_m3: The total volume of themain stem in cubic meters.
branch_volume_m3: The total volume ofthe branches in cubic meters.
tree_height_m: The total height of thetree in meters.
tree_length_m: The total length of thetree in meters. This is calculated by summing the length of all of thecylinders in the QSM. This is also equal to the growth length of base ofthe tree.
stem_length_m: The total length of themain stem in meters.
branch_length_m: The total length ofthe branches in meters. This is calculated by summing the length of allof the branch cylinders in the QSM.
branches: The total number of branchesin the QSM, where a branch begins at a new branch order and ends at atwig.
branches_alt: The total number ofalternate branches, where an alternate branch is attached directly tothe main stem, and contains all connected children.
max_branch_order: The maximum branchorder in the QSM.
max_reverse_order: The maximum reversebranch order in the QSM, which is the maximum node depth from thefurthest twig.
twigs: The total number of twigs in theQSM.
twig_length_m: The total length of thetwig cylinders in meters.
twig_distance_m: The average distancefrom the base of the tree to each twig.
path_fraction: The average path length(from the base of the tree to the twig) divided by the maximum pathlength. A path fraction of 1 is a perfect fractal.
tree_area_m2: The total surface area ofthe tree in square meters.
stem_area_m2: The total surface area ofthe main stem in square meters.
branch_area_m2: The total surface areaof the branches in square meters.
dbh_qsm_cm: The diameter at breastheight of the QSM at 1.37 meters in centimeters, modified by anytapering.
dbh_raw_cm: The diameter at breastheight of the QSM at 1.37 meters in centimeters, without any radiusmodification.
d_base_qsm_cm: The diameter of the basecylinder of the QSM in centimeters, modified by any tapering.
d_base_raw_cm: The diameter of the basecylinder of the QSM in centimeters, without any radius modification.
crown_diameter_mean_m: The averagecrown diameter in meters.
crown_diameter_max_m: The maximum crowndiameter in meters.
crown_diameter_min_m: The minimum crowndiameter in meters.
crown_projected_area_m2: The projectedcrown area in square meters.
crown_base_height_m: The base height ofthe crown in meters.
crown_length_m: The length of the crownin meters.
crown_ratio: The crown length dividedby the total tree height.
crown_area_m2: The surface area of thecrown in square meters.
crown_volume_m3: The volume of thecrown in cubic meters.
vessel_volume: The vessel volume of thebase cylinder in the QSM.
pipe_area: The pipe area of the basecylinder in the QSM, equal to the total number of supported twigs.
pipe_radius: The pipe radius of thebase cylinder in the QSM, equal to the square root of the pipe area.
start_x: The x coordinate of the basecylinder in the QSM.
start_y: The y coordinate of the basecylinder in the QSM.
start_z: The z coordinate of the basecylinder in the QSM.
modified: The ratio of cylinders withradii modified by Real Twig, divided by the total number of cylinders inthe QSM. This value only exists if Real Twig has been run.
volume_change_pct: The percent changein total volume from running Real Twig. This value only exists if RealTwig has been run.
area_change_pct: The percent change intotal surface area from running Real Twig. This value only exists ifReal Twig has been run.
branch: The id of the branch beingsummarised.
branch_alt: The id of the alternatebranch being summarised.
segment: The id of the segment beingsummarised.
parent_branch: The parent branch of thebranch being summarised.
parent_segment: The parent segment ofthe segment being summarised.
branch_order: The branch order of thebranch or segment.
reverse_order: The reverse branch orderof the branch or segment.
diameter_base_cm: The diameter of thebase of the branch or segment in centimeters.
diameter_mid_cm: The diameter of themidpoint of the branch or segment in centimeters.
diameter_tip_cm: The diameter of theend of the branch or segment in centimeters.
volume_m3: The volume in cubic metersof the branch or segment.
area_m2: The surface area in squaremeters of the branch or segment.
length_m: The length in meters of thebranch or segment.
height_m: The height above the groundin meters of the branch or segment.
angle_deg: The angle in degrees of thebranch or segment.
azimuth_deg: The azimuth in degrees ofthe branch or segment.
zenith_deg: The zenith in degrees ofthe branch or segment.
growth_length: The growth length of thebranch in meters.
cylinders: The total number ofcylinders in the branch or segment.
segments: The total number of segmentsin the branch.
children: The sum of the supportedchildren in the branch or segment.
base_distance_m: The shortest pathdistance in meters to the base of the tree from the base of the branchor segment.
twig_distance_m: The average distancein meters to the supported twigs from the base of the branch orsegment.
The height distributions are calculated on the tree, branch, andsegment level. Branch column names containing_1 summariseonly the first order branch cylinders, similar to the output ofTreeQSM.
height_class_m: The one meter heightclass of the tree, branch, or segment cylinders.
volume_m3: The volume in cubic metersof the tree, branch, or segment cylinders per height class.
area_m2: The surface are in squaremeters of the tree, branch, or segment cylinders per height class.
length_m: The length in meters of thetree, branch, or segment cylinders per height class.
branches: The number of branches in theheight class.
segments: The number of segments in theheight class.
The diameter distributions are calculated on the tree, branch, andsegment level. Branch column names containing_1 summariseonly the first order branch cylinders, similar to the output ofTreeQSM.
diameter_class_cm: The one centimeterdiameter class of the tree, branch, or segment cylinders.
volume_m3: The volume in cubic metersof the tree, branch, or segment cylinders per diameter class.
area_m2: The surface are in squaremeters of the tree, branch, or segment cylinders per diameter class.
length_m: The length in meters of thetree, branch, or segment cylinders per diameter class.
branches: The number of branches in thediameter class.
segments: The number of segments in thediameter class.
The zenith distributions are calculated on the tree, branch, andsegment level. Branch column names containing_1 summariseonly the first order branch cylinders, similar to the output ofTreeQSM.
zenith_class_deg: The ten degree zenithclass of the tree, branch, or segment cylinders.
volume_m3: The volume in cubic metersof the tree, branch, or segment cylinders per zenith class.
area_m2: The surface are in squaremeters of the tree, branch, or segment cylinders per zenith class.
length_m: The length in meters of thetree, branch, or segment cylinders per zenith class.
branches: The number of branches in thezenith class.
segments: The number of segments in thezenith class.
The azimuth distributions are calculated on the tree, branch, andsegment level. Branch column names containing_1 summariseonly the first order branch cylinders, similar to the output ofTreeQSM.
azimuth_class_deg: The ten degreeazimuth class of the tree, branch, or segment cylinders.
volume_m3: The volume in cubic metersof the tree, branch, or segment cylinders per azimuth class.
area_m2: The surface are in squaremeters of the tree, branch, or segment cylinders per azimuth class.
length_m: The length in meters of thetree, branch, or segment cylinders per azimuth class.
branches: The number of branches in theazimuth class.
segments: The number of segments in theazimuth class.
The angle distributions are calculated on the branch and segmentlevel. Branch column names containing_1 summarise only thefirst order branch cylinders, similar to the output of TreeQSM.
angle_class_deg: The ten degree angleclass of the branch or segment cylinders.
volume_m3: The volume in cubic metersof the branch or segment cylinders per angle class.
area_m2: The surface are in squaremeters of the branch or segment cylinders per angle class.
length_m: The length in meters of thebranch or segment cylinders per angle class.
branches: The number of branches in theangle class.
segments: The number of segments in theangle class.
The order distributions are calculated on the branch and segmentlevel. Branch column names containing_1 summarise only thefirst order branch cylinders, similar to the output of TreeQSM.
branch_order: The branch order.
reverse_order: The reverse branchorder.
volume_m3: The volume in cubic metersof the branch or segment cylinders per order.
area_m2: The surface are in squaremeters of the branch or segment cylinders per order.
length_m: The length in meters of thebranch or segment cylinders per order.
branches: The number of branches in theorder.
segments: The number of segments in theorder.
height_m: The height in meters abovethe ground of the main stem.
diameter_cm: The diameter incentimeters at the given height.
azimuth_deg: 20 degree azimuthclasses.
height_class: 1 meter heightclasses.
spread_m: The crown spread in meters atthe given azimuth and height.
height_class: 1 meter heightclasses.
avg_spread_m: The average crown spreadin meters at the given height.
The simulated point cloud used to calculate many of the metrics.
The version ofrTwig used to create the metrics.
The date and time the metrics were generated.