Detect an excursion in a timeseries

Determines whether an excursion event has occurred within the specified event window. 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.

detectExcursion(
  ltt = NA,
  time = NA,
  vals = NA,
  time.variable.name = NA,
  vals.variable.name = NA,
  time.units = NA,
  vals.units = NA,
  dataset.name = NA,
  n.ens = 100,
  output.figure.path = NA,
  surrogate.method = "isospectral",
  null.hypothesis.n = 100,
  null.quantiles = c(0.95),
  pvalue.method = "kde",
  ...
)

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

time

if ltt is not provided, input a vector or matrix of time (year or age) data. If it's a multicolumn matrix, the columns are time-ensemble members

vals

if ltt is not provided, input a vector or matrix of paleoData. If it's a multicolumn matrix, the columns are value-ensemble members

time.variable.name

If ltt is not provided, specify the name of the time variable (typically 'age' or 'year')

vals.variable.name

If ltt is not provided, specify the name of the paleo variable (e.g., 'd18O' or 'temperature'). Alternatively, if ltt is provided with more rows than expected, this term is used to attempt to select the correct row.

time.units

If ltt is not provided, specify the units the time variable (typically 'yr BP' or 'CE')

vals.units

If ltt is not provided, specify the units the paleo variable (e.g. 'permil' or 'degrees C')

dataset.name

If ltt is not provided, specify the dataset name

n.ens

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

output.figure.path

path pointing to where should the output figure be saved? An NA will not produce a figure (default = NA)

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)

null.quantiles

What quantiles to report as output from null hypothesis testing (default = c(.95, .9))

pvalue.method

method for estimating a pvalue. Options are "kde" (the default) which will use a KDE to estimate the pvalue relative to the null, or "ecdf" which will use an empirical cumulative distribution function.

...

Arguments passed on to propagateUncertainty

changeFun

the change function to across which to propagate

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)

bam.model

BAM Model parameters to use if simulating time uncertainty (default = list(ns = n.ens, name = "bernoulli", param = 0.05), paleo.uncertainty = sd(vals,na.rm = TRUE)))

paleo.uncertainty

Uncertainty to use if modelling uncertainty for paleo values. (default = sd(vals,na.rm = TRUE)/2)

paleo.ar1

Autocorrelation coefficient to use for modelling uncertainty on paleoData, what fraction of the uncertainties are autocorrelated? (default = sqrt(0.5); or 50% autocorrelated uncertainty)

paleo.arima.order

Order to use for ARIMA model used in modelling uncertainty on paleoDat (default = c(1,0,0))

summarize

Boolean. Summarize the output? Or return all the ensembles?

seed

set a seed for reproducibility

progress

show null hypothesis testing progress bar?

Value

a tibble that describes the positive and negative excursion results

References

Morrill

Author

Hannah Kolus

Nick McKay