defoliate_trees {dfoliatR}

Identify defoliation events in host trees

Description

defoliate_trees() is the starting point for most analyses of insect defoliation signals preserved in the growth patterns of trees. It requires individual-tree standardized measurements from potential host trees and a tree-ring chronology from a nearby non-host species. First, defoliate_trees() combines these tree-ring indices by calling gsi() to perform a "correction" of the host-tree indices to remove the climatic influences on tree growth as represented by the non-host chronology. This should isolate a disturbance-related signal. Second, defoliate_trees(), runs id_defoliation(), which completes a runs analyses to evaluate sequences of negative departures in the host tree growth series (ngsi) for potential defoliation events.

Usage

defoliate_trees(
  host_tree,
  nonhost_chron = NULL,
  duration_years = 8,
  max_reduction = -1.28,
  bridge_events = FALSE,
  series_end_event = FALSE,
  list_output = FALSE
)

Arguments

host_tree

A dplR::rwl object containing the tree-level growth series for all host trees to be compared to the non-host chronology.

nonhost_chron

A dplR::rwl object containing a single non-host chronology. If blank, defoliation events will be inferred on the host_tree series as provided. It is incumbent on the user to ensure the host_tree series are properly prepared for analyses when there is no nonhost_chron provided.

duration_years

The minimum length of time in which the tree is considered to be in defoliation.

max_reduction

The minimum value of ngsi required to be considered a defoliation event. If a sequence of negative ngsi values does not reach this threshold, the potential event is rejected. Defaults to -1.28.

bridge_events

Binary, defaults to FALSE. This option allows for successive events that are separated by a single year to be bridged and become one event. It should be used cautiously and closely evaluated to ensure the likelihood that the two (or more) events are actually one long event.

series_end_event

Binary, defaults to FALSE. This option allows the user to identify an event occurring at the time of sampling as a defoliation event, regardless of duration. Including it will help to quantify periodicity and extent of an outbreak. This should only be used if the user has direct knowledge of an ongoing defoliation event when the trees were sampled.

list_output

Defaults to FALSE. This option is to output a long list object containing a separate data.frame for each series in host_tree that includes the input series and the nonhost_chron, the corrected series, and the character string identifying the defoliation events.

Value

By default this returns a long-form data frame of tree-level growth suppression indices and identified defoliation events. If list_output = TRUE, it returns a list object with each element containing a data.frame rwl object of the host and non-host series, plus the outputs from gsi(). The list object is useful for assessing the effects of running gsi() on the host and nonhost data.

Note

Other functions in dfoliatR, like outbreak() and plot_defol(), require a long-form data frame identifiable as a defol() object. Selecting list_output = TRUE will trigger errors in running other functions.

Examples

# Load host and non-host data
data("dmj_h") # Host trees
data("dmj_nh") # Non-host chronology

dmj_defol <- defoliate_trees(dmj_h, dmj_nh)