chguiterman/dfoliatr

Detection and analysis of insect defoliators in tree rings

dfoliatR

The goal of dfoliatR is to provide dendrochronologists with tools for identifying and analyzing the signatures of insect defoliators preserved in tree rings. The methods it employs closely follow (or in some cases exactly replicate) OUTBREAK, a FORTRAN program available from the Dendrochronological Program Library.

When using dfoliatR in a publication, please cite the paper:

Guiterman, CH, AM Lynch, and JN Axelson (2020) dfoliatR: An R package for detection and analysis of insect defoliation signals in tree rings. Dendrochronologia. DOI: 10.1016/j.dendro.2020.125750.

Installation

You can install the released version of dfoliatR from CRAN with:

install.packages("dfoliatR")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("chguiterman/dfoliatR")

Usage

The package requires users to input two sets of tree-ring data: standardized ring widths of individual host trees and a standardized tree-ring chronology from a local non-host tree species or climate series. dfoliatR combines these to remove the climate signal represented by the non-host chronology from the host tree series. What’s left should represent a disturbance signal. Then dfoliatR identifies defoliation events in the host tree series.

We recommend that the input tree-ring data be standardized in either ARSTAN or the dplR R package. If there is more than one ring-width series from the same tree, these should be standardized and averaged to the tree level. In ARSTAN, make sure to output ‘.TRE’ files and read them into R with the read.compact() function in dplR. If you choose to standardize raw ring widths in dplR with detrend(), then use the treeMean() function to generate tree-level series. All data input to dfoliatR needs to be an rwl object as defined in dplR.

Example

Here we briefly explore defoliation and outbreaks patterns for a Douglas-fir site in New Mexico. These data are included in the package

library(dfoliatR)
## load the data
data("dmj_h")
data("dmj_nh")

To start out, we identify defoliation events on individual trees,

## Identify defoliation signals
dmj_defol <- defoliate_trees(host_tree = dmj_h, nonhost_chron = dmj_nh)

## Plot the results
plot_defol(dmj_defol)

And then scale up to outbreaks by compositing across the site via

## Identify site-level outbreak patterns
dmj_obr <- outbreak(dmj_defol)

## Plot those results
plot_outbreak(dmj_obr)

Further resources

Analyses of the tree series (termed defol objects) can be done via:

• plot_defol()
• defol_stats()
• get_defol_events()
• sample_depth()

To identify ecologically-significant outbreak events, use the outbreak() function. Various filters are available to aid users in defining outbreak thresholds. Analyses of outbreak series (termed obr objects) can be done via:

• plot_outbreak()
• outbreak_stats()

For the full range of usage in dfoliatR, please visit the introduction vignette.

Questions, concerns, problems, ideas, or want to contribute?

Please contact the author, Chris Guiterman

dfoliatr's Issues

Ongoing defoliations

If the last year of a series has a positive index, it is not allowed as an excursion in the defoliation event, and the event is cut-off. But if the user knows the event is ongoing, it should not cut-off.

Add examples to functions

Document data included in package

series_end_events label

Currently, the "series_end_event" tag in defol objects is placed regardless of whether series_end_event = TRUE in defoliate_trees(). The tag should only be placed where the variable is set to TRUE.

Flexible labels in `plot_oubreak()`

Currently only "GSI" displays in the y-axis label for plot_outbreak(). It would be better if it reflected whether the plot shows the ngsi (default) or gsi (only other option).

tree-level list of defoliation events

In `defol_stats()`, remove "series_end_event"s from duration stats

Allow `defoliate_trees` to run in host-only mode

Currently defoliate_trees can be only be done with a host and non-host chronology. Allow it to run with only a host set of tree-ring series, assuming the user has already performed series correction.

Add sort function for use in plotting

see burnr::sort.fhx()

Try to match results of OUTBREAK as best as possible.

This includes a lot of tedious checking

Add %defol line to `plot_outbreak()`

This can't be done after the fact...so the "filter_prop" variable must be passed to the obr object, probably as an "attr". then it has ot be called by plot_outbreak().

Units tests

bridge successive events

Allow user to combine 2 events if there are separated by a single year. This is response to observations that occasional successive events probably best reflect a single long event, but there are too many positive excursions to be objectively allowed. This option is being tested and should be scrutinized by users.

Add example to `plot_defol()`

Especially showing the use of the breaks argument

Change name of "corrected"series

Change package name

Back-to-back defolations

Somehow, it's possible to have two defolations, back-to-back without a break. Needs exploration and validation in id_defoliation

plotting functions broken due to changes in main.R

Include non-defoliated series in plot_defol

Series that lack identified defoliation events are ignored in plot_defol(). This also triggers an error in get_defol_events() which is actually caused bu events_table() yielded a null return.

Add flexibility for non-host chronologies

Need to ignore samp.depth. For chronology files with multiple types (std, res, ars), need to add warning message for user to select which they want and subset the input data.

Spell check everything

Depreciate and remove EF data

Updating the East Fork data, and removing the ef_* data objects. New data are labeled efk_*

Include Travis checks

Preparation for CRAN launch

fix outbreak_stats after changed to defoliate_trees and otubreak

add short-series warning to `id_defoliation`

As presented by Cody Dangerfield, if a series has only 1 year, the runs analysis, rle will fail with an NA that cascades into the for loop and fails on line 93 of "utils.R".
Need some way to catch NA in the departure runs and skip the loop.