R: Detrend Multiple Ring-Width Series Simultaneously

detrend {dplR} | R Documentation

## 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"),
            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")`. 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)

[Package dplR version 1.7.1 Index]