caps {dplR}

Cook and Peters Smoothing Spline with User-Specified Rigidity and Frequency Cutoff

Description

Applies a smoothing spline to y with rigidity determined by two parameters: frequency response f at a wavelength of nyrs years.

Usage

caps(y, nyrs = length(y) * 2/3, f = 0.5)

Arguments

y

a numeric vector, typically a tree-ring series.

nyrs

a number greater than zero, affecting the rigidity of the spline. If nyrs is between zero and one it will be treated as percentage of the length of the series. E.g., a value of 0.667 would 0.667 * length(y) or what is often called a 2/3 spline in the tree-ring literature (this is the default). When f is kept constant, a larger nyrs produces a more rigid spline.

f

a number between 0 and 1 giving the frequency response at a wavelength of nyrs years. When nyrs is kept constant, a smaller f produces a more rigid spline: At one extreme, f = 0 causes the function to return the least-squares straight line fit to the data. At the other extreme, as f approaches 1 the result approaches the natural spline, i.e. the function outputs y. The default value is 0.5 and shouldn't be changed without a good reason.

Details

This applies the classic smoothing spline from Cook and Peters (1981). The rigidity of the spline has a frequency response of 50% at a wavelength of nyrs. The references, of course, have more information.

This funciton was introduced to dplR in version 1.7.3 and essentially replaces ffcsaps for most uses. Where ffcsaps is written entirely in R, caps is a wrapper for a Fortran subroutine from Ed Cook's ARSTAN program that is thousands of times faster.

Note: like ffcsaps, caps returns NA if there are any NA values in y. See examples.

Value

A filtered vector.

Author(s)

Fotran code provided by Ed Cook and adapted for dplR by Andy Bunn.

References

Cook, E. R. and Kairiukstis, L. A., editors (1990) Methods of Dendrochronology: Applications in the Environmental Sciences. Springer. ISBN-13: 978-0-7923-0586-6.

Cook, E. R. and Peters, K. (1981) The Smoothing Spline: A New Approach to Standardizing Forest Interior Tree-Ring Width Series for Dendroclimatic Studies. Tree-Ring Bulletin, 41, 45-53.

See Also

ffcsaps, ads

Examples

library(graphics)
library(utils)

## Use first series from the Mesa Verde data set
data(co021)
series <- co021[, 1]
series <- series[!is.na(series)]
plot(series, type = "l", ylab = "Ring Width (mm)", col = "grey")
lines(caps(series, nyrs = 10), col = "red", lwd = 2)
lines(caps(series, nyrs = 100), col = "green", lwd = 2)
# A 2/3 spline, the default, 462.6667 yrs here
lines(caps(series), col = "blue", lwd = 2)
legend("topright",
       c("Series", "nyrs=10", "nyrs=100",
         paste("Default nyrs (", floor(length(series) * 2/3), ")", sep="")),
       fill=c("grey", "red", "green", "blue"))


## Note behavior when NA is encountered and
## take appropriate measures as demonstrated above
y <- c(NA,NA,rnorm(100))
caps(y)