---
title: "Dictionary"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Dictionary}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Background

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.

## Dictionary

#### Cylinder Attributes

**`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 Attributes

**`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 Attributes

**`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.

#### Additional Metrics

**`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.