R: Write Tree Ring Data Standard (TRiDaS) file

write.tridas {dplR}

R Documentation

Write Tree Ring Data Standard (TRiDaS) file

Description

This function writes measured or derived (standardized, averaged) series of values to a TRiDaS format file. Some metadata are also supported.

Usage

write.tridas(rwl.df = NULL, fname, crn = NULL, prec = NULL, ids = NULL,
    titles = NULL, crn.types = NULL, crn.titles = NULL,
    crn.units = NULL, tridas.measuring.method = NA,
    other.measuring.method = "unknown", sample.type = "core",
    wood.completeness = NULL, taxon = "",
    tridas.variable = "ring width", other.variable = NA,
    project.info = list(type = c("unknown"), description = NULL,
                        title = "", category = "", investigator = "",
                        period = ""),
    lab.info = data.frame(name = "", acronym = NA, identifier = NA,
                          domain = "", addressLine1 = NA,
                          addressLine2 = NA, cityOrTown = NA,
                          stateProvinceRegion = NA, postalCode = NA,
                          country = NA),
    research.info = data.frame(identifier = NULL, domain = NULL,
                               description = NULL),
    site.info = list(type = "unknown", description = NULL, title = ""),
    random.identifiers = FALSE, identifier.domain = lab.info$name[1],
    ...)

Arguments

`rwl.df`	`data.frame` containing tree-ring ring widths in millimetres with the series in columns and the years as rows. The series IDs are the column names and the years are the row names. This type of `data.frame` is produced by `read.tucson`, `read.compact` and `read.tridas`. Defaults to `NULL`: no measurement series are written.
`fname`	`character` vector giving the file name of the rwl file
`crn`	`data.frame` or a list of `data.frame`s containing tree-ring chronologies. Accepts `data.frame`s of the type produced by `chron`. Additionally, allows several chronologies per `data.frame`. Any column of the `data.frame`(s) with a name starting with `"samp.depth"` is interpreted as a sample depth. The rest of the columns are interpreted as chronologies whose titles are determined from the column names (optionally from parameter `crn.titles`). Chronology columns and sample depth columns are paired in order so that the first chronology gets the first sample depth column, second chronology gets the second set of sample depths, etc. If there are less sample depth columns than chronologies, the sample depths are recycled. Defaults to `NULL`: no chronologies are written.
`prec`	optional `numeric` indicating the rounding precision of the output file when writing the data contained in `rwl.df`. Defaults to `NULL`: no rounding is done and the measurements are written in (non-integer) millimetres. Possible `numeric` values are 0.001, 0.01, 0.05, 0.1, 1, 10, 100 and 1000, which cause the data to be transformed to micrometres, 1/100th millimetres, 1/20th millimetres, 1/10 millimetres, (millimetres), centimetres, decimetres or metres, respectively, and then rounded to integral values. Data rounded to decimetres are written in centimetres (values always ending in zero). Otherwise, the matching unit is used in the file.
`ids`	optional `data.frame` with column one named `"tree"` giving the `numeric` ID of the tree, column two named `"core"` giving the `numeric` ID of the core, optional column three named `"radius"` giving the `numeric` ID of the radius, and optional column four named `"measurement"` giving the `numeric` ID of the measurement. If column `"measurement"` exists, column `"radius"` must also exist. Defaults to one core, radius and measurement per tree: data.frame(tree=1:n.col, core=rep(1,n.col), radius=rep(1,n.col), measurement=rep(1,n.col)) where `n.col` is the number of columns in `rwl.df`.
`titles`	optional `data.frame` with column one named `"tree"` giving the title of the tree, column two named `"core"` giving the title of the core, column three named `"radius"` giving the title of the radius, and column four named `"measurement"` giving the title of the measurement. By default, `titles` is `NULL`, and the title hierarchy is automatically created out of the column names of `rwl.df`, taking `ids` into account.
`crn.types`	`character` vector or a `list` of `character` vectors giving the types of the derived series in `crn`. A single vector is interpreted as one type per `data.frame` in `crn`, recycled if not long enough. A list of vectors is interpreted as one list element per `data.frame`. In this case, the list is recycled to the correct length. After that, the vectors inside the list are recycled to match the number of derived series in each `data.frame` of `crn`. The default is to write empty ‘⁠<type>⁠’ elements.
`crn.titles`	optional `character` vector or a `list` of `character` vectors giving the titles of the derived series in `crn`. The interpretation is the same as with `crn.types`, except that the default is to derive the titles from the column names of `crn`. Also `NA` means that the column name is used.
`crn.units`	optional `character` vector or a `list` of `character` vectors giving the units of the derived series in `crn`. The interpretation is the same as with `crn.types`, except that the default is to mark the series as ‘⁠<unitless>⁠’. Also `NA` means ‘⁠<unitless>⁠’.
`tridas.measuring.method`	`character` vector giving the measuring method used to acquire each series of `rwl.df`. Partial matching is used to replace these with the complete terms in `tridas.vocabulary`. If the vector is shorter than the number of columns in `rwl.df`, it is recycled to the correct length. The default is to use the information in `other.measuring.method` instead. Also, `NA` in any position of the vector means that the measuring method information for that series is looked up in `other.measuring.method`.
`other.measuring.method`	`character` vector giving the measuring method used to acquire each series of `rwl.df`. In contrast to `tridas.measuring.method`, these are free-form strings in English. If the vector is shorter than the number of columns in `rwl.df`, it is recycled to the correct length. The default value is `"unknown"`.
`sample.type`	optional `character` vector giving the type of the samples, corresponding to `"core"` in `ids`. The length of the vector, however, must match the number of columns in `rwl.df`, or it is recycled to the correct length. If there are several measurements per sample, some elements of `sample.type` are redundant. The default is to use `"core"` for all series.
`wood.completeness`	optional `data.frame` giving wood completeness information for the measurement series in `rwl.df`. The number of rows must match the number of columns in `rwl.df`. The columns are expected to be a subset of the following (descriptions almost directly quoted from TRiDaS specification): n.unmeasured.inner Field for recording whether there are any rings at the inner (i.e. towards pith) edge of the sample that have not been measured. Typically used to note when rings are too damaged to measure. Non-negative integral value. n.unmeasured.outer Field for recording whether there are any rings at the outer (i.e. towards bark) edge of the sample that have not been measured. Typically used to note when rings are too damaged to measure. Non-negative integral value. pith.presence Whether the pith is present or absent. Each element must be a partial match with the contents of category `"complex presence / absence"` in `tridas.vocabulary`. heartwood.presence Whether the outer (youngest) heartwood is present and if so whether it is complete. Category `"complex presence / absence"` in `tridas.vocabulary`. n.missing.heartwood Estimated number of missing heartwood rings to the pith. Non-negative integral value. missing.heartwood.foundation Description of the way the estimation of how many heartwood rings are missing was made and what the certainty is. Free-form string. sapwood.presence Whether the sapwood is present or not. Category `"complex presence / absence"`. n.sapwood Number of sapwood rings measured. Non-negative integral value. last.ring.presence Last ring under the bark is present or absent. Category `"presence / absence"`. last.ring.details If the last ring under the bark is present, include information about the completeness of this ring and/or season of felling. Free-form string. n.missing.sapwood Estimated number of missing sapwood rings to the bark. Non-negative integral value. missing.sapwood.foundation Description of the way the estimation of how many sapwood rings are missing was made and what the certainty is. Free-form string. bark.presence Bark is present or absent. Category `"presence / absence"` in `tridas.vocabulary`.
`taxon`	`character` string. The most detailed taxonomic name known for this element (species, genus, family etc). Preferably from the Catalogue of Life controlled vocabulary. The same string is used for all of `rwl.df`. The default value is an empty string, but a proper value should really be given.
`tridas.variable`	`character` string. Measured variable (ring width, earlywood, latewood etc) taken from the TRiDaS controlled vocabulary (`tridas.vocabulary`, category `"variable"`). The same string is used for all of `rwl.df`. Defaults to `"ring width"`.
`other.variable`	`character` string. Measured variable as a free-form string. The same string is used for all of `rwl.df`. This is only used if `tridas.variable` is `NA`.
`project.info`	`list` containing information about the project. Elements are the following (includes quotes from the TRiDaS specification): type `character` vector. The type(s) of the project. Defaults to `"unknown"`. description `character` string. A description of the project. Defaults to `NULL`: no description. title `character` string. The title of the project. Defaults to an empty string. category `character` string. Category of research this project falls into. Defaults to an empty string. investigator `character` string. Principal investigator of this project. Defaults to an empty string. period `character` string. When the dendrochronological project took place. Could consist of a start- and end-date. If unknown it should be estimated. Defaults to an empty string.
`lab.info`	`data.frame`. Information about the dendrochronological research laboratories where this work was done. One row per laboratory. Defaults to one laboratory with an empty name and no other information. The columns are expected to be a subset of the following: name Name of the laboratory acronym Optional acronym of the laboratory identifier Optional identifier of the laboratory domain The domain which the identifier of the laboratory is applicable to. Could be the URL of the organization’s server or the name of the organization as long as it is not ambiguous. addressLine1 First address line addressLine2 Second address line cityOrTown City or town stateProvinceRegion State, province or region postalCode Postal code. Beware of ignored leading zeros if these are given in `numeric` or `integer` type values. It is always safe to use `character` values. country Country
`research.info`	optional `data.frame` with information about the systems in which the research project is registered. Columns are the following: identifier Identifier domain Domain which the identifier is applicable to description General description
`site.info`	`list` containing information about the site (‘⁠<object>⁠’). Elements are the following, and all are `character` strings: type Type of the site. Defaults to `"unknown"`. description Description. Defaults to no description. title Title of the site. Defaults to an empty string.
`random.identifiers`	`logical` flag. If `TRUE`, unique random identifiers are created with `uuid.gen` and attached to each ‘⁠<project>⁠’ (one in the file), ‘⁠object⁠’ (site, one in the file), ‘⁠<element>⁠’ (tree), ‘⁠<sample>⁠’ (core), ‘⁠<radius>⁠’, ‘⁠<measurementSeries>⁠’ (measurement) and ‘⁠<derivedSeries>⁠’ element in the resulting TRiDaS file.
`identifier.domain`	`character` string. The domain which the random identifiers are applicable to. Could be the URL of the organization’s server or the name of the organization as long as it is not ambiguous. Defaults to the name of the first laboratory in `lab.info`.
`...`	Unknown arguments are accepted but not used.

Details

The Tree Ring Data Standard (TRiDaS) is described in Jansma et. al (2010).

Value

fname

Note

This is an early version of the function. Bugs are likely to exist, and parameters are subject to change.

Author(s)

Mikko Korpela

References

Jansma, E., Brewer, P. W., and Zandhuis, I. (2010) TRiDaS 1.1: The tree-ring data standard. Dendrochronologia, 28(2), 99–130.

Examples

library(utils)
## Not run: 
## Write raw ring widths
data(co021)
fname1 <- write.tridas(rwl.df = co021,
    fname = tempfile(fileext=".xml"), prec = 0.01,
    site.info = list(title = "Schulman old tree no. 1, Mesa Verde",
                     type = "unknown"),
    taxon = "Pseudotsuga menziesii var. menziesii (Mirb.) Franco",
    project.info = list(investigator = "E. Schulman",
                        title = "", category = "",
                        period = "", type = "unknown"))
print(fname1) # tempfile used for output

## Write mean value chronology of detrended ring widths
data(ca533)
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
ca533.crn <- chron(ca533.rwi, prewhiten = TRUE)
fname2 <- write.tridas(crn = ca533.crn,
    fname = tempfile(fileext=".xml"),
    taxon = "Pinus longaeva D.K. Bailey",
    project.info =
        list(investigator = "Donald A. Graybill, V.C. LaMarche, Jr.",
             title = "Campito Mountain", category = "",
             period = "", type = "unknown"))
print(fname2) # tempfile used for output

unlink(c(fname1, fname2)) # remove the files

## End(Not run)

[Package dplR version 1.7.7 Index]