detrend.series: Detrend a Ring-Width Series

In dplR: Dendrochronology Program Library in R

Detrend a Ring-Width Series

Description

Detrend a tree-ring series by one of two methods, a smoothing spline or a statistical model. The series and fits are plotted by default.

Usage

detrend.series(y, y.name = "", make.plot = TRUE,
               method = c("Spline", "ModNegExp", "Mean", 
               "Ar", "Friedman", "ModHugershoff","AgeDepSpline"),
               nyrs = NULL, f = 0.5, pos.slope = FALSE,
               constrain.nls = c("never", "when.fail", "always"),
               verbose = FALSE, return.info = FALSE,
               wt, span = "cv", bass = 0, difference = FALSE)

Arguments

y	a numeric vector. Usually a tree-ring series.
y.name	an optional character vector to name the series for plotting purposes.
make.plot	a logical flag. Makes plots of the raw data and detrended data if TRUE.
method	a character vector to determine the detrending methods. See details below. Possible values are all subsets of c("Spline", "ModNegExp", "Mean", "Ar", "Friedman", "ModHugershoff", "AgeDepSpline"). Defaults to using all the available methods.
nyrs	a number controlling the smoothness of the fitted curve in methods. See Details.
f	a number between 0 and 1 giving the frequency response or wavelength cutoff in method "Spline". Defaults to 0.5. See caps.
pos.slope	a logical flag. Will allow for a positive slope to be used in method "ModNegExp" or "AgeDepSpline". If FALSE the line will be horizontal.
constrain.nls	a character string which controls the constraints of the "ModNegExp" model and and the "ModHugershoff" model which are fit using nonlinear least-squares via nls. The value is an answer to the question: When should the parameters of the nls function be constrained? The options are "never": do not constrain (the default), "when.fail": only compute the constrained solution if the unconstrained fit contains other than positive values, and "always": return the constrained solution, even if the unconstrained one would have been valid. See ‘Details’.
verbose	a logical flag. Write out details to the screen?
return.info	a logical flag. If TRUE, details about models and data will be added to the return value. See ‘Value’.
wt	a numeric vector of case weights for method "Friedman". The default means equals weights.
span	a numeric value controlling method "Friedman", or "cv" (default) for automatic choice by cross-validation. See supsmu.
bass	a numeric value controlling the smoothness of the fitted curve in method "Friedman". See supsmu.
difference	a logical flag. Compute residuals by subtraction if TRUE, otherwise use division.

Details

This detrends and standardizes a tree-ring series. The detrending is the estimation and removal of the tree’s natural biological growth trend. The default standardization is done by dividing each series by the growth trend to produce units in the dimensionless ring-width index (RWI). If difference is TRUE, the index is calculated by subtraction. Values of zero (typically missing rings) in y are set to 0.001.

There are currently seven methods available for detrending although more are certainly possible. The methods implemented are an age-dependent spline via ads (method = "AgeDepSpline"), the residuals of an AR model (method = "Ar"), Friedman's Super Smoother (method = "Friedman"), a simple horizontal line (method = "Mean"), or a modified Hugershoff curve (method = "ModHugershoff"), a modified negative exponential curve (method = "ModNegExp"), and a smoothing spline via caps (method = "Spline").

The "AgeDepSpline" approach uses an age-dependent spline with an initial stiffness of 50 (codenyrs=50). See ads. If some of the fitted values are not positive then method "Mean" is used. However, this is extremely unlikely.

The "Ar" approach is also known as prewhitening where the detrended series is the residuals of an ar model divided by the mean of those residuals to yield a series with white noise and a mean of one. This method removes all but the high frequency variation in the series and should only be used as such.

The "Friedman" approach uses Friedman’s ‘super smoother’ as implemented in supsmu. The parameters wt, span and bass can be adjusted, but periodic is always set to FALSE. If some of the fitted values are not positive then method "Mean" is used.

The "Mean" approach fits a horizontal line using the mean of the series. This method is the fallback solution in cases where the "Spline" or the linear fit (also a fallback solution itself) contains zeros or negative values, which would lead to invalid ring-width indices.

The "ModHugershoff" approach attempts to fit a Hugershoff model of biological growth of the form f(t) = a t^b e^{-g t} + d, where the argument of the function is time, using nls. See Fritts (2001) for details about the parameters. Option constrain.nls gives a possibility to constrain the parameters of the modified negative exponential function. If the constraints are enabled, the nonlinear optimization algorithm is instructed to keep the parameters in the following ranges: a \ge 0, b \ge 0 and d \ge 0. The default is to not constrain the parameters (constrain.nls = "never") for nls but warn the user when the parameters go out of range.

If a suitable nonlinear model cannot be fit (function is non-decreasing or some values are not positive) then a linear model is fit. That linear model can have a positive slope unless pos.slope is FALSE in which case method "Mean" is used.

The "ModNegExp" approach attempts to fit a classic nonlinear model of biological growth of the form f(t) = a e^{b t} + k, where the argument of the function is time, using nls. See Fritts (2001) for details about the parameters. Option constrain.nls gives a possibility to constrain the parameters of the modified negative exponential function. If the constraints are enabled, the nonlinear optimization algorithm is instructed to keep the parameters in the following ranges: a \ge 0, b \le 0 and k \ge 0. The default is to not constrain the parameters (constrain.nls = "never") for nls but warn the user when the parameters go out of range.

If a suitable nonlinear model cannot be fit (function is non-decreasing or some values are not positive) then a linear model is fit. That linear model can have a positive slope unless pos.slope is FALSE in which case method "Mean" is used.

The "Spline" approach uses a spline where the frequency response is 0.50 at a wavelength of 0.67 * “series length in years”, unless specified differently using nyrs and f in the function caps. If some of the fitted values are not positive then method "Mean" is used.

These methods are chosen because they are commonly used in dendrochronology. There is a rich literature on detrending and many researchers are particularly skeptical of the use of the classic nonlinear model of biological growth (f(t) = a e^{b t} + k) for detrending. It is, of course, up to the user to determine the best detrending method for their data.

Note that the user receives a warning if a series has negative values in the fitted curve. This happens fairly commonly with with the ‘Ar’ method on high-order data. It happens less often with method ‘Spline’ but isn't unheard of (see ‘Examples’). If this happens, users should look carefully at their data before continuing. Automating detrending and not evaluating each series individually is folly. Remember, frustration over detrending is the number one cause of dendros going to live as hermits in the tallgrass prairie, where there are no trees to worry about.

See the references below for further details on detrending. It's a dark art.

Value

If several methods are used, returns a data.frame containing the detrended series (y) according to the methods used. The columns are named and ordered to match method. If only one method is selected, returns a vector.

If return.info is TRUE, the return value is a list with four parts:

series	the main result described above (data.frame or vector)
curves	the curve or line used to detrend series. Either a data.frame or vector.
model.info	Information about the models corresponding to each output series. Whereas series may return a vector, model.info is always a list where each top level element corresponds to one selected method. Also these elements are named and arranged according to the methods selected. Each element is a list with some of the following sub-elements, depending on which detrending method was actually used: n.zeros See "data.info" below. Always present. zero.years See "data.info". Always present. method The method actually used for detrending. One of "Mean", "Line", "ModNegExp", "Spline" or "Ar". Always present. mean Mean of the input series, missing values removed. Only for method "Mean". coefs Coefficients of the model. Methods "Line" and "ModNegExp". formula The "ModNegExp" formula. is.constrained A logical flag indicating whether the parameters of the "ModNegExp" model were constrained. Only interesting when argument constrain.nls is set to "when.fail". nyrs The value of nyrs used for caps. For methods "Spline" and "AgeDepSpline". order The order of the autoregressive model, selected by AIC (Akaike information criterion). Only for method "Ar". ar The autoregressive coefficients used by method "Ar". A numeric vector ordered by increasing lag.
data.info	Information about the input series: number ("n.zeros") and location ("zero.years") of zero values. If the locations are in a character vector, they are years. Otherwise they are indices to the input series.
dirtDog	A logical flag indicating whether the requested method resulted in neagtive values for the curve fit, what Cook's ARSTAN called a Dirty Dog.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela. A bug fix related to negative output values is based on work by Alice Cecile.

References

Cook, E. R. and Kairiukstis, L. A., editors (1990) Methods of Dendrochronology: Applications in the Environmental Sciences. Springer. ISBN-13: 978-0-7923-0586-6.

Fritts, H. C. (2001) Tree Rings and Climate. Blackburn. ISBN-13: 978-1-930665-39-2.

See Also

detrend

Examples

library(stats)
library(utils)
## Use series CAM011 from the Campito data set
data(ca533)
series <- ca533[, "CAM011"]
names(series) <- rownames(ca533)
# defaults to all six methods
series.rwi <- detrend.series(y = series, y.name = "CAM011", verbose=TRUE)
# see plot with three methods
series.rwi <- detrend.series(y = series, y.name = "CAM011",
                             method=c("Spline", "ModNegExp","Friedman"),
                             difference=TRUE)
# see plot with two methods
# interesting to note difference from ~200 to 250 years 
# in terms of what happens to low frequency growth
series.rwi <- detrend.series(y = series, y.name = "CAM011",
                             method=c("Spline", "ModNegExp"))
# see plot with just one method and change the spline
# stiffness to 50 years (which is not neccesarily a good choice!)
series.rwi <- detrend.series(y = series, y.name = "CAM011",
                             method="Spline",nyrs=50)
                             
# note that method "Ar" doesn't get plotted in first panel
# since this approach doesn't approximate a growth curve.
series.rwi <- detrend.series(y = series, y.name = "CAM011",
                             method="Ar")
                             
# note the difference between ModNegExp and ModHugershoff at the 
# start of the series. Also notice how curves, etc. are returned
# via return.info
data(co021)
series <- co021[, 4]
names(series) <- rownames(co021)
series.rwi <- detrend.series(y = series, y.name = names(co021)[4],
                             method=c("ModNegExp", "ModHugershoff"),
                             verbose = TRUE, return.info = TRUE, 
                             make.plot = TRUE)
                             
# A dirty dog.
# In the case of method=="Spline" the function carries-on
# and applies method=="Mean" as an alternative. 
data(nm046)
series <- nm046[,8]
names(series) <- rownames(nm046)
series.rwi <- detrend.series(y = series, y.name = names(nm046)[8],
                             method="Spline",
                             make.plot = FALSE)

dplR documentation built on Aug. 30, 2023, 9:08 a.m.