Package 'RAPTOR'

Title: Row and Position Tracheid Organizer
Description: Performs wood cell anatomical data analyses on spatially explicit xylem (tracheids) datasets derived from thin sections of woody tissue. The package includes functions for visualisation, detection and alignment of continuous tracheid radial file (defined as rows) and individual tracheid position within an annual ring of coniferous species. This package is designed to be used with elaborate cell output, e.g. as provided with ROXAS (von Arx & Carrer, 2014 <doi:10.1016/j.dendro.2013.12.001>). The package has been validated for Picea abies, Larix Siberica, Pinus cembra and Pinus sylvestris.
Authors: Richard L. Peters [aut, cre, cph], Daniel Balanzategui [ctr], Alexander Hurley [ctr], Georg von Arx [ctr], Angela Luisa Prendin [ctr], Henri E. Cuny [ctr], Jesper Bjoerklund [ctr], David C. Frank [ctr], Patrick Fonti [ths, ctr, fnd]
Maintainer: Richard L. Peters <[email protected]>
License: GPL (>= 2)
Version: 1.0.1
Built: 2024-11-01 03:08:20 UTC
Source: https://github.com/the-hull/raptor

Help Index


Data alignment

Description

Provides a re-aligned is.raptor file, where new x- and y-coordinates (XCAL and YCAL values, respectively) are calculated according to a specified rotation. Appropriate alignment is achieved when the first row of earlywood cells are positioned along an approximately horizontal axis and the radial files of tracheids are positioned along a vertical axis.

Usage

align(input, year = FALSE, list = FALSE, interact = TRUE, make.plot = TRUE)

Arguments

input

an is.raptor file.

year

a numeric vector specifying the year of interest. The default (FALSE) applies the function on all years present in the input.

list

a vector of numeric values indicating the rotation slope for each year.

interact

a logical flag. If TRUE, the user can manually assign the degree of rotation for each annual ring in an interactive session. The user will have to select among the options (along the horizontal axis, along the vertical axis, manually define the degree of reorientation based on a set of slopes overlaid on the plot). If FALSE, the rotation is optimized automatically using a simple linear regression through all points along the horizontal axis (default = FALSE).

make.plot

logical flag indicating whether to make a plot (default = FALSE).

Details

Correct alignment of cells/tracheids is important for detecting the first cells and assigning cells to a radial file. This function provides the option to align your cell data (XCAL and YCAL). This function provides and interactive procedure to improve the alignment by presenting a crosshair with slopes with which the sample should be rotated. Proper alignment is obtain when the first cells are approximately aligned on a horizontal line and the upward cells are propagated vertically. Either interactively or with predefined slopes, the user can rotate the sample orientation. An automatic option is also available where a simple linear regression is fitted through all points to adjust the rotation. The plot shows the original position of the cells (black dots) and lines that can be selected to rotate the sample. After correction the new position of the cells is presented (red dots).

Value

An aligned is.raptor file.

Examples

#rotating example data
input<-is.raptor(example.data(species="LOT_PICEA"), str=FALSE)
input<-align(input, year=2007, list=FALSE,interact=FALSE, make.plot=TRUE)

Anatomical measurements

Description

This example dataset includes ROXAS output files (cf. von Arx & Carrer, 2014) with lumen area and cell wall thickness measurements from; i) Norway Spruce (Picea abies) from the Loetschental, Switzerland (2007-2013), ii) Siberian larch (Larix siberica) from Siberia, Russia (2007-2010), iii) Stone pine (Pinus cembra) from the Dolomite mountains, Italy (2007-2010), and iv) Scots pine (Pinus sylvestris) from the eastern lowlands, Germany (2007-2010).

Usage

anatomy.data

anatomy.data

Format

Provides a data.frame with 18838 rows and 7 columns containing data on:

[ ,1] ID = Site and species id <factor>
[ ,2] CID = Unique cell id <integer>
[ ,3] YEAR = Year of the ring <integer>
[ ,4] CA = Lumen size (micron) <numeric>
[ ,5] XCAL = X-value of cell center in calibrated coordinate system (micron) <numeric>
[ ,6] YCAL = Y-value of cell center in calibrated coordinate system (micron) <numeric>
[ ,7] CWTALL = Mean thickness of all cell walls (micron) <numeric>

References

von Arx, G., & Carrer, M. (2014) ROXAS - A new tool to build centuries-long tracheid-lumen chronologies in conifers. Dendrochronologia 32, 290-293.

Examples

#viewing anatomy data
head(anatomy.data)

Automatic rows and position detection

Description

Batch.mode applies all functionalities described in is.raptor, align, first.cell, pos.det and write.output. Multiple input datasets (sample specific) can be provided in a folder and automatically used within this function. Input data should be checked for all requirements described in is.raptor and preferably adjusted with align. See pos.det for a detailed description of arguments.

Usage

batch.mode(location, files = FALSE,
           interact = TRUE, make.plot = TRUE,
           aligning = TRUE, frac.small=0.5, swe=0.5, sle=3,
           ec=3, swl=0.5, sll=5, lc=10, prof.co=6, max.cells=0.5,
           list = FALSE, flip = FALSE)

Arguments

location

a character string containing the location of input files and where the outputs (.pdf and .txt files) should be stored.

files

a vector of files for the analyses (defaults to all files present in the folder). Text files should agree with all criteria presented in is.raptor.

interact

a logical flag. If TRUE, the user will have the options to manually assign the degree of rotation for each annual ring. See align for rotation options. If FALSE, the rotation is optimized automatically using a simple linear regression through all points along the horizontal axis (default = FALSE).

make.plot

logical flag indicating whether to make a plot (default = FALSE).

aligning

logical flag indicating whether a second alignment has to be performed based upon the cells detected within first.cell (default = TRUE).

frac.small

a numeric value (between 0 and 1) that is multiplied by the average cell lumen size of the ring, determining the minimal threshold used to filter out too small first row tracheids (default = 0.5).

swe

a numeric value that is multiplied by the square-rooted cell lumen area (l) of the target cell and used to determine the width of the rectangular search area which locates the next earlywood cell in the row (default = 0.5).

sle

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the length of the rectangle search area which locates the next earlywood cell in the row (default = 3).

ec

threshold ratio between the lumen area of two consecutive earlywood cells to determine the end of the earlywood search (default = 1.75). The default setting indicates that the earlywood search ends when the next cell lumen area is at least 1.75 times smaller than the target cell.

swl

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the width of the rectangle search area which locates the next latewood cell in the row (default = 0.25).

sll

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the length of the rectangle search area which locates the next earlywood cell in the row (default = 5).

lc

threshold ratio between the lumen area of two consecutive latewood cells to determine the end of the radial file (default = 10). The default setting indicates that the latewood search ends when the next cell lumen area is at least 10 times smaller than the target cell.

prof.co

threshold ratio between the distance to the previous and consecutive cell to determine if the row (or radial file) should be excluded (default = 6).

max.cells

threshold proportion of the maximum number of cells to determine if the radial file has to be excluded (default = 0.6).

list

a data.frame with the individual "ID" and in sequence the slopes as described in pos.det. Cannot be activated when interact = TRUE.

flip

logical flag indicating whether to plot the data with earlywood downwards (default; flip = FALSE) or upwards (flip = TRUE).

Details

This function aids in applying all described functions on a large dataset composed of multiple files, including multiple individuals and years. It will generate output graphs as described in is.raptor, align, first.cell, pos.det and write.output in a .pdf file. Additionally, output text files are written. All output files are exported into the directory specified in the location argument.

Value

Plots the detected radial files and writes output according the the write.output format.


Species-specific anatomy input

Description

This function provides a data.frame containing standard anatomical measurements from xylem cross-sections images analysed with ROXAS (version 3.0). From the dataset described in anatomy.data, multiple input examples can be provided, including; 1) Norway Spruce (Picea abies) from the Loetschental, Switzerland, 2) Siberian larch (Larix siberica) from Siberia, Russia, 3) Stone pine (Pinus cembra) from the Dolomite mountains, Italy, and 4) Scots pine (Pinus sylvestris) from the eastern lowlands, Germany.

Usage

example.data(species = "LOT_PICEA")

Arguments

species

a character string specifying the species from which the example data should be loaded. Valid options include; Picea abies = "LOT_PICEA", Larix siberica = "SIB_LARIX", Pinus cembra = "MOUNT_PINUS", Pinus sylvestris = "LOW_PINUS".

Details

This datasets can be applied as an example to test functions provided in the package. Other examples of ROXAS output can be obtained via: WSL - ROXAS.

Value

A data.frame containing anatomical measurements from the selected species.

Examples

#loading example data
input<-example.data(species="LOT_PICEA")
input
str(input)

Detection of the first cells

Description

This function uses an is.raptor file (preferably obtained from align) and adds a column with the first cells detected within radial files (i.e. first cell formed in the growing season). The value indicates to which radial file the first cell belongs to (counting from left to right). All cells with NA are not considered as first row cells and are excluded in further analyses.

Usage

first.cell(input, frac.small, yrs, make.plot = TRUE)

Arguments

input

an is.raptor file.

frac.small

a numeric value (between 0 and 1) that is multiplied by the average cell lumen size of the ring, determining the minimum threshold used to exclude cells in the first row that are too small (default = 0.5).

yrs

either a numeric vector providing the year(s) of interest or FALSE to select all years included in input (default = FALSE).

make.plot

logical flag indicating whether to make a plot (default = FALSE).

Details

The first row of cells is detected by using a local search algorithm, where the first cell is indicated by a green box when make.plot = TRUE, and the last by a red box. Values within the graph indicate the row numbers that have been detected. The output adds a column to the input data which indicates the first row of cells. The frac.small argument allows the user to filter out unrealistically small cells.

Value

An is.raptor file with an added column describing the first cells.

Examples

## Not run: 
#first row detection example
input<-is.raptor(example.data(species="LOT_PICEA"), str = FALSE)
input<-input[which(input[,"YEAR"]>2006 & input[,"YEAR"]<2011),]
aligned<-align(input,list=c(0.04,0.04,0,0))
first<-first.cell(aligned, frac.small = 0.5, yrs = FALSE, make.plot = TRUE)

## End(Not run)

Data visualization

Description

This function uses is.raptor files to create a two panel plot including; 1) a schematic overview of the ring width sequence and 2) a graphical representation of the cell size and position within a specific year (highlighted in the ring width sequence).

Usage

graph.cells(input, year=FALSE, interact=FALSE)

Arguments

input

an is.raptor file.

year

a numerical value specifying the year of interest. Default starts with the first year and plots the other years in sequence.

interact

a logical flag. If TRUE, the user can interactively cycle through plots of annual rings (default = FALSE).

Details

This graphical interface aids in exploring the cell position and cell size. The upper plot provides and overview of the available years within the data.frame. Grey shading indicates the year that is presented in the lower panel. The italic value in the upper panel presents the number of cells within the selected year. The lower panel shows the position of the cells with their unique "CID". XCAL and YCAL positions are standardized to the minimum occurring coordinates. Within the lower panel, the grey boxes represent the cells, derived from the lumen area ("CA") assuming a square. When "interact = TRUE", readline messages will be presented with multiple options to create a new plot while moving along the years (including selecting the previous, next year or selecting a specific year). Stopping the interact function is done by typing "x". Terminate this function before continuing with other functions.

Examples

#' #plotting example data
input<-example.data(species="LOT_PICEA")
input<-is.raptor(input, str=TRUE)
graph.cells(input, year=2010)

Testing and preparing input data

Description

Testing if the structure of the input matches the requirements for the RAPTOR functions. The input has to be presented in a data.frame including the following columns; 1) sample id <as.character/as.factor>, 2) tracheid id <as.integer>, 3) tree-ring year <as.numeric>, 4) lumen size <as.numeric>, 5) x-coordinate of the cell <as.numeric> and 6) y-coordinate of the cell <as.numeric>. The anatomical data should be oriented with the latewood cells on the upper section of the image. For this function either the order or the columns has to be respected or the following column names have to be present within the data.frame: "ID" = sample id, "CID" = tracheid id, "YEAR" = year, "CA" = lumen size (micron), "XCAL" = x coordinate, "YCAL" = y coordinate. Additionally, at least 50 tracheid's (or cells) have to be present in each year.

Usage

is.raptor(data, str = TRUE)

Arguments

data

a data.frame where tracheids are ordered in rows and the columns contain the variables; sample id, cell id, year, tracheid lumen area, x coordinates and y coordinates. The name of the columns (colnames) have to either be named as "ID","CID","YEAR","CA","XCAL" and "YCAL" or properly ordered.

str

a logical flag. If TRUE the structure of the data will be printed (default = FALSE).

Details

To prevent errors occurring in the other reported functions, it is advised to run this function for checking the data structure and preparing it for further analyses.

Value

A data.frame in the appropriate format for other functionalities.

See Also

anatomy.data

Examples

#validating example data
input<-example.data(species="LOT_PICEA")
input<-is.raptor(input, str=TRUE)
input

Determining the cell position

Description

Returns a data.frame, similar as produced by first.cell, but with added columns providing ROW and POSITION which indicate the radial files number (ROW, from left to right) and radial cell position (from earlywood to latewood) of each tracheid. NA is assigned to cells not belonging to recognized radial files. A MARKER column is added to indicate the last detected cell in the earlywood search (indicated with 1), latewood search (2), the last detected cell (3), rows that are removed due to gaps (4, see prof.co) and rows that are removed due to limited amount of cells (5, see max.cells).

Usage

pos.det(input, swe = 0.5, sle = 3, ec = 1.75 , swl = 0.25, sll = 5, lc = 5,
        prof.co = 6, max.cells = 0.5, list=FALSE, yrs = FALSE,
        aligning = TRUE, make.plot = TRUE)

Arguments

input

an input file as produced by first.cell.

swe

a numeric value that is multiplied by the square-rooted cell lumen area (l) of the target cell and used to determine the width of the rectangular search area which locates the next earlywood cell in the row (default = 0.5).

sle

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the length of the rectangle search area which locates the next earlywood cell in the row (default = 3).

ec

threshold ratio between the lumen area of two consecutive earlywood cells to determine the end of the earlywood search (default = 1.75). The default setting indicates that the earlywood search ends when the next cell lumen area is at least 1.75 times smaller than the target cell.

swl

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the width of the rectangle search area which locates the next latewood cell in the row (default = 0.25).

sll

a numeric value that is multiplied by the square rooted cell lumen area (l) of the target cell to determine the length of the rectangle search area which locates the next earlywood cell in the row (default = 5).

lc

threshold ratio between the lumen area of two consecutive latewood cells to determine the end of the radial file (default = 10). The default setting indicates that the latewood search ends when the next cell lumen area is at least 10 times smaller than the target cell.

prof.co

threshold ratio between the distance to the previous and consecutive cell to determine if the row (or radial file) should be excluded (default = 6).

max.cells

threshold proportion of the maximum number of cells to determine if the radial file has to be excluded (default = 0.6).

list

a data.frame of "CID" (unique cell ID) from cells which should be considered as first row cells. Should be filled if first.cell output is not used as input. The vector should be ordered to years and present specific "CID" which is considered the first cell.

yrs

either a vector providing the year(s) of interest or FALSE to select all years included in the input file (default = FALSE).

aligning

logical flag indicating whether a second alignment has to be performed based upon the cells detected within first.cell (default = TRUE).

make.plot

logical flag indicating whether to make a plot (default = FALSE).

Details

After the identification of the first cells (with first.cell) within a radial file, this function assigns remaining cells to a corresponding radial file based on various search criteria. A local search algorithm is applied which searches cells above a specified target cell (n; starts with first cell of the radial file detected by first.cell). First the "earlywood" search process projects a search area from the selected cell with a specific width (x-axis) and length (y-axis). The search length and width is based on the length of the target cell (l_n) determined with size of the cell (where l_n= sqrt(CA_n) ) and multiplied by a factor (sle = search length earlywood, for the search length and swe = search width earlywood, for the search width). This initial search grid is presented in "orange"(if make.plot = TRUE), where the width can be adjusted by changing swe and the length by sle. When no cells are detected (last detected cells are indicated with orange circles), caused in most cases by the small size of latewood cells, a second search grid is established with an altered length and width (sll = search length latewood and swl = search width latewood; presented in "red" if make.plot = TRUE; last detected cell are indicates with red circles). Due to smaller fragments of erroneously detected cells, for both search grids a cut-off value is added where the next cell should not be smaller than the lumen area of the target cell (CA_n) times a factor (ec = earlywood cut off and lc = latewood cut off). Finally, a flexible spline is fitted through the selected cells within a row to detect missing cells. Once all cells are detected (last cell is indicated with a red square), the distance between the cells is analysed and depending upon a profile cut-off factor (prof.co) the row is omitted, if the distance difference between n+1 and n+2 times prof.co is bigger than the distance of n and n+1 (which could present a gap often caused by resin ducts; omitted rows are indicated with a "+" symbol). Also, rows that have less cells then the maximum cell count times a factor (max.cells) are removed, as the row might be incomplete (omitted rows are indicated with a "x" symbol).

Value

An is.raptor file with an added column describing the position within the radial file.

Examples

## Not run: 
#example of position detection
input<-is.raptor(example.data(species="MOUNT_PINUS"), str = FALSE)
aligned<-align(input, list=c("h", "h", "h", 0.03), make.plot = FALSE)
first<-first.cell(aligned, frac.small = 0.2, yrs = FALSE, make.plot = FALSE)
output<-pos.det(first, swe = 0.7, sle = 3, ec = 1.75, swl = 0.5, sll = 5, lc = 10,
                prof.co = 1.7, max.cells = 0.7, yrs = FALSE, aligning = FALSE, make.plot = TRUE)

## End(Not run)

Output generation and visualization

Description

Generating final output graphs and files for the row and position detection. Input data should be provided as produced by pos.det.

Usage

write.output(input, location, flip = FALSE)

Arguments

input

a data.frame produced by pos.det.

location

an optional character string containing the location where the output .pdf and .txt file should be stored. If not supplied, the function returns the computed output, which can be stored in an object.

flip

logical flag indicating in which direction to plot the cells, i.e. with earlywood at the bottom (default; flip = FALSE) or at the top (flip = TRUE).

Details

Function that aids in graphing the output and writing output tables. The generated plot provides an overview of the detected cells, rows, and the position of the cells within each radial file. The output table provides the standard output table with three additional columns containing; the "ROW" number and "POSITION" within the row and the "MARKER" column (cf. pos.det. This output can provide crucial information that can be used with other packages to generate tracheidograms (cf. de la Cruz & DeSoto, 2015) and link the output to xylogenesis data (cf. Rathgeber et al., 2011).

Value

Plots the detected radial files and writes output according to the is.raptor format.

References

de la Cruz, M., & DeSoto, L. (2015) tgram: Functions to compute and plot tracheidograms. CRAN: https://cran.r-project.org/web/packages/tgram/tgram.pdf.

Rathgeber, C.B.K., Longuetaud, F., Mothe, F., Cuny, H., & Le Moguedec, G. (2011) Phenology of wood formation: Data processing, analysis and visualisation using R (package CAVIAR). Dendrochronologia 29, 139-149.

Examples

## Not run: 
#example to write output
input<-is.raptor(example.data(species="SIB_LARIX"), str = FALSE)
aligned<-align(input)
first<-first.cell(aligned, frac.small = 0.5, yrs = FALSE, make.plot = FALSE)
output<-pos.det(first, swe = 0.3, sle = 3, ec = 1.5, swl = 0.5, sll = 5, lc = 15,
                prof.co = 4, max.cells = 0.5, yrs = FALSE, aligning = FALSE, make.plot = FALSE)
sib_larix<-write.output(output)

#removing rows which are unsuitable
corrections<-data.frame(year=c(2010,2010,2010,2009,2009,2009,2009,2008,2008,
                        2008,2008,2008,2008,2007,2007,2007),
                        row=c(19,15,9,6,11,14,17,5,6,14,17,24,15,2,8,14))
for(i in c(1:nrow(corrections))){
sib_larix[which(sib_larix[,"YEAR"]==corrections[i,1]  &
          sib_larix[,"ROW"]==corrections[i,2] ),"POSITION"]<-rep(NA,length(sib_larix[
          which(sib_larix[,"YEAR"]==corrections[i,1]& sib_larix[,"ROW"]==corrections[i,2] ),
          "POSITION"]))
sib_larix[which(sib_larix[,"YEAR"]==corrections[i,1]  &
          sib_larix[,"ROW"]==corrections[i,2] ),"ROW"]<-rep(NA,length(sib_larix[
          which(sib_larix[,"YEAR"]==corrections[i,1]&sib_larix[,"ROW"]==corrections[i,2] ),
          "POSITION"]))}
SIB_LARIX<-write.output(sib_larix)
for(i in c(1:length(unique(SIB_LARIX[,"YEAR"])))){
row_id<-unique(SIB_LARIX[which(SIB_LARIX[,"YEAR"]==unique(SIB_LARIX[,"YEAR"])[i]),"ROW"],
               na.rm=TRUE)
row_id<-na.omit(row_id[order(row_id)])
for(j in c(1:length(row_id))){
SIB_LARIX[which(SIB_LARIX[,"YEAR"]==unique(SIB_LARIX[,"YEAR"])[i] &
          SIB_LARIX[,"ROW"]==row_id[j]), "ROW"]<-j
}}

## End(Not run)