ccm_lagged: Cross-mapping from one variable to another variable over a...

Description Usage Arguments

View source: R/ccm-wrapper.R

Description

Cross-mapping from one variable to another variable over a range of lags. Wrapper around OnewayLaggedCCM allowing multiple values for each input argument. Useful when performing sensitivity tests. NOTE: automated optimisation of embedding parameters is only available in this function; lower-level functions do not implement them.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
ccm_lagged(data, lags = 0, Es = NULL, taus = NULL,
  library.sizes = c(as.integer(nrow(data)/2)), lib = c(1, dim(data)[1]),
  pred = lib, samples.original = 100, samples.surrogates = 50,
  n.surrogates = 0, surrogate.methods = c("aaft"), time.unit = NULL,
  time.bin.size = NULL, num.neighbours = NULL, random.libs = TRUE,
  with.replacement = TRUE, exclusion.radius = NULL, epsilon = NULL,
  RNGseed = 1111, silent = TRUE, time.run = F, print.to.console = T,
  time.series.length.threshold = 100, library.column = 1,
  target.column = 2, surrogate.column = target.column,
  convergence.test = TRUE, parallel = TRUE, parallelize.on.each.lag = F,
  num.cores = parallel::detectCores() - 1, regression.convergence.plots = F,
  always.run.surrogates = F, n.libsizes.to.check = 20,
  optimise.FNNdim = T, optimise.boxcountdim = T,
  which.optimdim.test = "all", min.E = 2, max.E = 10, max.tau = 10,
  plot.simplex.projection = F, ...)

Arguments

data

A data frame containing two columns - one for the presumed driver and one for the response.

lags

A vector of lags to compute CCM for.

Es

Vector of embedding dimensions. Defaults to NULL, which triggers automated optimisation of the embedding dimension up to the dimension specified by 'max.E'.

taus

Embedding lags. Can either be several types: 1. A vector of integer lags, in which case every lag provided is considered 2. NULL, which sets the embedding lag to a default value of 1. 3. "mi", which triggers automated optimisation of the embedding lag up to the dimension specified by 'max.tau' using the first minima of the lagged mutual information function. 4. "acf", which triggers automated optimisation of the embedding lag up to the dimension specified by 'max.tau' using the first minima of the lagged autocorrelation function. For densely sampled time series, the embedding lag should be set to the first minima of the autocorrelation ("acf"), or mutual information ("mi") functions. For sparsely sampled time series (for example geological time series), set the embedding lag(s) to low values (defaults to 1 if NULL).

library.sizes

The size of the random libraries drawn when calculating cross map skill.

lib

Indices of the original library time series to use as the library (training) set.

pred

Indices of the original target time series to use as prediction set. If this overlaps with the training set, make sure to use leave-K-out cross validation setting the 'exclusion.radius' parameters to a minimum of E + 1.

samples.original

The number of random libraries to draw when calculating cross map skill.

samples.surrogates

The number of surrogate series in each null ensemble.

n.surrogates

Should a surrogate test also be performed? If so, 'n.surrogates' sets the number of surrogate time series to use. By default, no surrogate test is performed (n.surrogates = 0).

surrogate.methods

Vector of types of surrogate time series to generate. Will vary depending on what null hypothesis is being tested. Defaults to AAFT surrogates.

time.unit

The time unit of the raw time series.

time.bin.size

The temporal resolution of the raw time series (given in the units indicated by 'time.unit').

num.neighbours

The number of nearest neighbours to use in predictions. Defaults to NULL, in which case it is set to E + 1 for each analysis (this number will vary depending on the particular set of embedding parameters used for that analysis).

random.libs

Whether or not to sample random library (training) sets. Defaults to TRUE.

with.replacement

Should samples be drawn with replacement? Defaults to TRUE.

exclusion.radius

The number of temporal neighbours to exclude for the leave-K-out cross validation. Must be at least E + 1. Can be one of the following: 1. An integer, in which case that exclusion radius is used. 2. NULL, which sets the exclusion radius of E + 1. 3. "mi", which triggers automated optimisation of the exclusion radius up to using the first minima of the lagged mutual information function ran over a maximum lag approximately equal to 5 3. "acf", which triggers automated optimisation of the exclusion radius up to using the first minima of the lagged autocorrelation information function ran over a maximum lag approximately equal to 5 series length.

If the embedding lag is high, the exclusion radius can be set to E + 1. If the embedding lag is low, the exclusion radius should be higher, or, even better, estimated using either "mi" or "acf".

epsilon

Exlude neighbours if the are within a distance of 'epsilon' from the predictee.

RNGseed

For reproducivility. Seed to use for the random number generator.

silent

Suppress warnings?

time.run

Time the run?

print.to.console

Display progress?

time.series.length.threshold

Display a warning if the time series length drops below this threshold.

library.column

Integer indicating which column to use as the library column (presumed response) (1 for the first column and 2 for the second column).

target.column

Integer indicating which column to use as the target column (presumed driver). Defaults to the opposite of 'library.column'.

surrogate.column

Which column to use to generate surrogates. Defaults to the value of 'target.column' (the presumed driver).

convergence.test

Should a convergence test be performed? Analyses where CCM does not convergence are nonsensical, so this option defaults to TRUE.

parallel

Activate parallellisation? Defaults to true. Currently, this only works decently on Mac and Linux systems.

parallelize.on.each.lag

Should parallellisation be done on the outer lag loop? Defaults to TRUE. Otherwise, parallellisation is done over the surrogate analyses.

num.cores

The number of CPU cores to use for parallelisation. Defaults to one core less than what is available.

regression.convergence.plots

Display regression plots for the convergence test? Defaults to FALSE.

always.run.surrogates

Should surrogate analyses be performed even if the convergence test fails? Defaults to FALSE (there is, usually, no reason to perform significance testing if the analysis is not causal to begin with).

n.libsizes.to.check

How many library sizes to use for the convergence check? Defaults to 30.

optimise.FNNdim

Optimise false nearest neighbours? Defaults to FALSE, meaning that simplex projection only is used for optimisation. If TRUE, simplex projection is performed with the minimum embedding dimension outputted from the FNN algorithm (and the box counting dimension, if acitivated). Only relevant if either 'E' or tau is set to NULL.

optimise.boxcountdim

Optimise box counting dimension? Defaults to FALSE, meaning that simplex projection only is used for optimisation. If TRUE, simplex projection is performed with the minimum embedding dimension as the first integer larger than twice the box counting algorithm of the attractor (also considering the minimum dimension indicated by the FNN algorithm, if activated). Only relevant if either 'E' or tau is set to NULL.

which.optimdim.test

Use the embedding dimension estimated by which optimisation procedure? Defaults to "all", which uses the maximum of the three methods. Other options are "FNN", "boxcount" or "simplex".

min.E

The minimum embedding dimension for which to optimise 'E'. Only relevant if 'Es' is set to NULL.

max.E

The maximum embedding dimension for which to optimise 'E'. Only relevant if 'Es' is set to NULL.

max.tau

The maximum embedding lag for which to optimise 'tau'. Only relevant if 'taus' is set to "mi" or "acf".

plot.simplex.projection

Plot simplex projection output?

...

Additional arguments to pass to lower-level functions.


kahaaga/tstools documentation built on Nov. 30, 2017, 7:24 a.m.