detrend {dplR}

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 = 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

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 using 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 substraction 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.

Value

If one detrending method is used, a data.frame containing the dimensionless detrended ring widths with column names, row names and dimensions of rwl. 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

Examples

library(utils)
data(ca533)
## Detrend using modified exponential decay. Returns a data.frame
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
## Detrend using a slines on power transformed data and compute
## residuals via subtraction
ca533.rwi <- detrend(rwl = powt(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)
## 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)