Package 'pointRes' reference manual

Title:	Analyzing Pointer Years and Components of Resilience
Description:	Functions to calculate and plot event and pointer years as well as resilience indices. Designed for dendroecological applications, but also suitable to analyze patterns in other ecological time series.
Authors:	Marieke van der Maaten-Theunissen [aut, cph, cre, trl], Ernst van der Maaten [aut, trl], Gottfried Jetsckhe [aut, trl], Mario Trouillier [aut, trl]
Maintainer:	Marieke van der Maaten-Theunissen <[email protected]>
License:	GPL (>= 2)
Version:	2.0.2
Built:	2024-12-22 06:46:53 UTC
Source:	CRAN

Plot event years for individual trees

Description

The function creates a dot plot showing positive and (or) negative event years from a list of the type as produced by pointer.norm or pointer.rgc.

Usage

event.plot(list.name, sign = c("both", "pos", "neg"),
           period = NULL, x.tick.major = 10, x.tick.minor = 5)
event.plot(list.name, sign = c("both", "pos", "neg"),
           period = NULL, x.tick.major = 10, x.tick.minor = 5)

Arguments

`list.name`	a `list` as produced by `pointer.norm` or `pointer.rgc`
`sign`	a `character` string specifying whether both positive and negative (`"both"`), or only positive (`"pos"`) or negative (`"neg"`) event years should be displayed. Defaults to `"both"`.
`period`	a `vector` specifying the start and end year to be plotted. Defaults to the full period covered by the output of the pointer year analysis.
`x.tick.major`	an `integer` controlling the major x-axis tick labels. Defaults to 10 years.
`x.tick.minor`	an `integer` controlling the minor x-axis ticks. Defaults to 5 years.

Details

The function makes a dot plot showing event years for individual trees. Positive and negative event years are indicated with different symbols and (or) colors.

Value

Dot plot.

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

Examples

## Plot event years from pointer.rgc output
data(s033)
py <- pointer.rgc(s033)
event.plot(py) 

## Plot negative event years from pointer.norm output (method "Neuwirth") for a specific period
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyn <- pointer.norm(detr_s033, method.thresh = "Neuwirth")
event.plot(pyn, sign = "neg", period = c(1950, 2007)) 
           
## Plot event years from pointer.rgc output
data(s033)
py <- pointer.rgc(s033)
event.plot(py) 

## Plot negative event years from pointer.norm output (method "Neuwirth") for a specific period
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyn <- pointer.norm(detr_s033, method.thresh = "Neuwirth")
event.plot(pyn, sign = "neg", period = c(1950, 2007))

Calculate pointer years using the interval trend method

Description

The function calculates year-to-year growth changes for individual tree-ring series and defines interval trends for (the population of) trees using the pointer interval method according to Schweingruber et al. (1990), which is also extensively described in Jetschke et al. (2019). The minimum percentual growth change and the minimum percentage of trees that should display a negative (or positive) trend for that year to be considered as negative (or positive) pointer year, can be adjusted.

Usage

interval.trend(data, period = NULL, trend.thresh = 0, 
               IT.thresh = 95, make.plot = FALSE)
interval.trend(data, period = NULL, trend.thresh = 0, 
               IT.thresh = 95, make.plot = FALSE)

Arguments

`data`	a `data.frame` with tree-ring series (raw or detrended) as columns and years as rows (e.g., output of `read.rwl` of package dplR).
`period`	a `vector` specifying the start and end year of the analysis. Defaults to the full period covered by the data.
`trend.thresh`	a `numeric` specifying the threshold for a percentual growth change to be considered a trend. Defaults to 0.
`IT.thresh`	a `numeric` specifying the minimum percentage of trees that should display a negative (or positive) trend for that year to be considered as negative (or positive) pointer year. Defaults to 95.
`make.plot`	a `logical` specifying whether a line plot, showing mean annual interval-trend values, should be created. The plot highlights positive and negative pointer years with black triangles pointing up and down, respectively. Defaults to FALSE.

Details

The function calculates year-to-year growth changes. For each tree and year, the interval trend is defined as 1 if a positive change exceeds trend.thresh, as 0 if a negative change falls below minus trend.thresh and as 0.5 if the absolute change is below trend.thresh. trend.thresh defaults to 0%. The interval trend for a population is defined as the average interval trend of the individual trees. A year is considered a negative (or positive) pointer year if the percentage of trees showing a decreasing (or increasing) trend exceeds IT.thresh (defaults to 95%). Hence, in case of a negative pointer year the mean overall interval trend falls below 1 - IT.thresh, for a positive pointer year the mean overall interval trend exceeds IT.thresh.

Value

The function returns a list containing the following components:

`perc.diff`	a `matrix` with percentual growth changes for individual tree-ring series
`ITvalues`	a `matrix` indicating positive (1), negative (0) and no interval trends (0.5) for individual tree-ring series
`out`	a `data.frame` containing the following columns: `year` - time stamp, `nb.series` - number of series considered, `nature` - number indicating whether the year is a positive (1), negative (-1) or no pointer year (0), and `IT` - mean overall interval trend
`spec.param`	a `data.frame` specifying the arguments used in the calculation

Author(s)

Marieke van der Maaten-Theunissen, Ernst van der Maaten and Gottfried Jetschke.

References

Jetschke, G., van der Maaten, E. and van der Maaten-Theunissen, M. (2019) Towards the extremes: a critical analysis of pointer year detection methods. Dendrochronologia 53: 55-62.

Schweingruber, F.H., Eckstein, D., Serre-Bachet, F. and Bräker, O.U. (1990) Identification, presentation and interpretation of event years and pointer years in dendrochronology. Dendrochronologia 8: 9-38.

Examples

## Calculate pointer years using interval.trend
## for a specified period and create a plot
data(s033)
IT <- interval.trend(s033, period = c(1950,2010), make.plot = TRUE)

## Calculate pointer years as years with at least 90% of the trees
## showing a positive/negative interval trend
data(s033)
IT <- interval.trend(s033, IT.thresh = 90)
IT$out[which(IT$out$nature == 1),"year"]
IT$out[which(IT$out$nature == -1),"year"]

## Calculate pointer years using interval.trend
## for a specified period and create a plot
data(s033)
IT <- interval.trend(s033, period = c(1950,2010), make.plot = TRUE)

## Calculate pointer years as years with at least 90% of the trees
## showing a positive/negative interval trend
data(s033)
IT <- interval.trend(s033, IT.thresh = 90)
IT$out[which(IT$out$nature == 1),"year"]
IT$out[which(IT$out$nature == -1),"year"]

Apply 13-year low-pass filter

Description

The function applies a 13-year weighted low-pass filter, as described by Fritts (1976), on a data.frame with tree-ring series.

Usage

lowpass13(data)
lowpass13(data)

Arguments

data

a data.frame with raw tree-ring series as columns and years as rows (e.g., output of read.rwl of package dplR).

Details

A 13-year weighted low-pass filter, as described by Fritts (1976, p. 270), can be applied to tree-ring series prior to the calculation of event and pointer years using pointer.norm. According to Cropper (1979), such a filter improves the detection of event and pointer years for complacent series, whereas for sensitive series filtering has little effect.

Note that the resulting time series are truncated by 6 years at both ends inherent to the calculation method.

Value

The function returns a data.frame with 13-year low-pass filtered index series.

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

References

Cropper, J.P. (1979) Tree-ring skeleton plotting by computer. Tree-Ring Bulletin 39: 47-59.

Fritts, H.C. (1976) Tree rings and climate. Academic Press Inc. (London) Ltd.

Examples

data(s033)
lp13_s033 <- lowpass13(s033)

data(s033)
lp13_s033 <- lowpass13(s033)

Calculate pointer years using the normalization in a moving window method

Description

The function calculates event and pointer years on a data.frame with tree-ring series using the normalization in a moving window method introduced by Cropper (1979; cf. Schweingruber et al. 1990, Jetschke et al. 2019). This method locally z-transforms tree growth in year i within a symmetric moving window of n years, thereby providing the number of standard deviations that tree growth deviates in individual years (Cropper values, Ct) from the window average. To identify event years, one absolute threshold on the number of standard deviations can be set (Cropper 1979), or, alternatively, three intensity classes (Neuwirth et al. 2007). Threshold values for defining event and pointer years can be adjusted.

Prior to the calculation of event and pointer years with pointer.norm, a 13-year weighted low-pass filter, as described by Fritts (1976), may be applied on the tree-ring series using lowpass13. According to Cropper (1979), such a filter improves the detection of event and pointer years for complacent series, whereas for sensitive series filtering has little effect. Alternatively, a flexible detrending (e.g., using a cubic-smoothing spline with a 50% frequency cut-off at 15 years) may be applied prior to pointer.norm.

Usage

pointer.norm(data, period = NULL, window = 13, method.thresh = c("Cropper", "Neuwirth"),
             C.thresh = 0.75, N.thresh = c(1, 1.28, 1.645), series.thresh = 75, 
             make.plot = FALSE)
pointer.norm(data, period = NULL, window = 13, method.thresh = c("Cropper", "Neuwirth"),
             C.thresh = 0.75, N.thresh = c(1, 1.28, 1.645), series.thresh = 75, 
             make.plot = FALSE)

Arguments

`data`	a `data.frame` with detrended tree-ring series as columns and years as rows (e.g., output of `detrend` of package dplR), or a `data.frame` with filtered series (output of `lowpass13`).
`period`	a `vector` specifying the start and end year of the analysis. Defaults to the full period covered by the data.
`window`	an `integer` specifying the window size (i.e. number of years) to be used to calculate normalized growth deviations. Must be an odd number (>=3). Defaults to 13.
`method.thresh`	a `character` string of `"Cropper"` or `"Neuwirth"`, specifying whether one absolute threshold or three intensity classes should be used for defining event years. Argument matching is performed.
`C.thresh`	a (positive) `numeric` specifying the threshold for identification of event years using method `"Cropper"`. Defaults to 0.75.
`N.thresh`	a `vector` specifying the (positive) thresholds for identification of weak, strong and extreme event years using method `"Neuwirth"`. Defaults to 1, 1.28 and 1.645, respectively.
`series.thresh`	a `numeric` specifying the minimum percentage of trees that should display a positive (or negative) event year for that year to be considered as positive (or negative) pointer year. Defaults to 75.
`make.plot`	a `logical` specifying whether a bar plot, showing mean Cropper values, should be created. Pointer years are indicated with dark-gray bars. If event years were defined using `method.thresh "Neuwirth"` (`pointer.norm`), different tones of gray indicate weak, strong and extreme pointer years, based on the most common event year class. Defaults to FALSE.

Details

The function locally z-transforms tree growth in year i within a symmetric moving window of n years. For method.thresh "Cropper", event years are defined as those years having absolute Cropper values (Ct) above a specified threshold (defaults to |Ct| > 0.75). For method.thresh "Neuwirth", three classes of distinct growth deviations can be defined, being 'weak', 'strong' and 'extreme' (defaults to |Ct| > 1, |Ct| > 1.28, and |Ct| > 1.645). The window size can be adjusted (defaults to 13 years), as well as the minimum percentage of trees that should display a positive (or negative) event year for that year to be considered as positive (or negative) pointer year (defaults to 75%).

Note that the resulting time series are truncated by (window-1)/2 at both ends inherent to the calculation method.

Value

The function returns a list containing the following components:

for method.thresh "Cropper":

`Cvalues`	a `matrix` with Cropper values for individual tree-ring series
`EYvalues`	a `matrix` indicating positive (1), negative (-1) and non-event years (0) for individual tree-ring series
`out`	a `data.frame` containing the following columns: `year` - time stamp, `nb.series` - number of series considered, `perc.pos` - percentage of trees showing a positive event year, `perc.neg` - percentage of trees showing a negative event year, `nature` - number indicating whether the year is a positive (1), negative (-1) or no pointer year (0), `Cvalues_mean` - mean Cropper value over the available series, and `Cvalues_sd` - standard deviation of Cropper values
`spec.param`	a `data.frame` specifying the arguments used in the calculation

for method.thresh "Neuwirth":

`Cvalues`	a `matrix` with Cropper values for individual tree-ring series
`EYvalues`	a `matrix` indicating weak (1/-1), strong (2/-2) and extreme (3/-3) positive/negative event years, as well as non-event years (0) for individual tree-ring series
`out`	a `data.frame` containing the following columns: `year` - time stamp, `nb.series` - number of series considered, `perc.pos.extreme` - percentage of trees showing a positive extreme event year, `perc.pos.strong` - percentage of trees showing a positive strong event year, `perc.pos.weak` - percentage of trees showing a positive weak event year, `perc.neg.weak` - percentage of trees showing a negative weak event year, `perc.neg.strong` - percentage of trees showing a negative strong event year, `perc.neg.extreme` - percentage of trees showing a negative extreme event year, `nature` - number indicating whether the year is a positive (1), negative (-1) or no pointer year (0), `Cvalues_mean` - mean Cropper value over the available series, `Cvalues_sd` - standard deviation of Cropper values
`spec.param`	a `data.frame` specifying the arguments used in the calculation

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

References

Cropper, J.P. (1979) Tree-ring skeleton plotting by computer. Tree-Ring Bulletin 39: 47-59.

Jetschke, G., van der Maaten, E. and van der Maaten-Theunissen, M. (2019) Towards the extremes: A critical analysis of pointer year detection methods. Dendrochronologia 53: 55-62.

Fritts, H.C. (1976) Tree rings and climate. Academic Press Inc. (London) Ltd.

Neuwirth, B., Schweingruber, F.H. and Winiger, M. (2007) Spatial patterns of central European pointer years from 1901 to 1971. Dendrochronologia 24: 79-89.

Examples

## Calculate pointer years on detrended tree-ring series using method.thresh "Cropper"
## and a user-defined threshold for event-year definition of 1
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyc <- pointer.norm(detr_s033, method.thresh = "Cropper", C.thresh = 1)
head(pyc$out)

## Calculate pointer years on detrended tree-ring series using method.thresh "Neuwirth"
## and a user-defined window of 11 years
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyn <- pointer.norm(detr_s033, window = 11, method.thresh = "Neuwirth", make.plot = TRUE)
head(pyn$out)

## Calculate pointer years on detrended tree-ring series using method.thresh "Cropper"
## and a user-defined threshold for event-year definition of 1
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyc <- pointer.norm(detr_s033, method.thresh = "Cropper", C.thresh = 1)
head(pyc$out)

## Calculate pointer years on detrended tree-ring series using method.thresh "Neuwirth"
## and a user-defined window of 11 years
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
pyn <- pointer.norm(detr_s033, window = 11, method.thresh = "Neuwirth", make.plot = TRUE)
head(pyn$out)

Plot pointer years for multiple sites

Description

The function creates a dot plot showing positive and (or) negative pointer years from lists of the type as produced by pointer.norm, pointer.rgc, pointer.zchron and (or) interval.trend.

Usage

pointer.plot(list.sites, sign = c("both", "pos", "neg"),
             period = NULL, labels = NULL,
             x.tick.major = 10, x.tick.minor = 5)
pointer.plot(list.sites, sign = c("both", "pos", "neg"),
             period = NULL, labels = NULL,
             x.tick.major = 10, x.tick.minor = 5)

Arguments

`list.sites`	a `list` with `lists` as produced by `pointer.norm`, `pointer.rgc`, `pointer.zchron` or `interval.trend` for individual sites (created using list(site1, site2,..)).
`sign`	a `character` string specifying whether both positive and negative (`"both"`), or only positive (`"pos"`) or negative (`"neg"`) pointer years should be displayed. Defaults to `"both"`.
`period`	a `vector` specifying the start and end year to be plotted. Defaults to the full period covered by the output of the pointer year analyses.
`labels`	a `character` vector with labels for the sites. Defaults to 'site 1, 2, .., `i`'.
`x.tick.major`	an `integer` controlling the major x-axis tick labels. Defaults to 10 years.
`x.tick.minor`	an `integer` controlling the minor x-axis ticks. Defaults to 5 years.

Details

The function makes a dot plot showing pointer years for multiple sites. Positive and negative pointer years are indicated with different symbols an (or) colors.

Value

Dot plot.

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

Examples

## Plot negative pointer years for multiple sites (or different methods)
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
py <- pointer.rgc(s033)
pyn <- pointer.norm(detr_s033, method = "Neuwirth")
it <- interval.trend(s033)
zchron <- pointer.zchron(detr_s033)
comparison <- list(py, pyn, it, zchron)
pointer.plot(comparison, sign = "neg", period = c(1950, 2013),
             labels = c("py", "pyn", "it", "zchron")) 

## Plot pointer years for different specifications of pointer.norm (method "Neuwirth")
data(s033)
w09 <- pointer.norm(detr_s033, window = 9, method.thresh = "Neuwirth")
w11 <- pointer.norm(detr_s033, window = 11, method.thresh = "Neuwirth")
w13 <- pointer.norm(detr_s033, method.thresh = "Neuwirth")
comparison <- list(w09, w11, w13)
pointer.plot(comparison, period = c(1950, 2007)) 
           
## Plot negative pointer years for multiple sites (or different methods)
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 30)
py <- pointer.rgc(s033)
pyn <- pointer.norm(detr_s033, method = "Neuwirth")
it <- interval.trend(s033)
zchron <- pointer.zchron(detr_s033)
comparison <- list(py, pyn, it, zchron)
pointer.plot(comparison, sign = "neg", period = c(1950, 2013),
             labels = c("py", "pyn", "it", "zchron")) 

## Plot pointer years for different specifications of pointer.norm (method "Neuwirth")
data(s033)
w09 <- pointer.norm(detr_s033, window = 9, method.thresh = "Neuwirth")
w11 <- pointer.norm(detr_s033, window = 11, method.thresh = "Neuwirth")
w13 <- pointer.norm(detr_s033, method.thresh = "Neuwirth")
comparison <- list(w09, w11, w13)
pointer.plot(comparison, period = c(1950, 2007))

Calculate pointer years using the relative growth change method

Description

The function calculates event and pointer years on a data.frame with tree-ring series using the relative growth change method, described as abrupt growth change method in Schweingruber et al. (1990). This method relates tree growth in year i to the average growth of n preceding years. Thresholds for event- and pointer-year calculations can be adjusted.

Usage

pointer.rgc(data, period = NULL, nb.yrs = 4, rgc.thresh.pos = 60, rgc.thresh.neg = 40, 
            series.thresh = 75, make.plot = FALSE)
pointer.rgc(data, period = NULL, nb.yrs = 4, rgc.thresh.pos = 60, rgc.thresh.neg = 40, 
            series.thresh = 75, make.plot = FALSE)

Arguments

`data`	a `data.frame` with tree-ring series (raw or detrended) as columns and years as rows (e.g., output of `read.rwl` or `detrend` of package dplR).
`period`	a `vector` specifying the start and end year of the analysis. Defaults to the full period covered by the data.
`nb.yrs`	an `integer` specifying the number of preceding years to be used in calculating relative growth changes. Defaults to 4.
`rgc.thresh.pos`	a `numeric` specifying the threshold above which a relative growth change (in percentage) for a specific tree and year is considered a positive event year. Defaults to 60.
`rgc.thresh.neg`	a `numeric` specifying the threshold below which a relative growth change (in percentage) for a specific tree and year is considered a negative event year. Defaults to 40.
`series.thresh`	a `numeric` specifying the minimum percentage of trees that should display a positive (or negative) event year for that year to be considered as positive (or negative) pointer year. Defaults to 75.
`make.plot`	a `logical` specifying whether a bar plot, showing mean relative growth changes, should be created. Pointer years are indicated with dark-gray bars. Defaults to FALSE.

Details

The function calculates the ratio of tree growth in year t and the average growth of n preceding years for individual trees. Resulting relative growth changes are used to identify event years for trees, and these event years to define pointer years for the site.

Following Schweingruber et al. (1990), nb.yrs, rgc.thresh.pos, rgc.thresh.neg and series.thresh are set to 4, 60, 40 and 75 respectively, meaning that a positive or negative pointer year will be defined when at least 75% of the tree-ring series display an event year with a growth increase or decrease of at least 60% or 40%, respectively, relative to the average growth in the four preceding years. Depending on the sensitivity of the tree-ring series, the thresholds rgc.thresh.pos and rgc.thresh.neg may be adjusted (e.g., lowered for more complacent series; Jetschke et al. 2019).

Note that the resulting time series are truncated by nb.yrs at the beginning inherent to the calculation method.

Value

The function returns a list containing the following components:

`rgc`	a `matrix` with relative growth changes for individual tree-ring series
`EYvalues`	a `matrix` indicating positive (1), negative (-1) and non-event years (0) for individual tree-ring series
`out`	a `data.frame` containing the following columns: `year` - time stamp, `nb.series` - number of series considered, `perc.pos` - percentage of trees showing a positive event year, `perc.neg` - percentage of trees showing a negative event year, `nature` - number indicating whether the year is a positive (1), negative (-1) or no pointer year (0), `dev_mean` - mean growth deviation in percentage over the available series for each year, and `dev_sd` - standard deviation of the growth deviation for each year
`spec.param`	a `data.frame` specifying the arguments used in the calculation

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

References

Jetschke, G., van der Maaten, E. and van der Maaten-Theunissen, M. (2019) Towards the extremes: A critical analysis of pointer year detection methods. Dendrochronologia 53: 55-62.

In writing the function, the code of the dplR function pointer (Pierre Mérian) was used as a reference.

Examples

## Calculate pointer years on tree-ring series
data(s033)
py1 <- pointer.rgc(s033)
head(py1$out)

## Calculate pointer years with user-defined arguments
data(s033)
py2 <- pointer.rgc(s033, period = c(1950,2010), nb.yrs = 5, rgc.thresh.pos = 50,
                   rgc.thresh.neg = 50, series.thresh = 50, make.plot = TRUE)
head(py2$out)

## Calculate pointer years on tree-ring series
data(s033)
py1 <- pointer.rgc(s033)
head(py1$out)

## Calculate pointer years with user-defined arguments
data(s033)
py2 <- pointer.rgc(s033, period = c(1950,2010), nb.yrs = 5, rgc.thresh.pos = 50,
                   rgc.thresh.neg = 50, series.thresh = 50, make.plot = TRUE)
head(py2$out)

Calculate pointer years using z-transformation of a site chronology

Description

The function calculates pointer years on a data.frame of tree-ring series using a z-transformation of the site chronology (by default based on a biweight robust mean). The method provides the number of standard deviations that the chronology deviates in individual years. To identify pointer years, one absolute threshold on the number of standard deviations can be set. Optionally, a t-test can be applied to test whether the z-transformed chronology significantly exceeds the selected threshold. The function is intended to use on flexibly detrended data, e.g., with a cubic-smoothing spline with a 50% frequency cut-off at 15 years (cf. Jetschke et al. 2019).

Usage

pointer.zchron(data, period = NULL, bi.weight = TRUE,
               z.thresh = 1, t.Test = FALSE, make.plot = FALSE)
pointer.zchron(data, period = NULL, bi.weight = TRUE,
               z.thresh = 1, t.Test = FALSE, make.plot = FALSE)

Arguments

`data`	a `data.frame` with detrended tree-ring series as columns and years as rows (e.g., output of `detrend` of package dplR).
`period`	a `vector` specifying the start and end year of the analysis. Defaults to the full period covered by the data.
`bi.weight`	a `logical` flag specifying whether a Tukey's biweight robust mean site chronology should be calculated. Defaults to TRUE.
`z.thresh`	a `numeric` specifying the threshold for identification of pointer years. Defaults to 1.
`t.Test`	a `logical` flag specifying whether a t-test should be performed. Defaults to FALSE.
`make.plot`	a `logical` specifying whether a bar plot indicating pointer years should be created. Defaults to FALSE.

Details

The function develops a site chronology, which is z-transformed over its entire length, thereby providing the number of standard deviations that the chronology deviates in individual years. In developing the site chronology, a normal or biweight robust mean can be used. A threshold z.thresh on the minimum number of standard deviations can be set (cf. Cropper 1979) to define the years to be considered as pointer years. Optionally, a t-test may be performed to test whether the z-transformed chronology significantly differs from the selected threshold value in a particular year. Therefore, individual tree-ring series are z-transformed as well and compared to the threshold value z.thresh. In case a biweight robust mean is used in building the site chronology, the t-test is based on the biweight robust estimate of the standard deviation. In all t-tests a significance level of 0.05 is used.

Value

The function returns a list containing the following components:

`TRIsite`	a `data.frame` with the calculated site chronology and corresponding sample depth (output of `chron` of package dplR)
`out`	a `data.frame` containing the following columns: `year` - time stamp, `nb.series` - number of series considered, `nature` - number indicating whether the year is a positive (1), negative (-1) or no pointer year (0), and `AVGztrans` - z-transformed site chronology
`spec.param`	a `data.frame` specifying the arguments used in the calculation

Author(s)

Marieke van der Maaten-Theunissen, Ernst van der Maaten and Gottfried Jetschke.

References

Cropper, J.P. (1979) Tree-ring skeleton plotting by computer. Tree-Ring Bulletin 39: 47-59.

Jetschke, G., van der Maaten, E. and van der Maaten-Theunissen, M. (2019) Towards the extremes: A critical analysis of pointer year detection methods. Dendrochronologia 53: 55-62.

Examples

## Calculate pointer years on detrended tree-ring series
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 15)
pz1 <- pointer.zchron(detr_s033)
head(pz1$out)

## Calculate pointer years with user-defined arguments
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 15)
pz2 <- pointer.zchron(detr_s033, period = c(1950,2010), z.thresh = 1.28,
                      make.plot = TRUE)
head(pz2$out)

## Calculate pointer years on detrended tree-ring series
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 15)
pz1 <- pointer.zchron(detr_s033)
head(pz1$out)

## Calculate pointer years with user-defined arguments
data(s033)
detr_s033 <- detrend(s033, method = "Spline", nyrs = 15)
pz2 <- pointer.zchron(detr_s033, period = c(1950,2010), z.thresh = 1.28,
                      make.plot = TRUE)
head(pz2$out)

Calculate resilience indices

Description

The function calculates resilience indices on a data.frame, e.g., of tree-ring series, after Lloret et al. (2011; i.e. resistance, recovery, (relative) resilience), Thurm et al. (2016; recovery period, total growth reduction) and Schwarz et al. (2020; average growth reduction, average recovery rate), useful to analyze growth responses of individual trees prior, during and after extreme events / disturbances. The component 'resistance' is conceptually identical to 'abrupt growth changes' as described in Schweingruber et al. (1990; cf. pointer.rgc). 'Recovery' is the ability of tree growth to recover after disturbance, whereas 'resilience' reflects the ability of trees to reach pre-disturbance growth levels. Weighting of the resilience by the experienced growth reduction results in 'relative resilience'. 'Recovery period' (or: 'growth recovery time') is the time needed to reach pre-disturbance growth levels again. 'Total growth reduction' reflects the cumulative growth reduction in the year of disturbance as well as the associated years in the recovery period. 'Average growth reduction' is the total growth reduction divided by the length of the recovery period. 'Average recovery rate' is the mean percentual recovery over the recovery period.

Usage

res.comp(data, nb.yrs = c(4,4), max.yrs.rec = 10)
res.comp(data, nb.yrs = c(4,4), max.yrs.rec = 10)

Arguments

`data`	a `data.frame` with tree-ring series (raw or detrended) as columns and years as rows (e.g., output of `read.rwl`, `bai.in` or `bai.out` of package dplR)
`nb.yrs`	a `vector` specifying the number of years for pre- and post-disturbance periods to be considered in calculating resilience components after Lloret et al. (2011). Defaults to 4 for both periods.
`max.yrs.rec`	a `numeric` specifying the maximum length of the recovery period to be considered. Defaults to 10.

Details

The function calculates various resilience indices after Lloret et al. (2011), Thurm et al. (2016) and Schwarz et al. (2020). The output provides different matrices with resilience indices for individual tree-ring series and years.

In calculating resilience indices the number of pre- and post disturbance years (nb.yrs), as well as the maximum number of years to be considered in defining the recovery period (max.yrs.rec) can be specified.

Value

The function returns a list containing the following components:

`resist`	a `matrix` with resistance values (i.e. relative growth changes) for individual tree-ring series
`recov`	a `matrix` with recovery values for individual tree-ring series
`resil`	a `matrix` with resilience values for individual tree-ring series
`rel.resil`	a `matrix` with relative resilience values for individual tree-ring series
`rec.period`	a `matrix` with recovery periods for individual tree-ring series in years with decimal places (cf. Fig. 2 in Thurm et al. 2016). In case of no growth reduction (and thus no recovery), 0 is given as output. Inf indicates that no recovery occurred within the period as specified by `max.yrs.rec`
`avg.rec.rate`	a `matrix` with average recovery rates for individual tree-ring series as percentage, calculated as 1 / `rec.period` * 100. In case of no growth reduction (and thus no recovery), NA is given as output. Inf indicates that no recovery occurred within the period as specified by `max.yrs.rec`
`tot.abs.grow.red`	a `matrix` with total absolute growth reduction values for individual tree-ring series. 0 and Inf are given as output as for `rec.period`
`tot.rel.grow.red`	a `matrix` with total growth reduction for individual tree-ring series expressed as percentage. 0 and Inf are given as output as for `rec.period`
`avg.abs.grow.red`	a `matrix` with average absolute growth reduction, i.e. total absolute growth reduction divided by the number of full years needed for recovery. 0 and Inf are given as output as for `rec.period`
`avg.rel.grow.red`	a `matrix` with average growth reduction expressed as percentage. 0 and Inf are given as output as for `rec.period`
`nb.series`	a `data.frame` with the number of series for which the diverse indices could be calculated, with years in rows and indices in columns
`spec.param`	a `data.frame` specifying the arguments used in the calculation

Author(s)

Marieke van der Maaten-Theunissen, Ernst van der Maaten and Mario Trouillier.

References

Lloret, F., Keeling, E.G. and Sala, A. (2011) Components of tree resilience: effects of successive low-growth episodes in old ponderosa pine forests. Oikos 120: 1909-1920.

Schwarz, J., Skiadaresis, G., Kohler, M., Kunz, J., Schnabel, F., Vitali, V. and Bauhus, J. (2020) Quantifying growth responses of trees to drought — a critique of commonly used resilience indices and recommendations for future studies. Current Forestry Reports 6: 185-200.

Thurm, E.A., Uhl, E. and Pretzsch, H. (2016) Mixture reduces climate sensitivity of Douglas-fir stem growth. Forest Ecology and Management 376: 205-220.

Examples

## Calculate resilience indices on tree-ring series
data(s033)
res <- res.comp(s033)

## Calculate resilience indices on tree-ring series
data(s033)
res <- res.comp(s033)

Plot resilience indices

Description

The function creates box plots for selected years of the resilience indices as calculated by res.comp, and is intended for quick visualization.

Usage

res.plot(list.name, select.yr = NULL,
         param = c("resist", "recov", "resil", "rel.resil",
                   "rec.period", "avg.rec.rate",
                   "tot.abs.grow.red", "tot.rel.grow.red",
                   "avg.abs.grow.red", "avg.rel.grow.red"))
res.plot(list.name, select.yr = NULL,
         param = c("resist", "recov", "resil", "rel.resil",
                   "rec.period", "avg.rec.rate",
                   "tot.abs.grow.red", "tot.rel.grow.red",
                   "avg.abs.grow.red", "avg.rel.grow.red"))

Arguments

`list.name`	a `list` as produced by `res.comp`.
`select.yr`	an `integer` or `vector` specifying the year(s) to be plotted (e.g., c(1948, 1992)).
`param`	a `character` string specifying the resilience index to be plotted. Argument matching is performed.

Details

The function creates a box plot for a selected resilience index showing the full range of variation for individual trees in specific years. Box plots are only created for years for which indices are available for >= 5 series, as this value represents the number of statistics that a box plot represents in its' simplest form.

Value

Box plot.

Author(s)

Marieke van der Maaten-Theunissen and Ernst van der Maaten.

Examples

## Plot the recovery period for three selected years
data(s033)
res <- res.comp(s033)
res.plot(res, select.yr = c(1976, 1992, 2003), param = "resist")

## Plot the recovery period for three selected years
data(s033)
res <- res.comp(s033)
res.plot(res, select.yr = c(1976, 1992, 2003), param = "resist")

Tree-ring series Schneetal

Description

This dataset presents tree-ring series for 20 European beech (Fagus sylvatica L.) trees from the forest reserve Schneetal, Bavaria, Germany. Series are averages of two cores.

Usage

data(s033)
data(s033)

Format

A data.frame containing 20 tree-ring series in columns and 136 years in rows.

References

Principe, A.S., van der Maaten, E., van der Maaten-Theunissen, M., Struwe, T., Wilmking, M. & Kreyling, J. (2017) Low resistance but high resilience in growth of a major deciduous forest tree (Fagus sylvatica L.) in response to late spring frost in southern Germany. Trees 31: 743-751. doi: 10.1007/s00468-016-1505-3.

Package 'pointRes'

Help Index

Plot event years for individual trees

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Calculate pointer years using the interval trend method

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Apply 13-year low-pass filter

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Calculate pointer years using the normalization in a moving window method

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Plot pointer years for multiple sites

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Calculate pointer years using the relative growth change method

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Calculate pointer years using z-transformation of a site chronology

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Calculate resilience indices

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Plot resilience indices

Description

Usage

Arguments

Details

Value

Author(s)

Examples