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 |
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.
align(input, year = FALSE, list = FALSE, interact = TRUE, make.plot = TRUE)
align(input, year = FALSE, list = FALSE, interact = TRUE, make.plot = TRUE)
input |
an |
year |
a numeric vector specifying the year of interest. The default ( |
list |
a |
interact |
a logical flag. If |
make.plot |
logical flag indicating whether to make a plot (default = |
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).
An aligned is.raptor
file.
#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)
#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)
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).
anatomy.data anatomy.data
anatomy.data anatomy.data
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>
von Arx, G., & Carrer, M. (2014) ROXAS - A new tool to build centuries-long tracheid-lumen chronologies in conifers. Dendrochronologia 32, 290-293.
#viewing anatomy data head(anatomy.data)
#viewing anatomy data head(anatomy.data)
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.
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)
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)
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 |
interact |
a logical flag. If |
make.plot |
logical flag indicating whether to make a plot (default = |
aligning |
logical flag indicating whether a second alignment has to be performed based upon the cells detected within |
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 |
flip |
logical flag indicating whether to plot the data with earlywood downwards (default; flip = |
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.
Plots the detected radial files and writes output according the the
write.output
format.
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.
example.data(species = "LOT_PICEA")
example.data(species = "LOT_PICEA")
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". |
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.
A data.frame
containing anatomical measurements from the selected species.
#loading example data input<-example.data(species="LOT_PICEA") input str(input)
#loading example data input<-example.data(species="LOT_PICEA") input str(input)
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.
first.cell(input, frac.small, yrs, make.plot = TRUE)
first.cell(input, frac.small, yrs, make.plot = TRUE)
input |
an |
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 |
make.plot |
logical flag indicating whether to make a plot (default = |
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.
An is.raptor
file with an added column describing the first cells.
## 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)
## 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)
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).
graph.cells(input, year=FALSE, interact=FALSE)
graph.cells(input, year=FALSE, interact=FALSE)
input |
an |
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 |
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.
#' #plotting example data input<-example.data(species="LOT_PICEA") input<-is.raptor(input, str=TRUE) graph.cells(input, year=2010)
#' #plotting example data input<-example.data(species="LOT_PICEA") input<-is.raptor(input, str=TRUE) graph.cells(input, year=2010)
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.
is.raptor(data, str = TRUE)
is.raptor(data, str = TRUE)
data |
a |
str |
a logical flag. If |
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.
A data.frame
in the appropriate format for other functionalities.
#validating example data input<-example.data(species="LOT_PICEA") input<-is.raptor(input, str=TRUE) input
#validating example data input<-example.data(species="LOT_PICEA") input<-is.raptor(input, str=TRUE) input
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).
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)
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)
input |
an input file as produced by |
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 |
yrs |
either a vector providing the year(s) of interest or |
aligning |
logical flag indicating whether a second alignment has to be performed based upon the cells detected within |
make.plot |
logical flag indicating whether to make a plot (default = |
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).
An is.raptor
file with an added column describing the position within the radial file.
## 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)
## 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)
Generating final output graphs and files for the row and position detection. Input data should be provided as produced by pos.det
.
write.output(input, location, flip = FALSE)
write.output(input, location, flip = FALSE)
input |
a |
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 = |
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).
Plots the detected radial files and writes output according to the is.raptor
format.
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.
## 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)
## 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)