trajectory {archiDART} R Documentation

## Computing Root Growth Directions and Trajectories

### Description

Calculation of root system architecture (RSA) parameters describing the directions and the trajectories of the root system growth using Data Analysis of Root Tracings (DART) output files and RSA data encoded with the Root System Markup Language (RSML). This function allows the calculation of the branching angle of each daughter root on its corresponding mother root, statistical parameters describing the curvature of each root constituting a vectorized root system, and the root tip angles relative to a vertical direction vector at each observation date. More information can be found in Delory et al (2016), Le Bot et al (2010), and Lobet et al (2015).

### Usage

```trajectory(inputrac=NULL, inputlie=NULL, inputtps=NULL, inputrsml=NULL, res=NULL,
unitlength="px", unitangle="d", rotation=0, l.brangle, l.curv, l.tipangle,
rsml.date=NULL, vertical3d="y", plot=NULL, twod=NULL, colangle=NULL,
export.colors=FALSE, BRscale=NULL, main=NULL, xlim=NULL, ylim=NULL,
zlim=NULL, xlab=NULL, ylab=NULL, zlab=NULL, ...)```

### Arguments

 `inputrac` A character string specifying the path to the folder containing the rac files created by DART. This argument could be the same as `inputlie`/`inputtps`/`inputrsml`. `inputlie` A character string specifying the path to the folder containing the lie files created by DART. This argument could be the same as `inputrac`/`inputtps`/`inputrsml`. `inputtps` A character string specifying the path to the folder containing the tps files created by DART. This argument could be the same as `inputrac`/`inputlie`/`inputrsml`. `inputrsml` A character string specifying the path to the folder containing the RSML files. This argument could be the same as `inputrac`/`inputlie`/`inputtps`. `res` Mandatory for DART files only. If images were acquired with a flatbed scanner: a numeric value specifying the resolution of the images used to vectorize the root systems with DART (resolution is expressed in dots/inch). If images were acquired with a digital camera: the ratio between the length of a reference object located on the image expressed in pixels and the actual length of the same object expressed in inches. For DART files, this argument must be specified if `unitlength="mm"` or `unitlength="cm"`. For RSML files, the resolution is imported from the metadata and does not need to be specified as an argument. `unitlength` A character string specifying the unit of length that must be used to express the results. The value acceptable for this argument could be either “px” for pixels, “cm” for centimetres or “mm” for millimetres. `unitangle` A character string specifying the unit that must be used to express the calculated angles. The value acceptable for this argument could be either “d” for degrees (default value) or “r” for radians. `rotation` A numeric value specifying the angle (expressed in `unitangle`) that must be used to perform a clockwise rotation of 2D root systems (see details). `l.brangle` A numeric value specifying the minimum root length used to calculate the branching angle of a daughter root on its corresponding mother root (see details). `l.curv` A numeric value specifying the distance used to place equidistantly spaced interpolated points along each root before calculating the angles between the direction vectors of the successive links constituting a vectorized root (see details). `l.tipangle` A numeric value specifying the distance between the root tip and an interpolated point located along a root. Each interpolated point is used by the function to calculate a direction vector following the root growth direction near the apex prior to the calculation of the root tip angle relative to a vertical direction vector at each observation date. `rsml.date` Only used for RSML files. A numeric value specifying the root system age (the unit of time is defined by the user). If `rsml.date=NULL`, a default value of 1 is used by the function. If the root system age is stored as a continuous function along the root segments, a character string specifying the name/label of the function can be used (see details). `vertical3d` The vertical axis for 3D RSA data (x, y, or z). `plot` Either “branching” or “direction”. If `plot="branching"`, each root is plotted with a color code depending on the value of its branching angle. If `plot="direction"`, each root is plotted with a color code depending on the value of its growth direction angle. `twod` When RSML files contain 3D RSA data, should the root systems be plotted in 2D? This argument can be NULL (3D plots) or a character vector giving the name of the axes to plot (can be c(“x”, “y”), c(“x”, “z”), or c(“y”, “z”)). `colangle` A vector specifying the color(s) that must be used to plot the root system(s). `trajectory` interpolates the color(s) contained in `colangle` between the minimum and the maximum values of the computed standardized angle matrix (if `is.null(BRscale)=TRUE`) or between `min(BRscale)` and `max(BRscale)` (if `is.null(BRscale)=FALSE`). `export.colors` A logical value. Should the color values be exported? `BRscale` A numeric vector (length=2) specifying the minimum and the maximum angle values (expressed in `unitangle`) that must be used to plot each vectorized root system. `main` A character string giving a main title for the plot. When `is.null(main)=TRUE`, the default title for each plot is the name of the corresponding lie/RSML file. `xlim` A numeric vector (length=2) giving the X limits of the plot using the same unit as `unitlength`. `ylim` A numeric vector (length=2) giving the Y limits of the plot using the same unit as `unitlength`. `zlim` A numeric vector (length=2) giving the Z limits of the plot using the same unit as `unitlength`. `xlab` A character string giving a label for the X axis. When `is.null(xlab)=TRUE`, the default label for the X axis is X (`unitlength`). `ylab` A character string giving a label for the Y axis. When `is.null(ylab)=TRUE`, the default label for the Y axis is Y (`unitlength`). `zlab` A character string giving a label for the Z axis. When `is.null(zlab)=TRUE`, the default label for the Z axis is Z (`unitlength`). `...` Additional graphical parameters (see details).

### Details

To run `trajectory` efficiently, DART (.rac, .lie or .tps) and RSML (.rsml) files must have been saved with their appropriate extension.

If `inputtps` contains a single tps file, it is used by `trajectory` for each lie/rac file located in `inputlie`/`inputrac`. The number of lie files in `inputlie` must be equal to the number of rac files in `inputrac` and corresponding rac and lie files must have the same name. If `inputps` contains more than one tps file, the number of tps files in `inputtps` must be equal to the number of rac/lie files in `inputrac`/`inputlie` and corresponding rac/lie and tps files must have the same name.

After reading the RSML files located in `inputrsml`, the data associated with each root system are converted into data frames possessing the same structure as the lie/rac files created by DART. The `trajectory` function then uses these data frames to compute RSA traits.

The argument `rsml.date` is used to create a tps file for each root system located in `inputrsml`. If the root system age is stored as a continuous function along the root segments, the `rsml.date` argument can be a character string specifying the name/label of the function. For instance, the root system age at the first apparition of each node is stored as a continuous function called “age” in RSML files containing RSA data simulated with the ArchiSimple model (Pages et al (2013)). The “age” function attaches the root system age along the root segments, so that each node is associated with one age value. An RSML library containing 3D RSA data simulated with ArchiSimple is available here: doi: 10.5281/zenodo.208214.

The `rsml.connect` argument can be used to connect the lateral roots to their corresponding mother root. If `rsml.connect=TRUE`, each point starting a lateral root is connected to the nearest point located on its mother root. DBase is approximated by the distance between the parent root base and the point located on the mother root that is closest to the point starting a lateral root. Using RSML files, only RSA data associated with roots possessing a branching order lower or equal to 7 are used for the computation of RSA traits.

Due to technical limitations, it is sometimes easier to take a picture of a root system if it is rotated before image acquisition. In this case, the vectorized root system depicts a rotation compared with the natural plant root system. In order to make a correction, one can use `rotation` to specify an angle value expressed in `unitangle` to rotate the vectorized root system clockwise before plotting.

Hereafter, we will consider that the normal vector that is orthogonal to a direction vector (a,b) has the following coordinates: (b,-a). The direction of lateral root growth is only computed for 2D root systems. A daughter root is considered to grow at the left side of the mother root if the scalar product between a direction vector (=vector A) going from the branching point (X0) to the following point (Xd) on the daughter root and a vector (=vector B) normal to a direction vector (=vector C) going from the branching point (X0) to the following point on the mother root (Xm) is positive. If the scalar product between A and B is negative, the daughter root is considered to grow at the right side of the mother root. If the scalar product between A and B is equal to zero, the calculation of the scalar product between A and B will be performed again using a vector A going from the branching point (X0) to a point located on the daughter root at Xd<-Xd+1 until the calculated scalar product is different from zero. If A is always normal to B, a random lateral root growth orientation (either left or right) is defined. See table 2 and figure 1 of Delory et al (2016) for more information.

The branching angle of a daughter root on its mother root is approximated by the angle between two direction vectors going from the branching point to an interpolated point located at a distance `l.brangle` from the branching point on the mother or on the daughter root, respectively. The distance `l.brangle` between a branching point and an interpolated point is measured along the mother and the daughter roots. A first-order root having no mother root, the reported angle is the angle measured between a vertical direction vector and a second direction vector going from the first node of the root to an interpolated point located at a distance `l.brangle` from the first node on the first-order root. If a root has a final length lower than `l.brangle`, no branching angle can be calculated and the function returns a `NA` value for Branching.Angle. See table 2 and figure 1 of Delory et al (2016) for more information.

For each root, the growth direction angle is calculated as the angle between a vertical direction vector and a second direction vector going from the branching point to the apex of the root.

The curvature of each root is evaluated by the mean and the standard deviation of the local angles formed by the direction vectors of the successive links constituting a vectorized root. First, the function uses `l.curv` to interpolate equidistantly spaced points along each root constituting a vectorized root system. Second, the angles between the direction vectors of successive links along each root are calculated. Then, the mean and the standard deviation of the calculated angles are determined for each root. If a root has a final length lower than 2*`l.curv`, the function returns a `NA` value for Mean.Curv and SD.Curv. If a root has a final length lower than 3*`l.curv`, the function returns a `NA` value for SD.Curv as no standard deviation can be calculated on a single angle value. See table 2 and figure 1 of Delory et al (2016) for more information.

Making 3D plots with `twod = NULL` requires the `rgl` package, which is otherwise optional. If it is not installed (which can be annoying to do on some OSes), `trajectory()` will complain when you attempt a 3D plot but will still work normally for 2D.

### Value

Returns a list including:

 `root` A list of data frames. Each element of the list is named as its corresponding rac/lie/RSML file and contains the following columns: Root (the identification number of each root constituting the vectorized root system), Mother (the parent root identification number), Ord (the branching order), DBase (the distance between the branching point to the parent root base expressed in `unitlength`), FinalRootLength (the root length at the last observation date expressed in `unitlength`), Tortuosity (the ratio of the final root length to the Euclidean distance between the branching point and the apex of the root), Orientation (the direction of the lateral root growth; only for 2D root systems), Branching.Angle (the branching angle expressed in `unitangle`), Growth.Direction (the growth direction angle expressed in `unitangle`), Mean.Curv (the mean of the local angle values calculated between the direction vectors of the successive links constructed using equidistantly spaced interpolated points along each root of a vectorized root system; the calculated mean is expressed in `unitangle`), SD.Curv (the standard deviation of the local angle values calculated between the direction vectors of the successive links constructed using equidistantly spaced interpolated points along each root of a vectorized root system; the calculated standard deviation is expressed in `unitangle`), Colors (if `export.colors=TRUE`, the colors used to plot each root). `tip` A list of data frames. Each element of the list is named as its corresponding rac/lie/RSML file and contains the following columns: Root (the identification number of each root constituting the vectorized root system), Ang.DateX (the calculated root tip angle relative to a vertical direction vector at the observation date X expressed in `unitangle`).

### Author(s)

Benjamin M. Delory, Guillaume Lobet, Loic Pages

### References

Delory B.M., Baudson C., Brostaux Y., Lobet G., du Jardin P., Pages L., Delaplace P. (2016) archiDART: an R package for the automated computation of plant root architectural traits, Plant and Soil, DOI: 10.1007/s11104-015-2673-4.

Le Bot J., Serra V., Fabre J., Draye X., Adamowicz S., Pages L. (2010) DART: a software to analyse root system architecture and development from captured images, Plant and Soil, DOI: 10.1007/s11104-009-0005-2.

Lobet G., Pound M.P., Diener J., Pradal C., Draye X., Godin C., Javaux M., Leitner D., Meunier F., Nacry P., Pridmore T.P., Schnepf A. (2015) Root System Markup Language: Toward a Unified Root Architecture Description Language, Plant Physiology, DOI: 10.1104/pp.114.253625.

Pages L., Becel C., Boukcim H., Moreau D., Nguyen C., Voisin, A-S. (2013) Calibration and evaluation of ArchiSimple, a simple model of root system architecture, Ecological Modelling, DOI: 10.1016/j.ecolmodel.2013.11.014.

### Examples

```## Locate folder with DART and RSML files
path <- system.file("extdata", package="archiDART")

##---------------------
## DART and RSML files
##---------------------

res4 <- trajectory(inputrac=path, inputlie=path, inputtps=path, inputrsml=path, res=75,
unitlength="cm", rsml.date="age", l.brangle=1, l.curv=1, l.tipangle=0.5, vertical3d="y")

## Distribution of the calculated branching angles
hist(res4\$root\$ch7\$Branching.Angle, breaks=seq(from=0, to=180, by=5),
main="ch7-Branching angle distribution", xlab="Branching angle (d)", las=1,
xaxp=c(0,150,15), xlim=c(0,150))

## Evolution of the root tip angle for the primary root (black) and the two longest lateral roots
## (green and red)
date<-c(1:31)
plot(date, res4\$tip\$ch7[1,2:ncol(res4\$tip\$ch7)], type="l", lwd=2, bty="l",
las=1, ylim=c(0,90), ylab="ch7 - Root tip angle (d)", xlab="Time (Num)", col="black",
main="Root tip angle", yaxp=c(0,90,9))
lines(date, res4\$tip\$ch7[206,2:ncol(res4\$tip\$ch7)], lwd=2, col="green")
lines(date, res4\$tip\$ch7[221,2:ncol(res4\$tip\$ch7)], lwd=2, col="red")

## Branching angles of lateral roots
monocot<-res4\$root\$'monocot-archisimple'
data<-data.frame(Factor=c(rep("Monocot", nrow(monocot))), monocot)
boxplot(Branching.Angle[Ord==2]~Factor[Ord==2], data=data, ylab="Branching angle (d)",
ylim=c(45,70), main="Branching angle laterals - Monocot", las=1, outline=FALSE,
range=0, notch=TRUE)

## Evolution of the root tip angle for the first-order roots of the monocot root system
tip<-res4\$tip\$'monocot-archisimple'
root<-res4\$root\$'monocot-archisimple'
date<-c(1:(ncol(tip)-1))
firstorderroots<-which(root\$Ord==1)
colors<-colorRampPalette(c("red", "green"))(length(firstorderroots))

plot(date, tip[1,2:ncol(tip)], type="n", lwd=2, bty="l", las=1, ylim=c(0,90),
yaxp=c(0,90,9), xaxp=c(0,16,16), ylab="Root tip angle (d)", xlab="Time (Num)", col="black",
main="Monocot - Root tip angle first-order roots")

for (i in 1:length(firstorderroots)){lines(date, tip[firstorderroots[i], 2:ncol(tip)], lwd=2,
col=colors[i])}
```

[Package archiDART version 3.4 Index]