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

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

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

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

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

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

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

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

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)