Cross mapping API

crossmap(measure::CrossmapMeasure, t::AbstractVector, s::AbstractVector) → ρ::Real
crossmap(measure::CrossmapMeasure, est, t::AbstractVector, s::AbstractVector) → ρ::Vector
crossmap(measure::CrossmapMeasure, t̄::AbstractVector, S̄::AbstractStateSpaceSet) → ρ

Compute the cross map estimates between between raw time series t and s (and return the real-valued cross-map statistic ρ). If a CrossmapEstimator est is provided, cross mapping is done on random subsamples of the data, where subsampling is dictated by est (a vector of values for ρ is returned).

Alternatively, cross-map between time-aligned time series t̄ and source embedding S̄ that have been constructed by jointly (pre-embedding) some input data.

This is just a wrapper around predict that simply returns the correspondence measure between the source and the target.

predict(measure::CrossmapMeasure, t::AbstractVector, s::AbstractVector) → t̂ₛ, t̄, ρ
predict(measure::CrossmapMeasure, t̄::AbstractVector, S̄::AbstractStateSpaceSet) → t̂ₛ

Perform point-wise cross mappings between source embeddings and target time series according to the algorithm specified by the given cross-map measure (e.g. ConvergentCrossMapping or PairwiseAsymmetricInference).

• First method: Jointly embeds the target t and source s time series (according to measure) to obtain time-index aligned target timeseries t̄ and source embedding S̄ (which is now a StateSpaceSet). Then calls predict(measure, t̄, S̄) (the first method), and returns both the predictions t̂ₛ, observations t̄ and their correspondence ρ according to measure.
• Second method: Returns a vector of predictions t̂ₛ (t̂ₛ := "predictions of t̄ based on source embedding S̄"), where t̂ₛ[i] is the prediction for t̄[i]. It assumes pre-embedded data which have been correctly time-aligned using a joint embedding (see embed), i.e. such that t̄[i] and S̄[i] correspond to the same time index.

Description

For each i ∈ {1, 2, …, N} where N = length(t) == length(s), we make the prediction t̂[i] (an estimate of t[i]) based on a linear combination of D + 1 other points in t, where the selection of points and weights for the linear combination are determined by the D+1 nearest neighbors of the point S̄[i]. The details of point selection and weights depend on measure.

Note: Some CrossmapMeasures may define more general mapping procedures. If so, the algorithm is described in their docstring.

CrossmapMeasure <: AssociationMeasure

The supertype for all cross-map measures. Concrete subtypes are

• ConvergentCrossMapping, or CCM for short.
• PairwiseAsymmetricInference, or PAI for short.

CrossmapEstimator{LIBSIZES, RNG}

A parametric supertype for all cross-map estimators, which are used with predict and crossmap.

Because the type of the library may differ between estimators, and because RNGs from different packages may be used, subtypes must implement the LIBSIZES and RNG type parameters.

For efficiency purposes, subtypes may contain mutable containers that can be re-used for ensemble analysis (see Ensemble).

Libraries

A cross-map estimator uses the concept of "libraries". A library is essentially just a reference to a set of points, and usually, a library refers to indices of points, not the actual points themselves.

For example, for timeseries, RandomVectors(libsizes = 50:25:100) produces three separate libraries, where the first contains 50 randomly selected time indices, the second contains 75 randomly selected time indices, and the third contains 100 randomly selected time indices. This of course assumes that all quantities involved can be indexed using the same time indices, meaning that the concept of "library" only makes sense after relevant quantities have been jointly embedded, so that they can be jointly indexed. For non-instantaneous prediction, the maximum possible library size shrinks with the magnitude of the index/time-offset for the prediction.

For spatial analyses (not yet implemented), indices could be more complex and involve multi-indices.

RandomVectors <: CrossmapEstimator
RandomVectors(; libsizes, replace = false, rng = Random.default_rng())

Cross-map over N different libraries, where N = length(libsizes), and the i-th library has cardinality k = libsizes[i]. Points within each library are randomly selected, independently of other libraries, and replace controls whether or not to sample with replacement. A user-specified rng may be specified for reproducibility.

This is method 3 from Luo et al. (2015).

See also: CrossmapEstimator.

RandomSegment <: CrossmapEstimator
RandomSegment(; libsizes::Int, rng = Random.default_rng())

Indicatates that cross mapping is performed on contiguous time series segments/windows of length L with a randomly selected starting point.

This is method 2 from (Luo et al., 2015).

ExpandingSegment <: CrossmapEstimator
ExpandingSegment(; libsizes::Int, rng = Random.default_rng())

Indicatates that cross mapping is performed on a contiguous time series segment/window, starting from the first available data point up to the Lth data point.

If used in an ensemble setting, the estimator is applied to time indices Lmin:step:Lmax of the joint embedding.