detrend.series {dplR}  R Documentation 
Detrend a treering series by one of two methods, a smoothing spline or a statistical model. The series and fits are plotted by default.
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)
y 
a 
y.name 
an optional 
make.plot 
a 
method 
a 
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 
pos.slope 
a 
constrain.nls 
a 
verbose 
a 
return.info 
a 
wt 
a 
span 
a 
bass 
a 
difference 
a 
This detrends and standardizes a treering 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 ringwidth 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 agedependent 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 agedependent spline with an initial
stiffness of 50 (nyrs=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
ringwidth 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 nondecreasing 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 nondecreasing 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 highorder 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.
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 ( 
curves 
the curve or line used to detrend 
model.info 
Information about the models corresponding to each
output 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. 
Andy Bunn. Patched and improved by Mikko Korpela. A bug fix related to negative output values is based on work by Alice Cecile.
Cook, E. R. and Kairiukstis, L. A., editors (1990) Methods of Dendrochronology: Applications in the Environmental Sciences. Springer. ISBN13: 9780792305866.
Fritts, H. C. (2001) Tree Rings and Climate. Blackburn. ISBN13: 9781930665392.
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 carrieson
# 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)