CCM: Convergent cross mapping

In rEDM: Empirical Dynamic Modeling ('EDM')

Convergent cross mapping

Description

The state-space of a multivariate dynamical system (not a purely stochastic one) encodes coherent phase-space variable trajectories. If enough information is available, one can infer the presence or absence of cross-variable interactions associated with causal links between variables. CCM measures the extent to which states of variable Y can reliably estimate states of variable X. This can happen if X is causally influencing Y.

If cross-variable state predictability converges as more state-space information is provided, this indicates a causal link. CCM performs this cross-variable mapping using Simplex, with convergence assessed across a range of observational library sizes as described in Sugihara et al. 2012.

Usage

CCM(dataFrame = NULL, columns, target, E, Tp = 0, knn = 0, tau = -1,
    exclusionRadius = 0, libSizes, sample = 30, seed = NULL,
    embedded = FALSE, validLib = logical(0), includeData = FALSE,
    numProcess = 4, backend = "RANN", pathIn = "./", dataFile = "",
    pathOut = "./", predictFile = "", parameterList = FALSE, showPlot = FALSE)

Arguments

dataFrame	A data.frame of input data. The first column must be a time index or time values unless noTime = TRUE. The columns must be named.
columns	Column name(s) to build the embedding: character vector or space-separated string of columns to create the library. If individual column names contain whitespace place names in a vector, or, append ',' to the name.
target	Target column name to predict.
E	Embedding dimension.
Tp	Forecast interval (prediction horizon).
knn	Number of nearest neighbours. 0 selects the method default.
tau	Embedding delay (negative selects past lags).
exclusionRadius	Temporal (Theiler) exclusion radius around each prediction point.
libSizes	Library sizes: string of 3 whitespace separated integer values specifying the intial library size, the final library size, and the library size increment. Can also be a list of strictly ncreasing library sizes.
sample	Number of random subsamples per library size.
seed	Random seed for reproducibility (not bit-comparable to pyEDM/NumPy).
embedded	If TRUE, columns already form the embedding.
validLib	Logical vector marking admissible library rows (or length 0 for all).
includeData	Add per-library-size sample-variance columns to the result.
numProcess	Number of worker processes for the parameter sweep or task grid.
backend	Nearest-neighbour backend: "RANN" (default) or "brute".
pathIn	File path for input dataFile.
dataFile	Input dataFile, .csv format. The first column must be a time index or time values unless noTime is TRUE. The first row must be column names.
pathOut	Output file path for predictFile
predictFile	Output file name, .csv format.
parameterList	Append named list of parameters/values to return.
showPlot	If TRUE, draw a base-graphics plot of the result.

Value

A data.frame with 3 columns. The first column is LibSize specifying the subsampled library size. Columns 2 and 3 report Pearson correlation coefficients for the prediction of X from Y, and Y from X.

If includeData = TRUE and parameterList = TRUE a named list "parameters" is added.

References

Sugihara G., May R., Ye H., Hsieh C., Deyle E., Fogarty M., Munch S., 2012. Detecting Causality in Complex Ecosystems. Science 338:496-500.

Examples

data(sardine_anchovy_sst)
df = CCM( dataFrame = sardine_anchovy_sst, E = 3, Tp = 0, columns = "anchovy",
target = "np_sst", libSizes = "10 70 10", sample = 100 )

rEDM documentation built on Aug. 30, 2026, 9:07 a.m.