phase_def: Define stem-cyclic phases
In dendrometeR: Analyzing Dendrometer Data

phase_def

R Documentation

Define stem-cyclic phases

Description

The function identifies and assigns each timestamp to one of the three distinct phases of contraction, expansion and stem-radius increment (Deslauriers et al. 2011) for dendrometer series from a data.frame with gap-free dendrometer data.

Usage

phase_def(dm.gpf, resolution = dendro.resolution(dm.gpf),
          shapeSensitivity = 0.6, minmaxDist = 0.2, minmaxSD = 2,
          radialIncrease = "max")

Arguments

`dm.gpf`	a `data.frame` with either gap-free or gap-filled dendrometer series as produced by `fill_gaps`.
`resolution`	a `numeric` specifying the resolution of the dendrometer data in seconds. Defaults to the resolution of `dm.gpf` as calculated using `dendro.resolution`.
`shapeSensitivity`	a `numeric` specifying a time window, defined as proportion of a single day. Within this time window possible extrema points (i.e. minimum and maximum) in dendrometer measurements are searched for. Defaults to 0.6 (60 percent of a day). See details for further explanation.
`minmaxDist`	a `numeric` specifying the minimum temporal distance between consecutive minimum and maximum points (i.e. in the x direction). Defaults to 0.2 (20 percent of a day).
`minmaxSD`	a `numeric` specifying the minimum difference between consecutive minimum and maximum points expressed as a number of standard deviations (i.e. in the y direction). Defaults to 2.
`radialIncrease`	a `character` string of `"max", "min", "mid"`, specifying when the stem-radius increment phase should start, with `"max"` as the most, and `"min"` as the least conservative approach; `"mid"` is in between. See details for further explanation.

Details

The function defines the stem-cyclic phases of contraction, expansion, and stem-radius increment, as described in Deslauriers et al. (2011). The function is a more robust version of the original SAS routine, as its architecture allows to handle noisy data as well.

First, the function searches for minimum and maximum points within a daily time window as specified by shapeSensitivity. Then, the original dendrometer series are offset by (1 - shapeSensitivity) / 2 in both directions to assure whether the identified extrema are indeed the extrema of cyclic phases. A comparison between the original and offset series allows to select all appropriate minimum and maximum values.

The arguments minmaxDist and minmaxSD specify the temporal distance and the minimum difference between consecutive minimum and maximum points (i.e. in x and y direction), respectively. The argument radialIncrease determines from which moment on data points should be assigned to the stem-radius increment phase: when points are continuously above the previous maximum ("max"), when a single data point is above the previous maximum ("min"), or right in between "min" and "max" ("mid").

Value

The function returns a data.frame with numbers indicating the different stem-cyclic phases: (1) contraction, (2) expansion, (3) stem-radius increment for each timestamp.

Author(s)

Marko Smiljanic

References

Deslauriers, A., Rossi, S., Turcotte, A., Morin, H. and Krause, C. (2011) A three-step procedure in SAS to analyze the time series from automatic dendrometers. Dendrochronologia 29: 151-161.