detrend: Detrend Multiple Ring-Width Series Simultaneously

In dplR: Dendrochronology Program Library in R

Detrend Multiple Ring-Width Series Simultaneously

Description

This is a wrapper for detrend.series to detrend many ring-width series at once.

Usage

detrend(rwl, y.name = names(rwl), make.plot = FALSE,
        method = "Spline",
        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

rwl	a data.frame with series as columns and years as rows such as that produced by read.rwl
y.name	a character vector of length(ncol(rwl)) that gives the ID of each series. Defaults to the column names of rwl.
make.plot	a logical flag. Makes plots of the raw data and detrended data if TRUE. See details below.
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 "Spline". Before dplR 1.8.0 the default was all the available methods.
nyrs	a number giving the rigidity of the smoothing spline, defaults to 0.67 of series length if nyrs is NULL.
f	a number between 0 and 1 giving the frequency response or wavelength cutoff. Defaults to 0.5.
pos.slope	a logical flag. Will allow for a positive slope to be used in method "ModNegExp" and "ModHugershoff". If FALSE the line will be horizontal.
constrain.nls	a character string which controls the constraints of the "ModNegExp" model and the "ModHugershoff". See detrend.series for further details.
verbose	logical. Write out details?
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

See detrend.series for details on detrending methods. Setting make.plot = TRUE will cause plots of each series to be produced. These could be saved using Devices if desired.

A series with no values at all is dropped, with a message naming it, and the rest are detrended as if it had never been there; its name is dropped from y.name too. x[rows, ] and head can leave such a series (see [.rwl). If no series has any values, that is an error. A series with NA inside its measured span stops the call, with a message naming the series; see fill.internal.NA.

Value

If one detrending method is used, an object of class c("rwi", "data.frame") containing the dimensionless detrended ring widths with the column names, row names and dimensions of rwl, less any series with no values. It records how it was made in attr(x, "dplR.detrend") and carries the provenance record of rwl, if it has one; see as.rwi. If more methods are used, a list with ncol(rwl) elements each containing a data.frame with the detrended ring widths in each column.

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

series	the main result described above (data.frame or list of data.frames)
curves	the curve or line used to detrend series. Either a data.frame or a list of data.frames.
model.info	Information about the models corresponding to each output series. A list with one element for each column of rwl. See detrend.series (‘Value’, model.info) for a description of the contents.
data.info	Information about the input series. A list with one element for each column of rwl. See detrend.series (‘Value’, data.info).

Note

This function uses the foreach looping construct with the %dopar% operator. For parallel computing and a potential speedup, a parallel backend must be registered before running the function. If verbose is TRUE, parallel computation is disabled.

Author(s)

Andy Bunn. Improved by Mikko Korpela.

See Also

detrend.series, as.rwi

Examples

library(utils)
data(ca533)
## Detrend using modified exponential decay. Returns an rwi object
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
## Detrend using splines and compute
## residuals via subtraction
ca533.rwi <- detrend(rwl = ca533, method = "Spline",
                     difference = TRUE)

## Detrend using modified Hugershoff curve and return info on the model
## fits. Returns a list with: series, curves, modelinfo and data.info
data(co021)
co021.rwi <- detrend(rwl = co021, method = "ModHugershoff",
                     return.info=TRUE)

## Not run: 
library(grDevices)
## Detrend using all methods. Returns a list
ca533.rwi <- detrend(rwl = ca533,
                     method = c("Spline", "ModNegExp", "Mean", "Ar",
                                "Friedman", "ModHugershoff", "AgeDepSpline"))
## Save a pdf of all series
fname <- tempfile(fileext=".pdf")
print(fname) # tempfile used for output
pdf(fname)
ca533.rwi <- detrend(rwl = ca533, method = c("Spline", "ModNegExp"),
                     make.plot = TRUE)
dev.off()

unlink(fname) # remove the file

## End(Not run)

dplR documentation built on Oct. 1, 2026, 9:07 a.m.