read.tridas: Read Tree Ring Data Standard (TRiDaS) File

View source: R/read.tridas.R

read.tridasR Documentation

Read Tree Ring Data Standard (TRiDaS) File

Description

This function reads in a TRiDaS format XML file. Measurements, derived series and various kinds of metadata are supported.

Usage

read.tridas(fname, ids.from.titles = FALSE,
            ids.from.identifiers = TRUE, combine.series = TRUE,
            trim.whitespace = TRUE, warn.units = TRUE)

Arguments

fname

character vector giving the file name of the TRiDaS file.

ids.from.titles

logical flag indicating whether to override the (tree, core, radius, measurement) structure imposed by the element hierarchy (element, sample, radius, measurementSeries) of the file. If TRUE, measurement series will be rearranged by matching titles in the file at the aforementioned four levels of the hierarchy. Defaults to FALSE, i.e. the element hierarchy of the file will be used.

ids.from.identifiers

logical flag indicating whether to (partially) override the element hierarchy of the file. If TRUE, measurement series will be grouped according to matching identifiers at the measurementSeries level, where identifiers are available. The changes caused by this option are applied on top of the structure imposed by the file or computed from matching titles if ids.from.titles == TRUE. Defaults to TRUE.

combine.series

logical flag indicating whether to combine two or more measurement series with the same set of (tree, core, radius, measurement) ID numbers. Each set of combined measurement series will be represented by one column of a resulting data.frame. Overlapping years of combined series do not produce a warning. If several data points are available for a given year, the function chooses one in a rather arbitrary manner. This option can only have effect when ids.from.titles || ids.from.identifiers.

trim.whitespace

logical flag indicating whether to replace repeated white spaces in the text content of the file with only one space. Defaults to TRUE, i.e. excess white space will be trimmed from the text.

warn.units

logical flag indicating whether to warn about unitless measurements and “strange” units. The function expects measurements in units that can be converted to millimetres. Defaults to TRUE: warnings will be given. For example, density measurements will trigger warnings, which can be disabled by setting this option to FALSE.

Details

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

The parameters used for rearranging (ids.from.titles, ids.from.identifiers) and combining (combine.series) measurement series only affect the four lowest levels of document structure: element, sample, radius, measurementSeries. Series are not reorganized or combined at the upper structural levels (project, object).

Value

A list with a variable number of components according to the contents of the input file. The possible list components are:

measurements

A data.frame or a list of data.frames with the series in columns and the years as rows. Contains measurements (‘⁠<measurementSeries>⁠’) with known years. The series IDs are the column names and the years are the row names. The series IDs are derived from ‘⁠<title>⁠’ elements in the input file. Each unique combination of ‘⁠<project>⁠’, ‘⁠<object>⁠’, ‘⁠<unit>⁠’, ‘⁠<taxon>⁠’, and ‘⁠<variable>⁠’ gets a separate data.frame.

ids

A data.frame or a list of data.frames with columns named "tree", "core", "radius", and "measurement", together giving a unique numeric ID for each column of the data.frame(s) in measurements.

If !combine.series && (ids.from.titles || ids.from.identifiers), some rows may be non-unique.

titles

A data.frame or a list of data.frames with columns named "tree", "core", "radius", and "measurement", containing the ‘⁠<title>⁠’ hierarchy of each column of the data.frame(s) in measurements.

wood.completeness

A data.frame or a list of data.frames containing wood completeness information. Column names are a subset of the following, almost self-explanatory set: "pith.presence", "heartwood.presence", "sapwood.presence",
"last.ring.presence", "last.ring.details", "bark.presence",
"n.sapwood", "n.missing.heartwood", "n.missing.sapwood",
"missing.heartwood.foundation", "missing.sapwood.foundation",
"n.unmeasured.inner", "n.unmeasured.outer".

unit

A character vector giving the unit of the measurements. Length equals the number of data.frames in measurements.

project.id

A numeric vector giving the project ID, i.e. the position of the corresponding ‘⁠<project>⁠’ element), of the measurements in each data.frame in measurements. Length equals the number of data.frames.

project.title

A character vector giving the title of the project of each data.frame in measurements. Length equals the number of data.frames.

site.id

A data.frame giving the site ID (position of ‘⁠<object>⁠’ element(s) within a ‘⁠<project>⁠’) of each data.frame in measurements. May have several columns to reflect the possibly nested ‘⁠<object>⁠’ elements.

site.title

A data.frame giving the site (‘⁠<object>⁠’) title of each data.frame in measurements. May have several columns to reflect the possibly nested ‘⁠<object>⁠’ elements.

taxon

A data.frame showing the taxonomic name for each data.frame in measurements. Contains some of the following columns: "text", "lang", "normal", "normalId", "normalStd". The first two are a free-form name and its language, and the rest are related to a normalized name.

variable

A data.frame showing the measured variable of each data.frame in measurements. Contains some of the following columns: "text", "lang", "normal", "normalId", "normalStd", "normalTridas". The first two are a free-form name and its language, and the rest are related to a normalized name.

undated

A list of measurements with unknown years, together with metadata. Elements are a subset of the following:

data

A numeric vector or a list of such vectors containing measurement series

unit

A character vector giving the unit of the measurements. Length equals the number of measurement series in undated$data

ids

A data.frame with columns named "tree", "core", "radius", and "measurement", together giving a numeric ID for each measurement series in undated$data. The rows are guaranteed to be unique only when comparing measurement series with the same project.id and site.id, but not if ids.from.titles || ids.from.identifiers.

titles

A data.frame with columns named "tree", "core", "radius", and "measurement", containing the ‘⁠<title>⁠’ hierarchy of each measurement series in undated$data

project.id

A numeric vector giving the project ID of each measurement series in undated$data

project.title

A character vector giving the project title of each measurement series in undated$data

site.id

A data.frame giving the site ID of each measurement series in undated$data

site.title

A data.frame giving the site title of each measurement series in undated$data

variable

A data.frame containing the variable of each measurement series in undated$data

taxon

A data.frame containing taxonomic names of each measurement series in undated$data

wood.completeness

A data.frame containing wood completeness information of each measurement series in undated$data

derived

A list of calculated series of values, together with metadata. Elements are a subset of the following:

data

A numeric vector or a list of such vectors containing calculated series of values.

link

A list of data.frames, one for each series in derived$data, giving links to the measurements used to form the corresponding derived series. Each data.frame has a subset of the following columns: "idRef" (reference to a series in the same file), "xLink" (URI), "identifier", and "domain" (identifier and its domain, not necessarily in the same file).

project.id

A numeric vector giving the project ID of each derived series in derived$data

id

A numeric vector giving the ID (order of appearance in the project) of each derived series in derived$data

title

A character vector giving the title of each derived series in derived$data

project.title

A character vector giving the project title of each derived series in derived$data

unit

A character vector giving the unit of the derived series. Length equals the number of series in derived$data.

standardizing.method

A character vector giving the standardizing method of the derived series. Length equals the number of series in derived$data.

variable

A data.frame containing the variable of each series in derived$data

type

A data.frame containing the type of various entities, and metadata related to each ‘⁠type⁠’ element. Contents are NA where the metadata is not applicable (e.g., no tree.id when the ‘⁠type⁠’ element refers to a project). Columns are a subset of the following:

text

The text of the ‘⁠type⁠’ element

lang

The language of the text

normal

The normalized name of the type

normalId

The ID value of the type in the standard dictionary

normalStd

The name of the standard

project.id

The ID of the project

site.id

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the ID of the site where the ‘⁠<type>⁠’ element appeared.

tree.id

The ID of the tree

core.id

The ID of the core

derived.id

The ID of the derived series

project.title

The title of the project

site.title

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the title of the site where the ‘⁠<type>⁠’ element appeared.

tree.title

The title of the tree

core.title

The title of the core

derived.title

The title of the derived series

comments

A data.frame containing comments to various entities, and metadata related to each ‘⁠comments⁠’ element. Contents are NA where the metadata is not applicable. Columns are a subset of the following:

text

The text of the ‘⁠comments⁠’ element

project.id

The ID of the project

site.id

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the ID of the site.

tree.id

The ID of the tree

core.id

The ID of the core

radius.id

The ID of the radius

measurement.id

The ID of the measurement series

derived.id

The ID of the derived series

project.title

The title of the project

site.title

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the title of the site.

tree.title

The title of the tree

core.title

The title of the core

radius.title

The title of the radius

measurement.title

The title of the measurement series

derived.title

The title of the derived series

identifier

A data.frame containing identifiers of various entities, and metadata related to each ‘⁠identifier⁠’ element. Contents are NA where the metadata is not applicable. Columns are a subset of the following:

text

The text of the ‘⁠identifier⁠’ element

domain

The domain which the identifier is applicable to

project.id

The ID of the project

site.id

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the ID of the site.

tree.id

The ID of the tree

core.id

The ID of the core

radius.id

The ID of the radius

measurement.id

The ID of the measurement series

derived.id

The ID of the derived series

project.title

The title of the project

site.title

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the title of the site.

tree.title

The title of the tree

core.title

The title of the core

radius.title

The title of the radius

measurement.title

The title of the measurement series

derived.title

The title of the derived series

remark

A list of remarks concerning individual measured or derived values, with some of the following items:

measurements

Remarks related to measurements with a known year. A data.frame with the following columns:

text

The remark

frame

Index to a data.frame in measurements

row

Index to a row of the data.frame

col

Index to a column of the data.frame

undated

Remarks related to measurements without a known year. A data.frame with the following columns:

text

The remark

series

Index to a series in undated$data

idx

Index to a value in the series

derived

Remarks related to derived values. A data.frame with the following columns:

text

The remark

series

Index to a series in derived$data

idx

Index to a value in the series

laboratory

A data.frame or a list of data.frames with one item per project. Each data.frame contains information about the research laboratories involved in the project. Columns are a subset of the following:

name

Name of the laboratory

acronym

Acronym of the name

identifier

Identifier

domain

Domain which the identifier is applicable to

addressLine1

Address

addressLine2

Another address line

cityOrTown

City or town

stateProvinceRegion

State, province or region

postalCode

Postal code

country

Country

research

A data.frame or a list of data.frames with one item per project. Each data.frame contains 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

altitude

A data.frame containing the altitude of trees. Columns are the following:

metres

The altitude in metres

project.id

The ID of the project

site.id

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the ID of the site.

tree.id

The ID of the tree

project.title

The title of the project

site.title

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the title of the site.

tree.title

The title of the tree

preferred

A data.frame containing links to preferred measurement series. Columns are a subset of the following:

idRef

Reference to a series in the same file

xLink

URI

identifier

Identifier of a series not necessarily in the same file

domain

Domain which the identifier is applicable to

project.id

The ID of the project

site.id

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the ID of the site.

tree.id

The ID of the tree

project.title

The title of the project

site.title

One or more columns with this prefix, depending on the maximum depth of the ‘⁠<object>⁠’ hierarchy. Gives the title of the site.

tree.title

The title of the tree

Note

This is an early version of the function. Bugs are likely to exist, and parameters and return values are subject to change. Not all metadata defined in the TRiDaS specification is supported – unsupported elements are quietly ignored.

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

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


dplR documentation built on June 22, 2024, 9:59 a.m.