Detect an excursion in many timeseries

Determines whether an excursion event has occurred within the specified event window for a lipd-ts-tibble of timeseries. Excursion events are defined as n.consecutive values within the event window that are more extreme than the avg +/- sig.num standard deviations of the reference windows.

detectMultipleExcursions(
  ltt = NA,
  n.ens = 100,
  surrogate.method = "isospectral",
  null.hypothesis.n = 100,
  event.yr,
  event.window,
  ref.window,
  sig.num = 2,
  n.consecutive = 2,
  exc.type = "either",
  min.vals = 8,
  na.rm = TRUE,
  simulate.time.uncertainty = FALSE,
  simulate.paleo.uncertainty = FALSE,
  seed = as.integer(Sys.time())
)

Arguments

ltt

A LiPD-timeseries-tibble, a tibble or data.frame that has the variable(s) of interest, a time variable (age, year or time) along with their metadata, aranged in rows. If ltt = NA, then one in is created from other inputs

n.ens

How many ensembles to use for error propagation? (default = 100)

surrogate.method

What method to use to generage surrogate data for hypothesis testing? Options include:

• 'isospectral': (Default) Following Ebisuzaki (1997), generate surrogates by scrambling the phases of the data while preserving their power spectrum. This uses the To generate these "isospectral" surrogates. Uses the rEDM::make_surrogate_data() or rEDM::SurrogateData() function depending on version

• 'isopersistent': Generates surrogates by simulating from an autoregressive process of order 1 (AR(1)), which has been fit to the data. Uses the geoChronR::createSyntheticTimeseries() function

• 'shuffle': Randomly shuffles the data to create surrogates. Uses the rEDM::make_surrogate_data() or rEDM::SurrogateData() function depending on version

null.hypothesis.n

How many simulations to run for null hypothesis testing (default = 100)

event.yr

time at the center of the excursion window

event.window

width (in time units) of the excursion window

ref.window

width (in time units) of the reference windows

sig.num

how many standard deviations required outside the reference windows must be exceeded for this to be considered an excursion? (default = 2)

n.consecutive

how many consecutive points are required for this to be considered an excursion? (default = 2)

exc.type

Type of excursion to look for. "positive", "negative", "either" or "both" (default = "either")

min.vals

Minimum effective sample size (adjusted by autocorrelation) required in reference and event windows (default = 4)

na.rm

Remove NAs? (default = TRUE)

simulate.time.uncertainty

TRUE or FALSE. If an ensemble is not included, do you want to simulate time ensembles (default = TRUE)

simulate.paleo.uncertainty

TRUE or FALSE. If an ensemble is not included, do you want to simulate paleo ensembles (default = TRUE)

seed

Set a seed for reproducibility. By default it will use current time meaning it will not be reproducible.

Value

a tibble that describes the positive and negative excursion results

References

Morrill

Author

Hannah Kolus

Nick McKay