Package 'dplR'

Description

This package contains functions for performing some standard tree-ring analyses.

Details

Main Functions

read.rwl

reads rwl files

detrend

detrends raw ring widths

chron

builds chronologies

corr.rwl.seg

crossdating function

Author(s)

Andy Bunn [email protected] with major additions from Mikko Korpela and other significant contributions from Franco Biondi, Filipe Campelo, Pierre Mérian, Fares Qeadan and Christian Zang. Function redfit is an improved translation of program REDFIT which is original work of Manfred Mudelsee and Michael Schulz. Jacob Cecile contributed a bug fix to detrend.series. Allan Buras came up with the revised formula of glk in dplR >= 1.6.1.

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.

Fritts, H. C. (2001) Tree Rings and Climate. Blackburn. ISBN-13: 978-1-930665-39-2.

Description

Applies an age-dependent smoothing spline to y.

Usage

ads(y, nyrs0 = 50, pos.slope = TRUE)

Arguments

Details

This implements the age-dependent smoothing spline similar to that described by Melvin (2004). In this implementation a cubic smoothing spline (caps) is fit to y with an initial stiffness of nyrs0. For each succesive measurement, the siffness is incremented by that ring index. This results in a spline is nyrs0 flexible at the start of the series and grows progressively stiffer. This can help capture the initial fast growth of a juvinielle tree with a flexible spline that then progresses to a stiffer spline that can better model the constant growth commonly found in mature trees. In its details, the cubic smoothing spline follows the Cook and Peters (1981) spline with a 50% frequency cutoff. See Cook and Kairiukstis (1990) for more information.

The default setting for nyrs0 is 50 years which is approprite for trees with a classic growth model but a value of 10 or 20 might be more appropriate for a Hugershoff-like initial increase in growth. Cook (pers comm) suggests a value of 20 for RCS.

If pos.slope is TRUE, the function will attempt to prevent a postive slope at the end of the series. In some cases when ads is used for detrending, a postive slope can be considered considered biologically unlikely. In those cases, the user can contrain the positive slope in the slpine. This works by calculating the spline and taking the first difference. Then the function finds the last (outside) index where the spline changes slope and fixes the spline values from the that point to the end. Finally the spline is rerun along this contrained curve. See examples for details. The wisdom of contraining the slope in this manner depends very much on expert knowledge of the system.

Value

A filtered vector.

Author(s)

Fortran code provided by Ed Cook. Ported 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.

Melvin, T. M. (2004) Historical Growth Rates and Changing Climatic Sensitivity of Boreal Conifers. PhD Thesis, Climatic Research Unit, School of Environmental Sciences, University of East Anglia.

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

caps, detrend

Examples

# fit a curve
data(co021)
aSeries <- na.omit(co021$`641114`)
plot(aSeries,type="l",col="grey50")
lines(ads(y = aSeries),col="blue",lwd=2)

# show an artificial series with a Hugershoff-like curve.
a <- 0.5
b <- 1
g <- 0.1
d <- 0.25

n <- 300
x <- 1:n
y <- I(a*x^b*exp(-g*x)+d)
# add some noise
y <- y + runif(n=length(y),min = 0,max = 0.5)
# Plot with two different splines.
plot(y,type="l",col="grey50")
lines(ads(y,50),col="darkgreen",lwd=2) # bad
lines(ads(y,10),col="darkblue",lwd=2) # good

# now repeat with a positive slope to constrain
y <- I(a*x^b*exp(-g*x)+d)
y[251:300] <- y[251:300] + seq(0,0.25,length.out=50)
y <- y + runif(n=length(y),min = 0,max = 0.5)
plot(y,type="l",col="grey50")
lines(ads(y,10),col="darkgreen",lwd=2) #bad?
lines(ads(y,10,pos.slope=FALSE),col="darkgreen",lwd=2,lty="dashed")

Description

This data set gives the raw ring widths for Norway spruce Picea abies at Rothenburg ob der Tauber, Bavaria, Germany. There are 20 series from 10 trees. Data set was created using read.rwl and saved to an .rda file using save.

Usage

data(anos1)

Format

A data.frame containing 20 tree-ring series from 10 trees in columns and 98 years in rows. The correct stc mask for use with read.ids is c(5, 2, 1).

References

Zang, C. (2010) Growth reaction of temperate forest tree species to summer drought – a multispecies tree-ring network approach. Ph.D. thesis, Technische Universität München.

Description

Attempts to turn its argument into a rwl object.

Usage

as.rwl(x)

Arguments

Details

This tries to coerce x into class c("rwl","data.frame"). Failable.

Value

An object of class c("rwl", "data.frame") with the series in columns and the years as rows. The series IDs are the column names and the years are the row names.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

Examples

library(graphics)
library(stats)
library(utils)
## Toy
n <- 100
## Make a data.frame that is tree-ring like
base.series <- 0.75 + exp(-0.2 * 1:n)
foo <- data.frame(x1 = base.series + abs(rnorm(n, 0, 0.25)),
                  x2 = base.series + abs(rnorm(n, 0, 0.25)),
                  x3 = base.series + abs(rnorm(n, 0, 0.25)),
                  x4 = base.series + abs(rnorm(n, 0, 0.25)),
                  x5 = base.series + abs(rnorm(n, 0, 0.25)),
                  x6 = base.series + abs(rnorm(n, 0, 0.25)))
# coerce to rwl and use plot and summary methods
foo <- as.rwl(foo)
class(foo)
plot(foo, plot.type="spag")
summary(foo)

Description

Convert multiple ring-width series to basal area increment (i.e., ring area) going from the pith to the bark.

Usage

bai.in(rwl, d2pith = NULL)

Arguments

Details

This converts ring-width series (mm) to ring-area series (mm squared) (aka basal area increments) based on the distance between the innermost measured ring and the pith of the tree. It is related to bai.out, which calculates each ring area starting from the outside of the tree and working inward. Both methods assume a circular cross section (Biondi 1999). See the references below for further details.

Value

A data.frame containing the ring areas for each series with column names, row names and dimensions of rwl.

Note

DendroLab website: https://dendrolaborg.wordpress.com/

Author(s)

Code by Andy Bunn based on work from DendroLab, University of Nevada Reno, USA. Patched and improved by Mikko Korpela.

References

Biondi, F. (1999) Comparing tree-ring chronologies and repeated timber inventories as forest monitoring tools. Ecological Applications, 9(1), 216–227.

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

See Also

bai.out

Examples

library(graphics)
library(stats)
library(utils)
## Toy
n <- 100
## Make three fake tree-ring series to show that these funcs work on rwl objects
base.series <- 0.75 + exp(-0.2 * 1:n)
rwl <- data.frame(x1 = base.series + abs(rnorm(n, 0, 0.05)),
                  x2 = base.series + abs(rnorm(n, 0, 0.05)),
                  x3 = base.series + abs(rnorm(n, 0, 0.05)))

## The inside out method
foo <- bai.in(rwl = rwl)
## The outside in method
bar <- bai.out(rwl = rwl)

## Identical
head(bar)
head(foo)

## Use gp data
data(gp.rwl)
data(gp.d2pith)
foo <- bai.in(rwl = gp.rwl, d2pith = gp.d2pith)
foo.crn <- chron(foo)
yrs <- time(foo.crn)
plot(yrs, foo.crn[, 1], type = "n",
     xlab = "Year", ylab = expression(mm^2))
lines(yrs, foo.crn[, 1], col = "grey", lty = "dashed")
lines(yrs, caps(foo.crn[, 1], nyrs = 32), col = "red", lwd = 2)

Description

Convert multiple ring-width series to basal area increment (i.e., ring area) going from the bark to the pith.

Usage

bai.out(rwl, diam = NULL)

Arguments

Details

This converts ring-width series (mm) to ring-area series (mm squared) (aka basal area increments) based on the diameter of the tree and the width of each ring moving towards the pith of the tree. It is related to bai.in, which calculates each ring area starting from the inside of the tree and working outward. Both methods assume a circular cross section (Biondi 1999). See the references below for further details.

Value

A data.frame containing the ring areas for each series with column names, row names and dimensions of rwl.

Note

DendroLab website: https://dendrolaborg.wordpress.com/

Author(s)

Code by Andy Bunn based on work from DendroLab, University of Nevada Reno, USA. Patched and improved by Mikko Korpela.

References

Biondi, F. (1999) Comparing tree-ring chronologies and repeated timber inventories as forest monitoring tools. Ecological Applications, 9(1), 216–227.

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

See Also

bai.in

Examples

library(graphics)
library(utils)
## Not run: 
library(stats)
## Toy
n <- 100
## Make three fake tree-ring series to show that these funcs work on rwl objects
base.series <- 0.75 + exp(-0.2 * 1:n)
rwl <- data.frame(x1 = base.series + abs(rnorm(n, 0, 0.05)),
                  x2 = base.series + abs(rnorm(n, 0, 0.05)),
                  x3 = base.series + abs(rnorm(n, 0, 0.05)))

## The inside out method
foo <- bai.in(rwl = rwl)
## The outside in method
bar <- bai.out(rwl = rwl)

## Identical
head(bar)
head(foo)

## End(Not run)
## Use gp data
data(gp.rwl)
data(gp.dbh)
## dbh (minus the bark) from cm to mm 
gp.dbh2 <- gp.dbh[, 1:2]
gp.dbh2[, 2] <- (gp.dbh[, 2] - gp.dbh[, 3]) * 10
bar <- bai.out(rwl = gp.rwl, diam = gp.dbh2)
bar.crn <- chron(bar)
yrs <- time(bar.crn)
plot(yrs, bar.crn[, 1], type = "n",
     xlab = "Year", ylab = expression(mm^2))
lines(yrs, bar.crn[, 1], col = "grey", lty = "dashed")
lines(yrs, caps(bar.crn[, 1], nyrs = 32), col = "red", lwd = 2)

Description

Convert multiple ring-width series to basal area increment (i.e., ring area) following the proportional method of Bakker (2005).

Usage

bakker(rwl, ancillary)

Arguments

Details

This converts ring-width series (mm) to ring-area series (mm squared) (aka basal area increments) based on the diameter of the tree, the missing distance to the pith and the missing number of rings to the pith, following the proportional method for reconstructing historical tree diameters by Bakker (2005). It prevents bai.out transformations from producing negative increments when the sum of all ring widths in a series is larger than DBH/2. It prevents bai.in transformations from producing too small values when the sum of all ring widths in a series is smaller than DBH/2.

Value

A list containing the following objects:

Author(s)

Code by Stefan Klesse. Adapted for dplR by Andy Bunn.

References

Bakker, J.D., 2005. A new, proportional method for reconstructing historical tree diameters. Canadian Journal of Forest Research 35, 2515–2520. https://doi.org/10.1139/x05-136

Examples

data(zof.rwl)
data(zof.anc)
zof.bakker <- bakker(rwl = zof.rwl,ancillary = zof.anc)
zof.bai <- zof.bakker$baiBakker_raw

# first series bai
yrs <- time(zof.rwl)
plot(yrs,zof.bai[,1],type="l",
     xlab="Year",
     ylab=expression(BAI~(mm^2)),
     main = colnames(zof.bai)[1])

Description

This data set gives the raw ring widths for bristlecone pine Pinus longaeva at Campito Mountain in California, USA. There are 34 series. Data set was created using read.rwl and saved to an .rda file using save.

Usage

data(ca533)

Format

A data.frame containing 34 tree-ring series in columns and 1358 years in rows.

Source

International tree-ring data bank, Accessed on 20-April-2021 at https://www.ncei.noaa.gov/pub/data/paleo/treering/measurements/northamerica/usa/ca533.rwl

References

Graybill, D. A. and LaMarche, Jr., V. C. (1983) Campito Mountain Data Set. IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series 1983-CA533.RWL. NOAA/NCDC Paleoclimatology Program, Boulder, Colorado, USA.

Description

This data set gives the standard chronology for white spruce Picea glauca at Twisted Tree Heartrot Hill in Yukon, Canada. Data set was created using read.crn and saved to an .rda file using save.

Usage

data(cana157)

Format

A data.frame containing the standard chronology in column one and the sample depth in column two. There are 463 years (1530–1992) in the rows.

Source

International tree-ring data bank, Accessed on 20-April-2021 at https://www.ncei.noaa.gov/pub/data/paleo/treering/chronologies/northamerica/canada/cana157.crn

References

Jacoby, G., D’Arrigo, R. and Buckley, B. (1992) Twisted Tree Heartrot Hill Data Set. IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series 1992-CANA157.CRN. NOAA/NCDC Paleoclimatology Program, Boulder, Colorado, USA.

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)

Arguments

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

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)
# 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)

Description

Computes cross-correlations between a tree-ring series and a master chronology built from a rwl object at user-specified lags and segments.

Usage

ccf.series.rwl(rwl, series, series.yrs = as.numeric(names(series)),
               seg.length = 50, bin.floor = 100, n = NULL,
               prewhiten = TRUE, biweight = TRUE, pcrit = 0.05,
               lag.max = 5, make.plot = TRUE,
               floor.plus1 = FALSE, series.x = FALSE, ...)

Arguments

Details

This function calculates the cross-correlation function between a tree-ring series and a master chronology built from rwl looking at correlations lagged positively and negatively using ccf at overlapping segments set by seg.length. For instance, with lag.max set to 5, cross-correlations would be calculated at for each segment with the master lagged at k = -5:5 years.

The cross correlations are calculated calling ccf as
ccf(x=master, y=series, lag.max=lag.max, plot=FALSE) if series.x is FALSE and as ccf(x=series, y=master, lag.max=lag.max, plot=FALSE) if series.x is TRUE. This argument was introduced in dplR version 1.7.0. Different users have different expectations about how missing or extra rings are notated. If switch.x = FALSE the behavior will be like COFECHA where a missing ring in a series produces a negative lag in the plot rather than a positive lag.

Correlations are calculated for the first segment, then the second segment and so on. Correlations are only calculated for segments with complete overlap with the master chronology.

Each series (including those in the rwl object) is optionally detrended as the residuals from a hanning filter with weight n. The filter is not applied if n is NULL. Detrending can also be done via prewhitening where the residuals of an ar model are added to each series mean. This is the default. The master chronology is computed as the mean of the rwl object using tbrm if biweight is TRUE and rowMeans if not. Note that detrending typically changes the length of the series. E.g., a hanning filter will shorten the series on either end by floor(n/2). The prewhitening default will change the series length based on the ar model fit. The effects of detrending can be seen with series.rwl.plot.

Value

A list containing matrices ccf and bins. Matrix ccf contains the correlations between the series and the master chronology at the lags window given by lag.max. Matrix bins contains the years encapsulated by each bin.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

References

Bunn, A. G. (2010) Statistical and visual crossdating in R using the dplR library. Dendrochronologia, 28(4), 251–258.

See Also

corr.rwl.seg, corr.series.seg, skel.plot, series.rwl.plot

Examples

library(utils)
data(co021)
dat <- co021
## Create a missing ring by deleting a year of growth in a random series
flagged <- dat$"641143"
flagged <- c(NA, flagged[-325])
names(flagged) <- rownames(dat)
dat$"641143" <- NULL
ccf.100 <- ccf.series.rwl(rwl = dat, series = flagged, seg.length = 100)
## Not run: 
flagged2 <- co021$"641143"
names(flagged2) <- rownames(dat)
ccf.100.1 <- ccf.series.rwl(rwl = dat, seg.length = 100,
                            series = flagged2)
## Select series by name or column position
ccf.100.2 <- ccf.series.rwl(rwl = co021, seg.length = 100,
                            series = "641143")
ccf.100.3 <- ccf.series.rwl(rwl = co021, seg.length = 100,
                            series = which(colnames(co021) == "641143"))
identical(ccf.100.1, ccf.100.2) # TRUE
identical(ccf.100.2, ccf.100.3) # TRUE

## End(Not run)

Description

This function builds a mean value chronology, typically from a data.frame of detrended ring widths as produced by detrend.

Usage

chron(x, biweight = TRUE, prewhiten = FALSE, ...)

Arguments

Details

This either averages the rows of the data.frame using a mean or a robust mean (the so-called standard chronology) or can do so from the residuals of an AR process (the residual chronology).

Note that the residual chronology in this function will return different values than the residual chronology from chron.ars which uses a slightly different method for determining AR order.

Value

An object of of class crn and data.frame with the standard chronology, residual chronology (if prewhitening was performed), and the sample depth. The years are stored as row numbers.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

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.

Fritts, H. C. (2001) Tree Rings and Climate. Blackburn. ISBN-13: 978-1-930665-39-2.

See Also

read.rwl, detrend, ar, crn.plot

Examples

library(graphics)
library(utils)
data(ca533)
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
ca533.crn <- chron(ca533.rwi)
plot(ca533.crn,xlab="Year",ylab="RWI")
## With residual chron
ca533.crn2 <- chron(ca533.rwi, prewhiten = TRUE)
plot(ca533.crn2,xlab="Year",ylab="RWI")

Description

This function builds three varieties of the mean-value chronology, including the ARSTAN chronology, typically from a data.frame of detrended ring widths as produced by detrend.

Usage

chron.ars(x, biweight=TRUE, maxLag=10, firstAICmin=TRUE, 
  verbose=TRUE, prewhitenMethod=c("ar.yw","arima.CSS-ML"))

Arguments

Details

This produces three mean-value chronologies: standard, residual, and ARSTAN. Users unfamiliar with the concept behind the ARSTAN method should look to Cook (1985) for background and inspiration.

The standard chronology is the (biweight) mean value across rows and identical to chron.

The residual chronology is the prewhitened chronology as described by Cook (1985) and uses uses multivariate autoregressive modeling to determine the order of the AR process. It's important to note that residual chronology produced here is different than the simple residual chronology produced by chron which returns the residuals of an AR process using a naive call to ar. But in practice the results will be similar. For more on the residual chronology in this function, see pp. 153-154 in Cook's 1985 dissertation.

The ARSTAN chronology builds on the residual chronology but returns a re-whitened chronology where the pooled AR coefficients from the multivariate autoregressive modeling are reintroduced. See references for details.

The order of the AR model is selected from the pooled AR coefficients by AIC using either the first (local) AIC minimum otherwise or the overall minimum considering the maximum lag (argument maxLag).

Once the AR order is determined an AR(p) model is fit using either ar via the Yule-Walker method or by arima via conditional-sum-of-squares to find starting values, then maximum likelihood. It is possible that the model will not converge in which case a warning is produced. The AR fitting is determined via prewhitenMethod and defaults to using ar.

Value

A data.frame with the standard, residual, and ARSTAN chronologies. The sample depth is also included.

Author(s)

Andy Bunn with contributions from Kevin Achukaitis and Ed Cook. Much of the function is a port of Cook's FORTRAN code.

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. (1985). A Time Series Analysis Approach to Tree Ring Standardization. PhD thesis, The University of Arizona.

See Also

chron, crn.plot, ar, arima

Examples

library(graphics)
library(utils)
data(co021)
co021.rwi <- detrend(rwl = co021, method = "AgeDepSpline")
co021.crn <- chron.ars(co021.rwi)
plot(co021.crn,xlab="Year",ylab="RWI",add.spline=TRUE,nyrs=20)
cor(co021.crn)

Description

This function builds a mean value chronology with bootstrapped confidence intervals, typically from a data.frame of detrended ring widths as produced by detrend.

Usage

chron.ci(x, biweight=TRUE, conf=0.95, R=100)

Arguments

Details

This either averages the rows of the data.frame using a mean or a robust mean (the so-called standard chronology) and calculates boostrapped confidence intervals using the normal approximation. The function will fail if there are any rows in x that contain only one sample and in practice there should be several samples in a row. One of the guiding principles of bootstrapping is that the population is to the sample as the sample is to the bootstrap samples.

Value

An object of of class data.frame with the standard chronology, the upper and lower confidence interval, and the sample depth. The years are stored as row numbers.

Author(s)

Andy Bunn.

See Also

read.rwl, detrend, boot, boot.ci

Examples

library(graphics)
library(utils)
data(wa082)
# truncate to a sample depth of five
wa082Trunc <- wa082[rowSums(!is.na(wa082))>4,]
# detrend
wa082RWI <- detrend(wa082Trunc, method="AgeDepSpline")
# bootstrap the chronology and
wa082Crn <- chron.ci(wa082RWI, biweight = TRUE, R = 100, conf = 0.99)
head(wa082Crn)
# plot (this is so much easier in ggplot!)
wa082Crn$yrs <- time(wa082Crn)
xx <- c(wa082Crn$yrs,rev(wa082Crn$yrs))
yy <- c(wa082Crn$lowerCI,rev(wa082Crn$upperCI))
plot(wa082Crn$yrs,wa082Crn$std,type="n",ylim=range(yy),
     ylab="RWI",xlab="Year",main="Chronology with CI")
polygon(x=xx,y=yy,col = "grey",border = NA)
lines(wa082Crn$yrs,wa082Crn$std)

Description

This function builds a variance stabilized mean-value chronology, typically from a data.frame of detrended ring widths as produced by detrend.

Usage

chron.stabilized(x, winLength, biweight = TRUE, running.rbar = FALSE)

Arguments

Details

The variance of a mean chronology depends on the variance of the individual samples, the number of series averaged together, and their interseries correlation (Wigley et al. 1984). As the number of series commonly decreases towards the beginning of a chronology averaging introduces changes in variance that are a solely an effect of changes in sample depth.

Additionally, time-dependent changes in interseries correlation can cause artificial variance changes of the final mean chronology. The function chron.stabilized accounts for both temporal changes in the interseries correlation and sample depth to produce a mean value chronology with stabilized variance.

The basic correction centers around the use of the effective independent sample size, Neff, which considers sample replication and mean interseries correlation between the samples at every time. This is defined as: Neff = n(t) / 1+(n(t)-1)rbar(t)

where n(t) is the number of series at time t, and rbar is the interseries correlation (see interseries.cor). Multiplication of the mean time series with the square root of Neff at every time t theoretically results in variance that is independent of sample size. In the limiting cases, when the rbar is zero or unity, Neff obtains values of the true sample size and unity, respectively.

Value

An object of of class crn and data.frame with the variance stabilized chronology, running interseries correlation ('if running.bar=TRUE), and the sample depth.

Author(s)

Original code by David Frank and adapted for dplR by Stefan Klesse. Patched and improved by Andy Bunn.

References

Frank, D, Esper, J, Cook, E, (2006) On variance adjustments in tree-ring chronology development. Tree rings in archaeology, climatology and ecology, TRACE 4, 56–66

Frank, D, Esper, J, Cook, E, (2007) Adjustment for proxy number and coherence in a large-scale temperature reconstruction. Geophysical Research Letters 34

Wigley, T, Briffa K, Jones P (1984) On the Average Value of Correlated Time Series, with Applications in Dendroclimatology and Hydrometeorology. J. Climate Appl. Meteor., 23, 201–213

See Also

chron

Examples

library(graphics)
library(utils)
data(co021)
co021.rwi <- detrend(co021,method = "Spline")
co021.crn <- chron(co021.rwi)
co021.crn2 <- chron.stabilized(co021.rwi,
                                winLength=101,
                                biweight = TRUE,
                                running.rbar = FALSE)
yrs <- time(co021)
plot(yrs,co021.crn$std,type="l",col="grey")
lines(yrs,co021.crn2$adj.crn,col="red")

Description

Detrend multiple ring-width series simultaneously using the C-method.

Usage

cms(rwl, po, c.hat.t = FALSE, c.hat.i = FALSE)

Arguments

Details

This method detrends and standardizes tree-ring series by calculating a growth curve based on constant annual basal area increment. The method is based on the “assumption that constant growth is expressed by a constant basal area increment distributed over a growing surface” (Biondi and Qeadan 2008). The detrending is the estimation and removal of the tree’s natural biological growth trend. The standardization is done by dividing each series by the growth trend to produce units in the dimensionless ring-width index (RWI).

This attempts to remove the low frequency variability that is due to biological or stand effects.

See the reference below for further details.

Value

A data.frame containing the dimensionless and detrended ring-width indices with column names, row names and dimensions of rwl if c.hat.t is FALSE and c.hat.i is FALSE.

Otherwise a list of length 2 or 3 containing the RWI data.frame, a data.frame containing the C-curves for each tree (c.hat.t), and/or a vector containing the C-values for each tree (c.hat.i) depending on the output flags. See Eq. 12 in Biondi and Qeadan (2008) for more detail on c.hat.t, and c.hat.i.

Note

DendroLab website: https://dendrolaborg.wordpress.com/

Author(s)

Code provided by DendroLab based on programming by F. Qeadan and F. Biondi, University of Nevada Reno, USA and adapted for dplR by Andy Bunn. Patched and improved by Mikko Korpela.

References

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

See Also

detrend, chron, rcs

Examples

library(graphics)
library(utils)
data(gp.rwl)
data(gp.po)
gp.rwi <- cms(rwl = gp.rwl, po = gp.po)
gp.crn <- chron(gp.rwi)
crn.plot(gp.crn, add.spline = TRUE)
## c.hat
gp.rwi <- cms(rwl = gp.rwl, po = gp.po, c.hat.t = TRUE, c.hat.i = TRUE)
dotchart(gp.rwi$c.hat.i, ylab = "Series", xlab = expression(hat(c)[i]))
tmp <- gp.rwi$c.hat.t
plot(tmp[, 1], type = "n", ylim = range(tmp, na.rm = TRUE),
     xlab = "Cambial Age", ylab = expression(hat(c)[t]))
apply(tmp, 2, lines)

Description

This data set gives the raw ring widths for Douglas fir Pseudotsuga menziesii at Mesa Verde in Colorado, USA. There are 35 series. Data set was created using read.rwl and saved to an .rda file using save.

Usage

data(co021)

Format

A data.frame containing 35 tree-ring series in columns and 788 years in rows.

Source

International tree-ring data bank, Accessed on 20-April-2021 at https://www.ncei.noaa.gov/pub/data/paleo/treering/measurements/northamerica/usa/co021.rwl

References

Schulman, E. (1963) Schulman Old Tree No. 1 Data Set. IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series 1983-CO021.RWL. NOAA/NCDC Paleoclimatology Program, Boulder, Colorado, USA.

Description

This function combines any number of data.frames of tree-ring data into one data.frame.

Usage

combine.rwl(x, y = NULL)

Arguments

Details

The sequence of years in each data.frame must be increasing and continuous. The output produced by the function also fulfills this condition. If the input is differently formatted, the result will be wrong.

Value

An object of class c("rwl", "data.frame") with the series in columns and the years as rows. The keycodes are the column names and the years are the row names.

Author(s)

Christian Zang. Patched by Mikko Korpela.

Examples

library(utils)
data(ca533)
data(co021)
combi1 <- combine.rwl(list(ca533, co021))
## or alternatively for data.frames to combine
combi2 <- combine.rwl(ca533, co021)
identical(combi1, combi2) # TRUE

Description

This function finds the common interval on a set of tree-ring widths such as that produced by read.rwl.

Usage

common.interval(rwl, type=c("series", "years", "both"),
                make.plot=TRUE)

Arguments

Details

This trims an rwl object to a common interval that maximizes the number of series (type="series"), the number of years (type="years"), or a compromise between the two (type="both"). A modified seg.plot can be drawn as well.

Value

A data.frame with colnames(x) and rownames(x).

Author(s)

Filipe Campelo, Andy Bunn and Mikko Korpela

See Also

seg.plot

Examples

library(utils)
data(co021)
co021.s <- common.interval(co021, type="series", make.plot=TRUE)
co021.y <- common.interval(co021, type="years", make.plot=TRUE)
co021.b <- common.interval(co021, type="both", make.plot=TRUE)

dim(co021)
dim.s <- dim(co021.s)
dim.s       # the highest number of series
prod(dim.s) #   (33 series x 288 years = 9504)
dim.y <- dim(co021.y)
dim.y       # the highest number of years
prod(dim.y) #   (27 series x 458 years = 12366)
dim.b <- dim(co021.b)
dim.b       # compromise solution
prod(dim.b) #   (28 series x 435 years = 12180)

Description

Computes the correlation between each tree-ring series in a rwl object.

Usage

corr.rwl.seg(rwl, seg.length = 50, bin.floor = 100, n = NULL,
             prewhiten = TRUE, pcrit = 0.05, biweight = TRUE,
             method = c("spearman", "pearson","kendall"),
             make.plot = TRUE, label.cex = 1, floor.plus1 = FALSE,
             master = NULL,
             master.yrs = as.numeric(if (is.null(dim(master))) {
                              names(master)
                          } else {
                              rownames(master)
                          }),
             ...)

Arguments

Details

This function calculates correlation serially between each tree-ring series and a master chronology built from all the other series in the rwl object (leave-one-out principle). Optionally, the user may give a master chronology (a vector) as an argument. In the latter case, the same master chronology is used for all the series in the rwl object. The user can also choose to give a master data.frame (series as columns, years as rows), from which a single master chronology is built.

Correlations are done for each segment of the series where segments are lagged by half the segment length (e.g., 100-year segments would be overlapped by 50-years). The first segment is placed according to bin.floor. The minimum bin year is calculated as ceiling(min.yr/bin.floor)*bin.floor where min.yr is the first year in either the rwl object or the user-specified master chronology, whichever is smaller. For example if the first year is 626 and bin.floor is 100 then the first bin would start in 700. If bin.floor is 10 then the first bin would start in 630.

Correlations are calculated for the first segment, then the second segment and so on. Correlations are only calculated for segments with complete overlap with the master chronology. For now, correlations are Spearman’s rho calculated via cor.test using method = "spearman".

Each series (including those in the rwl object) is optionally detrended as the residuals from a hanning filter with weight n. The filter is not applied if n is NULL. Detrending can also be done via prewhitening where the residuals of an ar model are added to each series mean. This is the default. The master chronology is computed as the mean of the rwl object using tbrm if biweight is TRUE and rowMeans if not. Note that detrending can change the length of the series. E.g., a hanning filter will shorten the series on either end by floor(n/2). The prewhitening default will change the series length based on the ar model fit. The effects of detrending can be seen with series.rwl.plot.

The function is typically invoked to produce a plot where each segment for each series is colored by its correlation to the master chronology. Green segments are those that do not overlap completely with the width of the bin. Blue segments are those that correlate above the user-specified critical value. Red segments are those that correlate below the user-specified critical value and might indicate a dating problem.

Value

A list containing matrices spearman.rho, p.val, overall, bins, rwi, vector avg.seg.rho, numeric seg.lag, seg.length, pcrit, label.cex. An additional character flags is also returned if any segments fall below the critical value. Matrix spearman.rho contains the correlations for each series by bin. Matrix p.val contains the p-values on the correlation for each series by bin. Matrix overall contains the average correlation and p-value for each series. Matrix bins contains the years encapsulated by each bin. The vector avg.seg.rho contains the average correlation for each bin. Matrix rwi contains the detrended rwl data, the numerics seg.lag, seg.length, pcrit, label.cex are from the oroginal call and used to pass into plot.crs.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

corr.series.seg, skel.plot, series.rwl.plot, ccf.series.rwl, plot.crs

Examples

library(utils)
data(co021)
crs <- corr.rwl.seg(co021, seg.length = 100, label.cex = 1.25)
names(crs)
## Average correlation and p-value for the first few series
head(crs$overall)
## Average correlation for each bin
crs$avg.seg.rho

Description

Compute correlation between a tree-ring series and a master chronology by segment.

Usage

corr.series.seg(rwl, series, series.yrs = as.numeric(names(series)),
                seg.length = 50, bin.floor = 100, n = NULL,
                prewhiten = TRUE, biweight = TRUE, 
                method = c("spearman", "pearson","kendall"),
                pcrit = 0.05,
                make.plot = TRUE, floor.plus1 = FALSE, ...)

Arguments

Details

This function calculates the correlation between a tree-ring series and a master chronology built from a rwl object. Correlations are done by segment (see below) and with a moving correlation with length equal to the seg.length. The function is typically invoked to produce a plot.

Value

A list containing matrices bins, moving.rho, and vectors spearman.rho, p.val, and overall.

Matrix bins contains the years encapsulated by each bin (segments). Matrix moving.rho contains the moving correlation and p-value for a moving average equal to seg.length. Vector spearman.rho contains the correlations by bin and p.val contains the p-values. Vector overall contains the average correlation and p-value.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

corr.series.seg, skel.plot, series.rwl.plot, ccf.series.rwl

Examples

library(utils)
data(co021)
dat <- co021
## Create a missing ring by deleting a year of growth in a random series
flagged <- dat$"641143"
flagged <- c(NA, flagged[-325])
names(flagged) <- rownames(dat)
dat$"641143" <- NULL
seg.100 <- corr.series.seg(rwl = dat, series = flagged,
                           seg.length = 100, biweight = FALSE)
## Not run: 
flagged2 <- co021$"641143"
names(flagged2) <- rownames(dat)
seg.100.1 <- corr.series.seg(rwl=dat, seg.length=100, biweight=FALSE,
                             series = flagged2)
## Select series by name or column position
seg.100.2 <- corr.series.seg(rwl=co021, seg.length=100, biweight=FALSE,
                             series = "641143")
seg.100.3 <- corr.series.seg(rwl=co021, seg.length=100, biweight=FALSE,
                             series = which(colnames(co021) == "641143"))
identical(seg.100.1, seg.100.2) # TRUE
identical(seg.100.2, seg.100.3) # TRUE

## End(Not run)

Description

This function reads in a file of ring widths (.rwl) from a text file with comma separated values (csv).

Usage

csv2rwl(fname,...)

Arguments

Details

This is a simple wrapper to read.table that reads in a text file with ring-width data in "spreadsheet" format. I.e., with series in columns and the the years as rows. The first column should contain the years and each subsequent column should contain a tree-ring series. The series names should be in the first row of the file. The deafult for NA values are empty cells or as the character string "NA" but can also be set using the na.strings argument passed to read.table. E.g.,:

Note that this is a rudimentary convenience function that isn't doing anything sophisticated. It reads in a file, assigns the years to the row names and sets the class of the object to c("rwl","data.frame") which allows dplR to recognize it.

Although arguments can be passed to read.table, this is not designed to be a flexible function. As is the philosophy with dplR, modifying the code is easy should the user wish to read in a different style of text file (e.g., tab delimited). Typing csv2rwl at the R prompt will get the user started.

Value

Function returns an object of class c("rwl", "data.frame") with the series in columns and the years as rows. The series IDs are the column names and the years are the row names.

Author(s)

Andy Bunn

See Also

read.rwl, read.table

Examples

library(utils)
data(ca533)
# write out a rwl file in a format that csv2rwl will understand
tm <- time(ca533)
foo <- data.frame(tm,ca533)
# this is the temp file where foo will be written
tmpName <- tempfile()
write.csv(foo,file=tmpName,row.names=FALSE)
# read it back in using csv2rwl
bar <- csv2rwl(tmpName)
# check to see if identical
identical(ca533,bar)
# delete temp file
unlink(tmpName)

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", "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

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:

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 splines and compute
## residuals via subtraction
ca533.rwi <- detrend(rwl = 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)

Description

Detrend a tree-ring series by one of two methods, a smoothing spline or a 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

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 for detrending although more are certainly possible. The methods implemented 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 Hugershoff curve (method = "ModHugershoff"), a modified negative exponential curve (method = "ModNegExp"), and a smoothing spline via caps (method = "Spline").

The "AgeDepSpline" approach uses an age-dependent 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 ring-width 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 non-decreasing 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 non-decreasing 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 high-order 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.

Value

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:

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela. A bug fix related to negative output values is based on work by Alice Cecile.

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.

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

Description

These are functions no longer included in dplR

Details

Description

This function fills internal NA values (i.e., those with numeric data above and below a small data gap) in each column of a data.frame such as a data set of ring widths as produced by read.rwl.

Usage

fill.internal.NA(x, fill = c("Mean", "Spline", "Linear"))

Arguments

Details

There are occasionally data gaps within a tree-ring series. Some of the functions in dplR will fail when an internal NA is encountered (e.g. caps). This function fills internal NA values with either a given numeric value (e.g., 0) or through crude imputation. The latter can be calculated as the mean of the series (fill="Mean") or calculated by fitting a cubic spline (fill="Spline") using the spline function or calculated by linear approximation (fill="Linear") using the function approx.

Editorial: Having internal NA in a tree-ring series is often bad practice and filling those values should be done with caution. For instance, some users code missing rings as NA instead of 0. And missing values (i.e., NA) are sometimes present in maximum latewood density data when the rings are small. A common, but not recommended, practice is to leave stretches of NA values in places where it has been impossible to accurately measure rings (perhaps because of a break in the core). It is often better to treat that core as two separate series (e.g., "01A" and "01B" rather than have internal NA values. As with all processing, the analyst should make a decision based on their experience with the wood and not rely on software to make a choice for them!

Value

A data.frame with colnames(x) and rownames(x). Internal NAs filled as above.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

spline, approx

Examples

library(graphics)
library(stats)
foo <- data.frame(x1=c(rnorm(5), NA, NA, rnorm(3)),
                  x2=c(rnorm(10)),
                  x3=c(NA, NA, rnorm(3), NA, rnorm(4)),
                  x4=c(NA, NA, rnorm(3), NA, rnorm(3), NA),
                  x5=c(NA, NA, rnorm(8)),
                  x6=c(NA, rnorm(9)),
                  x7=c(NA, rnorm(5), NA, rnorm(3)),
                  x8=c(rnorm(8), NA, NA),
                  x9=c(rnorm(5), NA, rnorm(3), NA))
row.names(foo) <- 1901:1910
class(foo) <- c("rwl","data.frame")
fill.internal.NA(foo, fill=0)

bar <- fill.internal.NA(foo, fill="Spline")
baz <- fill.internal.NA(foo, fill="Linear")

## note differences in method "Spline" vs. "Linear"
yrs <- time(foo)
plot(yrs, foo$x7, type="b", lwd=3)
lines(yrs, bar$x7, col="red", lwd=2)
lines(yrs, baz$x7, col="green", lwd=1)

Description

This function calculates the Gini coefficient on raw or detrended ring-width series.

Usage

gini.coef(x)

Arguments

Details

This calculates the Gini coefficient of inequality which is used as an all-lag measure of diversity in tree-ring records – typically detrended series. Lower values indicate lower diversity. The use of the Gini coefficient in dendrochronology is described by Biondi and Qeadan (2008). See Handcock and Morris (1999) for more information.

Value

the Gini coefficient.

Author(s)

Mikko Korpela, based on original by Andy Bunn

References

Biondi, F. and Qeadan, F. (2008) Inequality in Paleorecords. Ecology, 89(4), 1056–1067.

Handcock, M. S. and Morris, M. (1999) Relative Distribution Methods in the Social Sciences. Springer. ISBN: 0-387-98778-9.

See Also

rwl.stats

Examples

library(utils)
data(ca533)
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
ca533.crn <- chron(ca533.rwi)
gini.coef(ca533.crn)

Description

This function calculates the Gleichläufigkeit and related measures for a given set of tree-ring records.

Usage

glk(x, overlap = 50, prob = TRUE)
  glk.legacy(x)

Arguments

Details

Gleichläufigkeit is a classical agreement test based on sign tests (Eckstein and Bauch, 1969). This function implements Gleichläufigkeit as the pairwise comparison of all records in data set. This vectorized implementation is faster than the previous version and follows the original definition (Huber 1942), instead of the incorrect interpretation that has been used in the past (Schweingruber 1988, see Buras/Wilmking 2015 for the correction).

The probability of exceedence (p) for the Gleichläufigkeit expresses the chance that the Gleichläufigkeit is incorrect. The observed value of the Gleichläufigkeit is converted to a z-score and based on the standard normal curve the probability of exceedence is calculated. The result is a matrix of all p-values (Jansma 1995, 60-61, see also Visser 2020).

Note that prior to dplR version 1.7.2, glk did not have the overlap or prob and returned a matrix with just the Gleichläufigkeit for all possible combinations of records. That function can still be accessed via glk.legacy.

Value

The funtions returns a named list of two or three matrices (p_mat is optional if prob = TRUE):

1. glk_mat: matrix with Gleichläufigkeit

2. overlap: matrix with number of overlapping growth changes.This is the number of overlapping years minus one.

3. p_mat: matrix of all probabilities of exceedence for all observed Gleichläufigkeit values.

The matrices can be extracted from the list by selecting the name or index number. If two curves have less than 3 years of overlap, Gleichläufigkeit cannot be computed, and NA is returned. To calculate the global glk of the dataset mean(x$glk_mat, na.rm = TRUE).

Author(s)

Christian Zang. Patched and improved by Mikko Korpela. Improved by Allan Buras. Further improved and expanded by Ronald Visser and Andy Bunn

References

Buras, A. and Wilmking, M. (2015) Correcting the calculation of Gleichläufigkeit, Dendrochronologia 34, 29-30. DOI: https://doi.org/10.1016/j.dendro.2015.03.003

Eckstein, D. and Bauch, J. (1969) Beitrag zur Rationalisierung eines dendrochronologischen Verfahrens und zur Analyse seiner Aussagesicherheit. Forstwissenschaftliches Centralblatt, 88(1), 230-250.

Huber, B. (1943) Über die Sicherheit jahrringchronologischer Datierung. Holz als Roh- und Werkstoff 6, 263-268. DOI: https://doi.org/10.1007/BF02603303

Jansma, E., 1995. RemembeRINGs; The development and application of local and regional tree-ring chronologies of oak for the purposes of archaeological and historical research in the Netherlands, Nederlandse Archeologische Rapporten 19, Rijksdienst voor het Oudheidkundig Bodemonderzoek, Amersfoort

Schweingruber, F. H. (1988) Tree rings: basics and applications of dendrochronology, Kluwer Academic Publishers, Dordrecht, Netherlands, 276 p.

Visser, R.M. (2020) On the similarity of tree-ring patterns: Assessing the influence of semi-synchronous growth changes on the Gleichläufigkeit for big tree-ring data sets,Archaeometry, 63, 204-215 DOI: https://doi.org/10.1111/arcm.12600

See Also

sgc sgc is an alternative for glk)

Examples

library(utils)
  data(ca533)
  ca533.glklist <- glk(ca533)
  ca533.glk_mat <- ca533.glklist$glk_mat
  # calculating the mean GLK including self-similarities
  mean(ca533.glk_mat, na.rm = TRUE) 
  # calculating the mean GLK excluding self-similarities
  mean(ca533.glk_mat[upper.tri(ca533.glk_mat)], na.rm = TRUE)

Ponderosa Pine Distance to Pith Corresponding to gp.rwl

Description

This data set gives the distance to pith for each series (in mm) that matches the ring widths for gp.rwl – a data set of ponderosa pine (Pinus ponderosa) from the Gus Pearson Natural Area (GPNA) in northern Arizona, USA. Data are further described by Biondi and Qeadan (2008) and references therein.

Usage

data(gp.d2pith)

Format

A data.frame containing series IDs in column 1 (series) and the distance (in mm) from the innermost ring to the pith of the tree (d2pith). This can be used together with the ring widths to calculate the area of each ring.

Source

DendroLab, University of Nevada Reno, USA. https://dendrolaborg.wordpress.com/

References

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

Ponderosa Pine Stem Diameters and Bark Thickness (gp.rwl)

Description

This data set gives the diameter at breast height for each series that matches the series in gp.rwl – a data set of ponderosa pine (Pinus ponderosa) from the Gus Pearson Natural Area (GPNA) in northern Arizona, USA. Data are further described by Biondi and Qeadan (2008) and references therein.

Usage

data(gp.dbh)

Format

A data.frame containing series IDs in column 1 (series), tree diameter (in cm) at breast height (dbh), and the bark thickness (in cm). This can be used together with the ring widths to calculate the area of each ring.

Source

DendroLab, University of Nevada Reno, USA. https://dendrolaborg.wordpress.com/

References

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

Ponderosa Pine Pith Offsets Corresponding to gp.rwl

Description

This data set gives the pith offsets that match the ring widths for gp.rwl – a data set of ponderosa pine (Pinus ponderosa) from the Gus Pearson Natural Area (GPNA) in northern Arizona, USA. Data are further described by Biondi and Qeadan (2008) and references therein.

Usage

data(gp.po)

Format

A data.frame containing series IDs in column 1 (series) and the number of years between the beginning of that series in gp.rwl and the pith of the tree (pith.offset). This can be used together with the ring widths to calculate the cambial age of each ring.

Source

DendroLab, University of Nevada Reno, USA. https://dendrolaborg.wordpress.com/

References

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

Description

This data set includes ring-width measurements for ponderosa pine (Pinus ponderosa) increment cores collected at the Gus Pearson Natural Area (GPNA) in northern Arizona, USA. There are 58 series from 29 trees (2 cores per tree). Data are further described by Biondi and Qeadan (2008) and references therein.

Usage

data(gp.rwl)

Format

A data.frame containing 58 ring-width series in columns and 421 years in rows.

Source

DendroLab, University of Nevada Reno, USA. https://dendrolaborg.wordpress.com/

References

Biondi, F. and Qeadan, F. (2008) A theory-driven approach to tree-ring standardization: Defining the biological trend from expected basal area increment. Tree-Ring Research, 64(2), 81–96.

Description

Applies a Hanning filter of length n to x.

Usage

hanning(x, n = 7)

Arguments

Details

This applies a low frequency Hanning (a.k.a. Hann) filter to x with weight set to n.

Value

A filtered vector.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

References

Oppenheim, A. V., Schafer, R. W., and Buck, J. R. (1999) Discrete-Time Signal Processing. Prentice-Hall, 2nd edition. ISBN-13: 978-0-13-754920-7.

See Also

filter

Examples

library(graphics)
library(utils)
data(ca533)
yrs <- time(ca533)
y <- ca533[, 1]
not.na <- !is.na(y)
yrs <- yrs[not.na]
y <- y[not.na]
plot(yrs, y, xlab = "Years", ylab = "Series1 (mm)",
     type = "l", col = "grey")
lines(yrs, hanning(y, n = 9), col = "red", lwd = 2)
lines(yrs, hanning(y, n = 21), col = "blue", lwd = 2)
legend("topright", c("Series", "n=9", "n=21"),
       fill=c("grey", "red", "blue"))

Description

Interactively detrend multiple tree-ring series by one of two methods, a smoothing spline or a statistical model. This is a wrapper for detrend.series.

Usage

i.detrend(rwl, y.name = names(rwl), nyrs = NULL, f = 0.5,
          pos.slope = FALSE)

Arguments

Details

This function allows a user to choose detrending curves based on plots that are produced by detrend.series for which it is essentially a wrapper. The user enters their choice of detrended method via keyboard at a prompt for each ring width series in rwl. See detrend.series for examples and details on the detrending methods.

Value

A data.frame containing each detrended series according to the method used as columns and rownames set to colnames(y). These are typically years. Plots are also produced as the user chooses the detrending methods through keyboard input.

Author(s)

Andy Bunn

See Also

detrend.series

Description

Interactively detrend a tree-ring series by one of three methods, a smoothing spline, a linear model, or the mean. This is a wrapper for detrend.series.

Usage

i.detrend.series(y, y.name = NULL, nyrs = NULL, f = 0.5,
                 pos.slope = FALSE)

Arguments

Details

This function allows a user to choose a detrending method based on a plot that is produced by detrend.series for which it is essentially a wrapper. The user enters their choice of detrended method via keyboard at a prompt. See detrend.series for examples and details on the detrending methods.

Value

A vector containing the detrended series (y) according to the method used with names set to colnames(y). These are typically years. A plot is also produced and the user chooses a method through keyboard input.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

detrend.series

Description

Insert or delete rings from a ring-width series

Usage

insert.ring(rw.vec,rw.vec.yrs=as.numeric(names(rw.vec)),
            year,ring.value=mean(rw.vec,na.rm=TRUE),
            fix.last=TRUE,fix.length=TRUE)
delete.ring(rw.vec,rw.vec.yrs=as.numeric(names(rw.vec)),
            year,fix.last=TRUE,fix.length=TRUE)

Arguments

Details

Simple editing of ring widths.

Value

A named vector.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

dplR

Examples

library(utils)
data(gp.rwl)
dat <- gp.rwl
# insert a value of zero for the year 1950 in series 50A
# fix the last year of growth and maintain the length of the series
tmp <- insert.ring(rw.vec=dat$"50A",rw.vec.yrs = time(dat),
                   year=1950,ring.value=0,fix.length = TRUE)
# with fix.length=TRUE this can be merged back into the rwl object:
data.frame(dat$"50A",tmp)
dat$"50A" <- tmp

# note that if fix.last = FALSE and fix.length = FALSE inserting a ring causes the
# ending year of the series to be pushed forward and the length of the output to
# be longer than the original series.
tmp <- insert.ring(rw.vec=dat$"50A",rw.vec.yrs = time(dat),
                   year=1950,ring.value=0, fix.last = FALSE, 
                   fix.length = FALSE)
# with fix.length=FALSE this can't be merged back into the rwl object the
# same way as above
tail(tmp)
length(tmp)
nrow(dat)

# the same logic applies to deleting rings.
dat <- gp.rwl
# delete the year 1950 in series 50A
# fix the last year of growth and maintain the length of the series
tmp <- delete.ring(rw.vec=dat$"50A",rw.vec.yrs = time(dat),
                   year=1950,fix.last = TRUE, fix.length = TRUE)
# with fix.length=TRUE this can be merged back into the rwl object:
data.frame(dat$"50A",tmp)
dat$"50A" <- tmp

# note that if fix.last = FALSE and fix.length = FALSE inserting a ring causes the
# ending year of the series to be pushed forward and the length of the output to
# be longer than the original series.
tmp <- delete.ring(rw.vec=dat$"50A", rw.vec.yrs = time(dat),
                   year=1950, fix.last = FALSE, 
                   fix.length = FALSE)
# with fix.length=FALSE this can't be merged back into the rwl object the
# same way as above
tail(tmp)
length(tmp)
nrow(dat)

Description

This function calculates the correlation between a series and a master chronology.

Usage

interseries.cor(rwl,n=NULL,prewhiten=TRUE,biweight=TRUE,
    method = c("spearman", "pearson", "kendall"))

Arguments

Details

This function calculates correlation serially between each tree-ring series and a master chronology built from all the other series in the rwl object (leave-one-out principle).

Each series in the rwl object is optionally detrended as the residuals from a hanning filter with weight n. The filter is not applied if n is NULL. Detrending can also be done via prewhitening where the residuals of an ar model are added to each series mean. This is the default. The master chronology is computed as the mean of the rwl object using tbrm if biweight is TRUE and rowMeans if not. Note that detrending can change the length of the series. E.g., a hanning filter will shorten the series on either end by floor(n/2). The prewhitening default will change the series length based on the ar model fit. The effects of detrending can be seen with series.rwl.plot.

This function produces the same output of the overall portion of corr.rwl.seg. The mean correlation value given is sometimes referred to as the “overall interseries correlation” or the “COFECHA interseries correlation”. This output differs from the rbar statistics given by rwi.stats in that rbar is the average pairwise correlation between series where this is the correlation between a series and a master chronology.

Value

a data.frame with correlation values and p-values given from cor.test

Author(s)

Andy Bunn, patched and improved by Mikko Korpela

See Also

rwl.stats, rwi.stats

Examples

library(utils)
data(gp.rwl)
foo <- interseries.cor(gp.rwl)
# compare to: 
# corr.rwl.seg(rwl=gp.rwl,make.plot=FALSE)$overall
# using pearson's r
foo <- interseries.cor(gp.rwl,method="pearson")

# two measures of interseries correlation
# compare interseries.cor to rbar from rwi.stats
gp.ids <- read.ids(gp.rwl, stc = c(0, 2, 1))
bar <- rwi.stats(gp.rwl, gp.ids, prewhiten=TRUE)
bar$rbar.eff
mean(foo[,1])

Description

This is a simple convenience function that returns a date in the format used by ‘⁠\today⁠’ in LaTeX. A possible use case is fixing the date shown in a vignette at weaving time.

Usage

latexDate(x = Sys.Date(), ...)

Arguments

Value

A character vector

Author(s)

Mikko Korpela

Examples

latexDate()                              # today
latexDate(Sys.Date() + 5)                # today + 5 days
latexDate(c("2013-12-06", "2014-09-19")) # fixed dates
## [1] "December 6, 2013"   "September 19, 2014"
latexDate(5*60*60*24, origin=Sys.Date()) # today + 5 days

Description

Some characters cannot be entered directly into a LaTeX document. This function converts the input character vector to a form suitable for inclusion in a LaTeX document in text mode. It can be used together with ‘⁠\Sexpr⁠’ in vignettes.

Usage

latexify(x, doublebackslash = TRUE, dashdash = TRUE,
         quotes = c("straight", "curved"),
         packages = c("fontenc", "textcomp"))

Arguments

Details

The function is intended for use with unformatted inline text. Newlines, tabs and other whitespace characters ("[:space:]" in regex) are converted to spaces. Control characters ("[:cntrl:]") that are not whitespace are removed. Other more or less special characters in the ASCII set are ‘{’, ‘}’, ‘\’, ‘#’, ‘$’, ‘%’, ‘^’, ‘&’, ‘_’, ‘~’, double quote, ‘/’, single quote, ‘<’, ‘>’, ‘|’, grave and ‘-’. They are converted to the corresponding LaTeX commands. Some of the conversions are affected by user options, e.g. dashdash.

Before applying the substitutions described above, input elements with Encoding set to "bytes" are printed and the output is stored using captureOutput. The result of this intermediate stage is ASCII text where some characters are shown as their byte codes using a hexadecimal pair prefixed with "\x". This set includes tabs, newlines and control characters. The substitutions are then applied to the intermediate result.

The quoting functions sQuote and dQuote may use non-ASCII quote characters, depending on the locale. Also these quotes are converted to LaTeX commands. This means that the quoting functions are safe to use with any LaTeX input encoding. Similarly, some other non-ASCII characters, e.g. letters, currency symbols, punctuation marks and diacritics, are converted to commands.

Adding "eurosym" to packages enables the use of the euro sign as provided by the "eurosym" package (‘⁠\euro⁠’).

The result is converted to UTF-8 encoding, Normalization Form C (NFC). Note that this function will not add any non-ASCII characters that were not already present in the input. On the contrary, some non-ASCII characters, e.g. all characters in the "latin1" (ISO-8859-1) Encoding (character set), are removed when converted to LaTeX commands. Any remaining non-ASCII character has a good chance of working when the document is processed with XeTeX or LuaTeX, but the Unicode support available with pdfTeX is limited.

Assuming that ‘⁠pdflatex⁠’ is used for compilation, suggested package loading commands in the document preamble are:

\usepackage[T1]{fontenc}    % no '"' in OT1 font encoding
\usepackage{textcomp}       % some symbols e.g. straight single quote
\usepackage[utf8]{inputenx} % UTF-8 input encoding
\input{ix-utf8enc.dfu}      % more supported characters

Value

A character vector

Author(s)

Mikko Korpela

References

INRIA. Tralics: a LaTeX to XML translator, HTML documentation of all TeX commands. https://www-sop.inria.fr/marelle/tralics/.

Levitt, N., Persch, C., and Unicode, Inc. (2013) GNOME Character Map, application version 3.10.1.

Mittelbach, F., Goossens, M., Braams, J., Carlisle, D., and Rowley, C. (2004) The LaTeX Companion. Addison-Wesley, second edition. ISBN-13: 978-0-201-36299-2.

Pakin, S. (2009) The Comprehensive LaTeX Symbol List. https://www.ctan.org/tex-archive/info/symbols/comprehensive.

The Unicode Consortium. The Unicode Standard. https://home.unicode.org/.

Examples

x1 <- "clich\xe9\nma\xf1ana"
Encoding(x1) <- "latin1"
x1
x2 <- x1
Encoding(x2) <- "bytes"
x2
x3 <- enc2utf8(x1)
testStrings <-
    c("different     kinds\nof\tspace",
      "control\a characters \ftoo",
      "{braces} and \\backslash",
      '#various$ %other^ &characters_ ~escaped"/coded',
      x1,
      x2,
      x3)
latexStrings <- latexify(testStrings, doublebackslash = FALSE)
## All should be "unknown"
Encoding(latexStrings)
cat(latexStrings, sep="\n")
## Input encoding does not matter
identical(latexStrings[5], latexStrings[7])

Description

This function performs a continuous wavelet transform on a time series.

Usage

morlet(y1, x1 = seq_along(y1), p2 = NULL, dj = 0.25, siglvl = 0.95)

Arguments

Details

This performs a continuous wavelet transform of a time series. This function is typically invoked with wavelet.plot.

Value

A list containing:

Note

This is a port of Torrence’s IDL code, which can be accessed through the Internet Archive Wayback Machine.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

References

Torrence, C. and Compo, G. P. (1998) A practical guide to wavelet analysis. Bulletin of the American Meteorological Society, 79(1), 61–78.

See Also

wavelet.plot

Examples

library(utils)
data(ca533)
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
ca533.crn <- chron(ca533.rwi, prewhiten = FALSE)
Years <- time(ca533.crn)
CAMstd <- ca533.crn[, 1]
out.wave <- morlet(y1 = CAMstd, x1 = Years, dj = 0.1, siglvl = 0.99)

Description

Computes the $\mathit{NET}$ parameter for a set of tree-ring records or other time-series data.

Usage

net(x, weights = c(v = 1, g = 1))

Arguments

Details

This function computes the $\mathit{NET}$ parameter (Esper et al., 2001). The overall $\mathit{NET}$ is an average of all (non-NA) yearly values $\mathit{NET_j}$, which are computed as follows:

$\mathit{NET_j}=v_j+(1-G_j)$

The yearly variation $v_j$ is the standard deviation of the measurements of a single year divided by their mean. Gegenläufigkeit $1-G_j$ is based on one definition of Gleichläufigkeit $G_j$, similar to but not the same as what glk computes. Particularly, in the formula used by this function (Esper et al., 2001), simultaneous zero differences in two series are not counted as a synchronous change.

The weights of $v_j$ and $1-G_j$ in the sum can be adjusted with the argument weights (see above). As a rather extreme example, it is possible to isolate variation or Gegenläufigkeit by setting one of the weights to zero (see ‘Examples’).

Value

A list with the following components, in the same order as described here:

Author(s)

Mikko Korpela

References

Esper, J., Neuwirth, B., and Treydte, K. (2001) A new parameter to evaluate temporal signal strength of tree-ring chronologies. Dendrochronologia, 19(1), 93–102.

Examples

library(utils)
data(ca533)
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
ca533.net <- net(ca533.rwi)
tail(ca533.net$all)
ca533.net$average
## Not run: 
## Isolate the components of NET
ca533.v <- net(ca533.rwi, weights=c(v=1,0))
ca533.g <- net(ca533.rwi, weights=c(g=1,0))

## End(Not run)

Description

This data set gives the raw ring widths for Douglas fir Pseudotsuga menziesii near Los Alamos New Mexico, USA. There are 8 series. Data set was created using read.rwl and saved to an .rda file using save.

Usage

data(nm046)

Format

A data.frame containing 8 tree-ring series in columns and 289 years in rows.

Source

International tree-ring data bank, Accessed on 20-April-2021 at https://www.ncei.noaa.gov/pub/data/paleo/treering/measurements/northamerica/usa/nm046.rwl

References

O'Brien, D (2002) Los Alamos Data Set. IGBP PAGES/World Data Center for Paleoclimatology Data Contribution Series 2002-NM046.RWL. NOAA/NCDC Paleoclimatology Program, Boulder, Colorado, USA.

Description

Applies low-pass, high-pass, band-pass, or stop-pass filtering to y with frequencies (or periods) supplied by the user.

Usage

pass.filt(y, W, type = c("low", "high", "stop", "pass"),
          method = c("Butterworth", "ChebyshevI"),
          n = 4, Rp = 1)

Arguments

Details

This function applies either a Butterworth or a Chebyshev type I filter of order n to a signal and is nothing more than a wrapper for functions in the signal package. The filters are designed via butter and cheby1. The filter is applied via filtfilt.

The input data (y) has the mean value subtracted and is then padded via reflection at the start and the end to a distance of twice the maximum period. The padded data and the filter are passed to filtfilt after which the data are unpadded and returned afer the mean is added back.

The argumement W can be given in either frequency between 0 and 0.5 or, for convenience, period (minimum value of 2). For low-pass and high-pass filters, W must have a length of one. For low-pass and high-pass filters W must be a two-element vector (c(low, high)) specifying the lower and upper boundaries of the filter.

Because this is just a wrapper for casual use with tree-ring data the frequencies and periods assume a sampling frequency of one. Users are encouraged to build their own filters using the signal package.

Value

A filtered vector.

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

hanning, detrend

Examples

data("co021")
x <- na.omit(co021[, 1])

# 20-year low-pass filter -- note freq is passed in
bSm <- pass.filt(x, W=0.05, type="low", method="Butterworth")
cSm <- pass.filt(x, W=0.05, type="low", method="ChebyshevI")
plot(x, type="l", col="grey")
lines(bSm, col="red")
lines(cSm, col="blue")

# 20-year high-pass filter -- note period is passed in
bSm <- pass.filt(x, W=20, type="high")
plot(x, type="l", col="grey")
lines(bSm, col="red")

# 20 to 100-year band-pass filter -- note freqs are passed in
bSm <- pass.filt(x, W=c(0.01, 0.05), type="pass")
cSm <- pass.filt(x, W=c(0.01, 0.05), type="pass", method="ChebyshevI")
plot(x, type="l", col="grey")
lines(bSm, col="red")
lines(cSm, col="blue")

# 20 to 100-year stop-pass filter -- note periods are passed in
cSm <- pass.filt(x, W=c(20, 100), type="stop", method="ChebyshevI")
plot(x, type="l", col="grey")
lines(cSm, col="red")

Description

This function makes a default plot of a tree-ring chronology from a data.frame of the type produced by chron, chron.ars, chron.stabilized, ssf.

Usage

## S3 method for class 'crn'
plot(x, add.spline = FALSE, nyrs = NULL, ...)

Arguments

Details

This makes a crude plot of one or more tree-ring chronologies.

Value

None. Invoked for side effect (plot).

Author(s)

Andy Bunn. Patched and improved by Mikko Korpela.

See Also

chron

Examples

library(graphics)
data(wa082)
# Truncate the RW data to a sample depth at least 5
wa082Trunc <- wa082[rowSums(!is.na(wa082))>4,]
# Detrend with age-dependent spline
wa082RWI <- detrend(wa082Trunc,method = "AgeDep")
# make several chronologies
wa082CRN1 <- chron(wa082RWI)
wa082CRN2 <- chron.stabilized(wa082RWI,
                              winLength=51,
                              biweight = TRUE,
                              running.rbar = TRUE)
wa082CRN3 <- chron.ars(wa082RWI)
wa082CRN4 <- ssf(wa082Trunc)

# and plot
plot.crn(wa082CRN1,add.spline = TRUE,nyrs=20)
plot.crn(wa082CRN2,add.spline = TRUE,nyrs=20)
plot(wa082CRN3,add.spline = TRUE,nyrs=20)
plot(wa082CRN4,add.spline = TRUE,nyrs=20)

# a custom crn
foo <- data.frame(wa082CRN1,sfc=wa082CRN4$sfc)
foo <- foo[,c(1,3,2)]
class(foo) <- c("crn","data.frame")
plot.crn(foo,add.spline = TRUE,nyrs=20)

Description

Plots objects returned from corr.rwl.seg.

Usage

## S3 method for class 'crs'
plot(x, ...)

Arguments

Value

None. A plot is produced.

Author(s)

Andy Bunn

See Also

corr.rwl.seg

Examples

library(graphics)
data(co021)
foo <- corr.rwl.seg(co021, make.plot = FALSE)
plot(foo)

Description

Plots rwl objects.

Usage

## S3 method for class 'rwl'
plot(x, plot.type=c("seg","spag"), ...)

Arguments

Value

None. A plot is produced.

Author(s)

Andy Bunn

See Also

read.rwl

Examples

library(graphics)
library(utils)
data(co021)
plot(co021, plot.type="seg")
plot(co021, plot.type="spag")
plot(co021, plot.type="spag", zfac=2)

Description

This function creates a partial wood completeness data structure based on pith offset data.

Usage

po.to.wc(po)

Arguments

Details

Uses pith.offset - 1 as the number of missing heartwood rings.

Value

A data.frame containing one variable of wood completeness data: n.missing.heartwood (integer type). This can be used as input to write.tridas.

Author(s)

Mikko Korpela

See Also

wc.to.po, rcs, write.tridas

Examples

## Not run: 
library(utils)
data(gp.po)
all(wc.to.po(po.to.wc(gp.po)) == gp.po)

## End(Not run)

Description

This function calculates pointer years on a data.frame of ring-width series using the Becker algorithm. The pointer years are computed with adjustable thresholds of relative radial growth variation and number of series displaying similar growth pattern (i.e. positive or negative variations).

Usage

pointer(rwl, rgv.thresh = 10, nseries.thresh = 75, round.decimals = 2)

Arguments

Details

This calculates pointer years from ring-width series for each year t of the time period covered by the series using the Becker algorithm. This algorithm is based on, first, the calculation of the individual relative radial growth variation by comparison of ring-width of year t to that of year t-1 for each series, and second, the inter-series comparison of both sign and magnitude of these variations.

For example, if rgv.thresh and nseries.thresh are set at 10 and 75 respectively, pointer years will be defined as those years when at least 75% of the series present an absolute relative radial growth variation higher than 10%.

Users unfamiliar with the Becker algorithm should refer to Becker et al. (1994) and Mérian and Lebourgeois (2011) for further details.

Value

A data.frame containing the following columns (each row corresponds to one position of the window):

Author(s)

Pierre Mérian. Improved by Mikko Korpela and Andy Bunn.

References

Becker, M., Nieminen, T. M., and Gérémia, F. (1994) Short-term variations and long-term changes in oak productivity in northeastern France – the role of climate and atmospheric CO2. Annals of Forest Science, 51(5), 477–492.

Mérian, P. and Lebourgeois, F. (2011) Size-mediated climate–growth relationships in temperate forests: A multi-species analysis. Forest Ecology and Management, 261(8), 1382–1391.

See Also

skel.plot

Examples

## Pointer years calculation on ring-width series. Returns a data.frame.
library(utils)
data(gp.rwl)
py <- pointer(rwl=gp.rwl, rgv.thresh=10, nseries.thresh=75,
              round.decimals=2)
tail(py)

Description

Power transformation of tree-ring width.

Usage

powt(rwl, method = "universal", rescale = FALSE,
     return.power=FALSE)

Arguments

Details

In dendrochronology, ring width series are sometimes power transformed to address heteroscedasticity.

The classic procedure used by method="cook" is a variance stabilization technique implemented after Cook & Peters (1997): for each series a linear model is fitted on the logs of level and spread, where level is defined as the local mean $M_t = \left(R_t + R_{t-1}\right)/2$ with ring widths R, and spread S is the local standard deviation defined as $S_t = \left|R_t - R_{t-1}\right|$. The regression coefficient b from a linear model $\log S = k + b \log M$ is then used for the power transform $\star{R}_t = R_t^{1-b}$.

The procedure above is modified with method="universal" where all samples are used simultaneously in a linear mixed-effects model with time (year) as a random effect: lmer(log S ~ log M + (1|year). This "universal" or "signal free" approach accounts for the common year effect across all of the series in rwl and should address that not every year has the same change in environmental conditions to the previous year.

The rescale argument will return the series with a mean and standard deviation that matches the input data. While this is a common convention, users should note that this can produce negative values which can be confusing if thought of as "ring widths."