| detrend.series | R Documentation |
Detrend a Ring-Width Series
Description
Detrend a tree-ring series by one of two methods, a smoothing spline ora 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 |
y.name | an optional |
make.plot | a |
method | a |
nyrs | a number controlling the smoothness of thefitted curve in methods. See Details. |
f | a number between 0 and 1 giving the frequency response orwavelength cutoff in method |
pos.slope | a |
constrain.nls | a |
verbose | a |
return.info | a |
wt | a |
span | a |
bass | a |
difference | a |
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 fordetrending although more are certainly possible. The methodsimplemented 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 Hugershoffcurve (method = "ModHugershoff"), a modified negative exponentialcurve (method = "ModNegExp"), and a smoothing spline via caps (method = "Spline").
The "AgeDepSpline" approach uses an age-dependent spline with an initialstiffness of 50 (nyrs=50). See ads. If some of the fitted values are not positive then method "Mean" is used. However, this isextremely unlikely.
The "Ar" approach is also known as prewhitening where the detrended series is the residuals of an ar model divided by themean 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 seriesand should only be used as such.
The "Friedman" approach uses Friedman’s ‘supersmoother’ as implemented in supsmu. The parameterswt, span and bass can beadjusted, 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 ofthe 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 invalidring-width indices.
The "ModHugershoff" approach attempts to fit a Hugershoffmodel of biological growth of the form f(t) = a t^b e^{-g t} + d, where the argument of the function is time, usingnls. See Fritts (2001) for details about theparameters. Option constrain.nls gives apossibility to constrain the parameters of the modified negativeexponential function. If the constraints are enabled, the nonlinearoptimization algorithm is instructed to keep the parameters in thefollowing ranges: a \ge 0, b \ge 0 andd \ge 0. The default is to not constrain the parameters(constrain.nls = "never") for nls butwarn 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 alinear model is fit. That linear model can have a positive slopeunless pos.slope is FALSE in which case method"Mean" is used.
The "ModNegExp" approach attempts to fit a classic nonlinearmodel of biological growth of the form f(t) = a e^{b t} + k, where the argument of the function is time, usingnls. See Fritts (2001) for details about theparameters. Option constrain.nls gives apossibility to constrain the parameters of the modified negativeexponential function. If the constraints are enabled, the nonlinearoptimization algorithm is instructed to keep the parameters in thefollowing ranges: a \ge 0, b \le 0 andk \ge 0. The default is to not constrain the parameters(constrain.nls = "never") for nls butwarn 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 alinear model is fit. That linear model can have a positive slopeunless pos.slope is FALSE in which case method"Mean" is used.
The "Spline" approach uses a spline where the frequencyresponse is 0.50 at a wavelength of 0.67 * “series length inyears”, unless specified differently using nyrs andf 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 indendrochronology. There is a rich literature on detrendingand 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’ butisn't unheard of (see ‘Examples’). If this happens, users should lookcarefully 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 containingthe detrended series (y) according to the methods used.The columns are named and ordered to match method. Ifonly one method is selected, returns a vector.
If return.info is TRUE, the return value is alist with four parts:
series | the main result described above ( |
curves | the curve or line used to detrend |
model.info | Information about the models corresponding to eachoutput series. Whereas
|
data.info | Information about the input series: number( |
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 fixrelated to negative output values is based on work by Alice Cecile.
References
Cook, E. R. and Kairiukstis, L. A., editors (1990) Methods ofDendrochronology: 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 setdata(ca533)series <- ca533[, "CAM011"]names(series) <- rownames(ca533)# defaults to all six methodsseries.rwi <- detrend.series(y = series, y.name = "CAM011", verbose=TRUE)# see plot with three methodsseries.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 growthseries.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.infodata(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)