Getting Started with dplR

Reading ring widths

Ring widths are read with read.rwl(), which handles Tucson (decadal), compact, Heidelberg, CSV-style spreadsheets and TRiDaS files. It guesses the format, but naming it is safer:

dat <- read.rwl("mysite.rwl", format = "tucson")

The result is an rwl object: a data frame with one column per series and one row per year, with the years as row names and NA where a series has no ring. Here we use co021, 35 Douglas-fir series from Mesa Verde, Colorado, which was read from the International Tree-Ring Data Bank this way.

data(co021)
class(co021)

## [1] "rwl"        "data.frame"

dim(co021)

## [1] 788  35

co021[1:5, 1:4]

##      641114 641121 641132 641143
## 1176     NA     NA     NA     NA
## 1177     NA     NA     NA     NA
## 1178     NA     NA     NA     NA
## 1179     NA     NA     NA     NA
## 1180     NA     NA     NA     NA

Describing the data

rwl.report() gives an overview: number of series, span, mean length, mean interseries correlation, and any missing rings or suspicious values.

rwl.report(co021)

## File: co021.rwl
## Site: not given; the file carries no header
## Precision: 0.01 mm
## -------------
## Number of dated series: 35 
## Number of measurements: 19772 
## Number of missing (0) rings: 716 (3.621%)
## Avg series length: 564.9143 
## Range:  788 
## Span:  1176 - 1963 
## Mean (Std dev) series intercorrelation: 0.8477981 (0.03638052)
## Mean (Std dev) AR1: 0.6038 (0.157479)
## -------------
## Years where all rings are NA
##     None 
## -------------
## Years where all rings are zero
##     None 
## -------------
## Years with missing (0) rings listed by series 
##     Series 641114 -- 1455 1480 1495 1500 1505 1506 1516 1522 1532 1536 1542 1579 1584 1585 1590 1654 1679 1685 1861 1896 1899 1902 1904 
##     Series 641121 -- 1254 1390 1400 1413 1455 1457 1480 1495 1500 1506 1532 1542 1579 1584 1585 1590 1636 1654 1729 
##     Series 641132 -- 1413 1495 1506 1584 1585 1654 1679 1729 1861 1902 
##     Series 641143 -- 1495 1500 1506 1522 1532 1542 1584 1585 1679 1685 1729 1735 1782 1847 1861 1864 1896 1899 1902 1904 
##     Series 642114 -- 1390 1413 1455 1495 1500 1505 1506 1518 1522 1532 1584 1585 1654 1679 1729 1847 1861 1896 1899 1902 1904 
##     Series 642121 -- 1413 1455 1480 1495 1500 1516 1522 1532 1542 1584 1585 1896 1899 1902 1904 
##     Series 642143 -- 1455 1464 1495 1506 1542 1584 1585 1636 1654 1679 1729 1757 1767 1773 1782 1790 1847 1861 1896 1899 1902 1904 
##     Series 642211 -- 1455 1500 1579 1584 1585 1590 1654 1666 1667 1679 1685 1708 1724 1729 1735 1757 1767 1773 1782 1790 1808 1813 1818 1819 1820 1823 1845 1847 1851 1857 1861 1864 1876 1896 1899 1900 1902 1904 1934 1951 1959 
##     Series 642222 -- 1455 1579 1584 1585 1587 1654 1679 1685 1729 1735 1767 1773 1782 1790 1805 1806 1808 1813 1818 1819 1820 1823 1845 1847 1851 1861 1864 1876 1896 1899 1902 1904 1951 
##     Series 642233 -- 1495 1579 1584 1585 1654 1679 1729 1735 1773 1782 1790 1808 1818 1819 1820 1823 1831 1845 1847 1851 1861 1864 1872 1876 1896 1899 1902 1904 1959 
##     Series 642244 -- 1542 1579 1584 1585 1654 1729 1735 1773 1780 1782 1790 1805 1806 1808 1813 1818 1819 1820 1845 1847 1851 1854 1857 1864 1870 1871 1872 1876 1878 1883 1894 1896 1899 1900 1902 1904 1934 1936 1946 1951 1959 
##     Series 643114 -- 1390 1500 1506 1522 1584 1585 1679 1896 1899 1902 1904 
##     Series 643143 -- 1495 1500 1506 1522 1584 1585 1636 1654 1679 1729 1896 1902 1904 
##     Series 643211 -- 1590 1600 1654 1679 1724 1729 1735 1773 1780 1790 1847 1861 1896 1899 1902 1904 1959 
##     Series 643222 -- 1679 1729 1735 1767 1773 1782 1790 1805 1823 1847 1861 1864 1899 1902 1904 1951 
##     Series 643233 -- 1579 1583 1584 1585 1590 1679 1685 1729 1773 1782 1790 1847 1861 1864 1896 1899 1904 1951 
##     Series 643244 -- 1495 1500 1505 1516 1532 1542 1583 1584 1585 1587 1590 1600 1679 1685 1724 1729 1735 1773 1782 1790 1861 1896 1902 1904 
##     Series 644143 -- 1500 1505 1506 1522 1584 1585 1590 1636 1648 1654 1679 1729 1773 1847 1861 1896 1899 1902 1904 
##     Series 644211 -- 1390 1455 1457 1464 1542 1584 1585 1679 1729 1773 1790 1808 1861 1896 1899 1902 1904 
##     Series 644222 -- 1455 1457 1464 1495 1506 1542 1585 1679 1729 1773 1790 1847 1861 1864 1896 1899 1902 1904 
##     Series 644233 -- 1442 1455 1457 1464 1542 1584 1585 1676 1773 1847 1861 1864 1896 1902 1904 1959 
##     Series 644244 -- 1455 1457 1464 1495 1500 1532 1542 1584 1585 1679 1729 1773 1790 1847 1861 1896 1899 1902 1904 
##     Series 645100 -- 1316 1413 1455 1464 1480 1495 1500 1505 1506 1510 1516 1522 1532 1538 1542 1561 1579 1584 1585 1590 1654 1679 1685 1729 1861 1902 1904 
##     Series 645102 -- 1457 1480 1495 1500 1506 1510 1522 1532 1584 1585 1590 1600 1636 1654 1679 1847 1861 1896 1899 1900 1902 1904 1934 
##     Series 645103 -- 1390 1413 1455 1457 1495 1500 1506 1522 1532 1542 1579 1584 1585 1587 1590 1636 1654 1685 1773 1808 1823 1861 1896 1899 1902 1904 1959 
##     Series 645214 -- 1579 1584 1585 1676 1679 1685 1729 1773 1782 1790 1808 1818 1820 1823 1845 1847 1851 1861 1864 1872 1896 1899 1902 1904 1951 1959 
##     Series 645221 -- 1585 1676 1679 1685 1729 1767 1773 1782 1790 1818 1820 1823 1845 1847 1861 1864 1896 1899 1902 1908 
##     Series 645232 -- 1585 
##     Series 645243 -- 1585 1679 1685 1729 1782 1790 1823 1847 1861 1864 1896 1899 1902 1904 1951 1959 
##     Series 646107 -- 1413 1455 1480 1495 1506 1522 1532 1538 1542 1579 1585 1590 1654 1685 1902 
##     Series 646118 -- 1390 
##     Series 646211 -- 1676 1679 1685 1696 1729 1767 1773 1782 1790 1796 1798 1800 1801 1803 1805 1806 1808 1813 1814 1818 1819 1820 1823 1845 1847 1851 1861 1864 1894 1899 1902 1904 1951 
##     Series 646222 -- 1667 1676 1679 1685 1696 1729 1757 1790 1796 1803 1805 1806 1808 1813 1818 1820 1823 1845 1851 1864 1899 1902 1904 1951 1959 
##     Series 646233 -- 1667 1679 1696 1729 1790 1805 1806 1823 1845 1851 1861 1902 1904 1934 1951 1959 
##     Series 646244 -- 1679 1729 1757 1767 1782 1788 1790 1805 1806 1808 1820 1823 1845 1851 1861 1864 1876 1896 1899 1902 1904 1934 1951 1959 
## -------------
## Years with more than one consecutive missing (0) rings listed by series 
##     Series 641114 -- 1505 1506 1584 1585 
##     Series 641121 -- 1584 1585 
##     Series 641132 -- 1584 1585 
##     Series 641143 -- 1584 1585 
##     Series 642114 -- 1505 1506 1584 1585 
##     Series 642121 -- 1584 1585 
##     Series 642143 -- 1584 1585 
##     Series 642211 -- 1584 1585 1666 1667 1818 1819 1820 1899 1900 
##     Series 642222 -- 1584 1585 1805 1806 1818 1819 1820 
##     Series 642233 -- 1584 1585 1818 1819 1820 
##     Series 642244 -- 1584 1585 1805 1806 1818 1819 1820 1870 1871 1872 1899 1900 
##     Series 643114 -- 1584 1585 
##     Series 643143 -- 1584 1585 
##     Series 643233 -- 1583 1584 1585 
##     Series 643244 -- 1583 1584 1585 
##     Series 644143 -- 1505 1506 1584 1585 
##     Series 644211 -- 1584 1585 
##     Series 644233 -- 1584 1585 
##     Series 644244 -- 1584 1585 
##     Series 645100 -- 1505 1506 1584 1585 
##     Series 645102 -- 1584 1585 1899 1900 
##     Series 645103 -- 1584 1585 
##     Series 645214 -- 1584 1585 
##     Series 646211 -- 1800 1801 1805 1806 1813 1814 1818 1819 1820 
##     Series 646222 -- 1805 1806 
##     Series 646233 -- 1805 1806 
##     Series 646244 -- 1805 1806 
## -------------
## Years with internal NA values listed by series 
##     None

summary() returns per-series statistics, and plot() shows where each series sits in time.

head(summary(co021))

##   series first last year  mean median stdev  skew kurtosis  gini   ar1
## 1 641114  1270 1963  694 0.287   0.23 0.231 2.884   13.963 0.372 0.686
## 2 641121  1250 1963  714 0.328   0.26 0.315 3.306   15.199 0.410 0.744
## 3 641132  1256 1963  708 0.357   0.29 0.337 4.741   33.324 0.373 0.686
## 4 641143  1237 1963  727 0.344   0.27 0.287 2.341    7.637 0.397 0.708
## 5 642114  1243 1963  721 0.281   0.24 0.219 2.848   12.385 0.358 0.673
## 6 642121  1260 1963  704 0.313   0.21 0.416 4.399   22.962 0.474 0.865

plot(co021, plot.type = "spag")

Detrending

Raw ring widths carry an age-related growth trend and differences in mean growth between trees. Detrending fits a curve to each series and divides the ring widths by it, giving dimensionless indices with a mean of about one. detrend() does this for every series; detrend.series() does one and plots the fit, which is a good way to choose a method.

x <- co021[, "641114"]
names(x) <- rownames(co021)
x.rwi <- detrend.series(x, method = c("Spline", "ModNegExp"),
                        make.plot = TRUE)

Here we use a cubic smoothing spline with a 50% frequency cutoff at two-thirds of each series’ length (the default for "Spline").

co021.rwi <- detrend(co021, method = "Spline")

The result is an rwi object with the same shape as the rwl, which records how it was made. summary() describes the indices as a collection. rbar.eff is the mean interseries correlation and EPS the expressed population signal; an EPS above about 0.85 is the usual rule of thumb for a chronology that represents the population. These come from rwi.stats(), and here count each core as its own tree; pass ids to group cores by tree. The summary also correlates each series with the mean of the others and lists any that do not fit.

summary(co021.rwi)

## Ring-width indices: 35 series, 1176-1963
## Made by detrend(), method "Spline", as ratios (centred on 1).
## Common interval: none (no year has every series)
## rbar.eff 0.737, EPS 0.990, SNR 97.85 (rwi.stats(), one tree per series)
## Series vs the others (interseries.cor()): mean r 0.881, range 0.803 to 0.923
## Every series correlates with the others at p < 0.05.
## More:
##   as.data.frame(summary(x))  every series: span, mean, sd, ar1, cor, p
##   summary(x, ids = )         rbar and EPS with cores grouped by tree
##   rwi.stats.running(x)       rbar and EPS through time
##   corr.rwl.seg() on widths   where in a series the fit breaks down

plot() with plot.type = "image" shows every index at once, years across and series down, brown below 1 and green above. Vertical stripes are years the trees agree on, which is the signal a chronology is built from.

plot(co021.rwi, plot.type = "image")

The same plot is a quick check on the detrending. Dividing each series by its mean leaves the age trend in, and it shows as a green run at the start of nearly every series.

plot(detrend(co021, method = "Mean"), plot.type = "image")

Building a chronology

chron() averages the indices by year, using Tukey’s biweight robust mean by default. The result is a crn object: the chronology and the number of series behind each year.

co021.crn <- chron(co021.rwi)
tail(co021.crn)

##            std samp.depth
## 1958 1.1284148         32
## 1959 0.1459389         32
## 1960 1.1804609         32
## 1961 0.7720185         32
## 1962 0.6232634         32
## 1963 0.6440584         29

plot(co021.crn, add.spline = TRUE, nyrs = 32)

The early part of this chronology rests on few series (fewer than five before 1234), so check samp.depth before trusting a given year.

Checking the crossdating

Crossdating assigns each ring its exact calendar year. dplR does not replace visual crossdating, but it can check it statistically, the way COFECHA does. To see what an error looks like, we plant one: the 1500 ring of series 641143 is deleted, so every ring before 1500 is now dated one year too late.

dat <- co021
x <- dat[, "641143"]
names(x) <- rownames(dat)
dat[, "641143"] <- delete.ring(x, year = 1500)

corr.rwl.seg() correlates overlapping segments of each series against a master built from all the other series. Segments that do not correlate significantly are flagged, and with lag.max it also finds the shift at which each segment correlates best.

crs <- corr.rwl.seg(dat, seg.length = 50, pcrit = 0.01,
                    lag.max = 10, label.cex = 0.7)

Every tested segment of 641143 that ends before 1500 correlates best at a lag of -1, and every later one at a lag of 0. In dplR, as in COFECHA, a negative lag means the series is missing a ring, so this points to a missing ring near 1500.

ok <- !is.na(crs$best.lag["641143", ])
crs$best.lag["641143", ok]

## 1275.1324 1300.1349 1325.1374 1350.1399 1375.1424 1400.1449 1425.1474 1450.1499 
##        -1        -1        -1        -1        -1        -1        -1        -1 
## 1475.1524 1500.1549 1525.1574 1550.1599 1575.1624 1600.1649 1625.1674 1650.1699 
##         0         0         0         0         0         0         0         0 
## 1675.1724 1700.1749 1725.1774 1750.1799 1775.1824 1800.1849 1825.1874 1850.1899 
##         0         0         0         0         0         0         0         0 
## 1875.1924 1900.1949 
##         0         0

ccf.series.rwl() looks at one series in more detail, plotting the full cross-correlation with the master for each segment.

ccf <- ccf.series.rwl(rwl = dat[, colnames(dat) != "641143"],
                      series = dat[, "641143"],
                      series.yrs = as.numeric(rownames(dat)),
                      seg.length = 50, bin.floor = 50)

## NB: With series.x = FALSE (default), negative lags indicate missing rings in series

xdate.report() puts all of this into a COFECHA-style report. It lists the flagged segments with their best lag and the gain in correlation, and records the settings and file checksum so the report can be reproduced. Printing it shows the report in the console.

rpt <- xdate.report(dat, title = "co021 with a planted fault")
rpt

The report opens with a summary of the collection:

Summary

The flagged segments section is where to start. All nine flags are on 641143, all are B flags at a lag of -1, and all end before 1500:

Flagged segments

The same table is in the report as a data frame, rpt$flagged, ready for further work:

rpt$flagged[, c("series", "from", "to", "flag", "best.lag", "gain")]

##   series from   to flag best.lag      gain
## 1 641143 1250 1299    B       -1 1.0043412
## 2 641143 1275 1324    B       -1 0.7509562
## 3 641143 1300 1349    B       -1 0.6912424
## 4 641143 1325 1374    B       -1 0.7945452
## 5 641143 1350 1399    B       -1 0.6579816
## 6 641143 1375 1424    B       -1 0.7378189
## 7 641143 1400 1449    B       -1 0.8823181
## 8 641143 1425 1474    B       -1 1.0267152
## 9 641143 1450 1499    B       -1 0.9913002

A B flag means the segment correlates better at another lag than at its dated position. An A flag, which does not appear here, means the dated position is the segment’s best but falls short of significance. The report also has a correlation table for every segment of every series, descriptive statistics, the output of rwl.check(), and notes on how each number was computed:

write.xdate.report() saves the report as text, Markdown or HTML:

write.xdate.report(rpt, "co021-report.html")

The statistics say where to look; the wood says what happened. Having found the likely missing ring, you would go back to the sample, and once confirmed, fix the series with insert.ring().

Where to go next

• Learning to Love dplR covers these steps and more in depth.
• vignette("math-dplR") gives the mathematics behind the smoothing splines, detrending and other functions.
• help(package = "dplR") lists every function. Good next stops are ?detrend, ?chron, ?ssf (signal-free chronologies), ?corr.rwl.seg and ?xdate.report.
• dplR is part of openDendro.