dplR (version 1.8.0)

caps: 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 = 32, f = 0.5)

Value

A filtered vector.

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

Author

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

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 function was introduced to dplR in version 1.7.3 and replaces the now defunct ffcsaps. Where ffcsaps was written entirely in R, caps is a wrapper for a Fortran subroutine from Ed Cook's ARSTAN program that is hundreds of times faster.

The default value of nyrs was changed to 32 from 2/3 length of y in version 1.7.8 based on a suggestion from Klesse (2021).

Note: nyrs is passed to the Fortran subroutine as an integer, so a fractional nyrs is truncated. This matters when nyrs is given as a proportion of series length, which is rarely a whole number. The effect on the fitted curve is small but not zero; see the “Mathematical Details” vignette for a worked comparison.

Note: caps stops if there are any NA values in y. A smoothing spline through a series with missing values is not defined, and the caller has to decide what to do about the gap rather than have one chosen silently. Before version 1.8.0 such a call returned a vector of NA, which looked like an answer and was not. See examples, and fill.internal.NA.

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.

Klesse, S. (2021) Critical Note on the Application of the "Two-Third"" Spline. Dendrochronologia Volume 65: 125786

See Also

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)
# The default, a 32-year spline since version 1.7.8
lines(caps(series), col = "blue", lwd = 2)
legend("topright",
       c("Series", "nyrs=10", "nyrs=100", "Default nyrs (32)"),
       fill=c("grey", "red", "green", "blue"))


## caps() needs a series with no missing values. Note that the example
## above drops the NA padding before fitting. A gap inside the measured
## span has to be dealt with deliberately: drop the series, or close the
## gap with fill.internal.NA().
y <- c(NA, NA, rnorm(100))
try(caps(y))
## fit over the measured values instead
head(caps(y[!is.na(y)]))