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.frames containing tree-ring chronologies. Accepts data.frames 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.

See Also

write.rwl, write.tucson, write.compact, write.crn, read.tridas

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]