Title: Pattern Causality Analysis
Version: 0.1
Description: Infer causation from observational data through pattern causality analysis (PC), with original algorithm for time series data from Stavroglou et al. (2020) <doi:10.1073/pnas.1918269117>, as well as methodological extensions for spatial cross-sectional data introduced by Zhang & Wang (2025) <doi:10.1080/13658816.2025.2581207>, together with a systematic description proposed in Runge et al. (2023) <doi:10.1038/s43017-023-00431-y>.
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.3
URL: https://stscl.github.io/pc/, https://github.com/stscl/pc
BugReports: https://github.com/stscl/pc/issues
Depends: R (≥ 4.1.0)
LinkingTo: Rcpp, RcppThread
Imports: methods, sdsfun, sf, terra
Suggests: Rcpp, RcppThread, readr, infoxtr, spEDM, tEDM
NeedsCompilation: yes
Packaged: 2026-03-25 06:36:47 UTC; dell
Author: Wenbo Lyu ORCID iD [aut, cre, cph]
Maintainer: Wenbo Lyu <lyu.geosocial@gmail.com>
Repository: CRAN
Date/Publication: 2026-03-30 08:50:08 UTC

Optimal Parameter Search for Pattern Causality

Description

Optimal Parameter Search for Pattern Causality

Usage

## S4 method for signature 'data.frame'
ops(
  data,
  target,
  source,
  E = 3:5,
  k = E + 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  maximize = c("positive", "negative", "dark"),
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(E),
  higher.parallel = TRUE,
  h = 0
)

## S4 method for signature 'sf'
ops(
  data,
  target,
  source,
  E = 3:5,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  maximize = c("positive", "negative", "dark"),
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(E),
  higher.parallel = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
ops(
  data,
  target,
  source,
  E = 3:5,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  maximize = c("positive", "negative", "dark"),
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(E),
  higher.parallel = TRUE
)

Arguments

data

Observation data.

target

Integer of column indice for the target variable.

source

Integer of column indice for the source variable.

E

(optional) Embedding dimensions.

k

(optional) Number of nearest neighbors used for projection.

tau

(optional) Step of lag.

style

(optional) Embedding style (0 includes current state, 1 excludes it).

lib

(optional) Libraries indices.

pred

(optional) Predictions indices.

maximize

(optional) Causality metric to maximize: one of "positive", "negative", or "dark".

dist.metric

(optional) Distance measure to be used.

zero.tolerance

(optional) Maximum number of zeros tolerated in signature space.

relative

(optional) Whether to calculate relative changes in embedding.

weighted

(optional) Whether to weight causal strength.

threads

(optional) Number of threads used.

higher.parallel

(optional) Whether to use a higher level of parallelism.

h

(optional) Prediction horizon.

nb

(optional) Neighbours list.

Value

A list.

param

The selected optimal parameter combination.

xmap

A data.frame containing cross-mapping performance across parameter settings.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg", package="spEDM"))
pc::ops(columbus, 1, 3, E = 5:10, maximize = "negative", threads = 1)

Pattern Causality

Description

Pattern Causality

Usage

## S4 method for signature 'data.frame'
pc(
  data,
  target,
  source,
  libsizes = NULL,
  E = 3,
  k = E + 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  random = TRUE,
  seed = 42L,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(libsizes),
  higher.parallel = TRUE,
  verbose = TRUE,
  h = 0
)

## S4 method for signature 'sf'
pc(
  data,
  target,
  source,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  random = TRUE,
  seed = 42L,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(libsizes),
  higher.parallel = TRUE,
  verbose = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
pc(
  data,
  target,
  source,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  random = TRUE,
  seed = 42L,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(libsizes),
  higher.parallel = TRUE,
  verbose = TRUE
)

Arguments

data

Observation data.

target

Integer of column indice for the target variable.

source

Integer of column indice for the source variable.

libsizes

(optional) Number of observations used.

E

(optional) Embedding dimensions.

k

(optional) Number of nearest neighbors used for projection.

tau

(optional) Step of lag.

style

(optional) Embedding style (0 includes current state, 1 excludes it).

lib

(optional) Libraries indices.

pred

(optional) Predictions indices.

boot

(optional) Number of bootstraps to perform.

random

(optional) Whether to use random sampling.

seed

(optional) Random seed.

dist.metric

(optional) Distance measure to be used.

zero.tolerance

(optional) Maximum number of zeros tolerated in signature space.

relative

(optional) Whether to calculate relative changes in embedding.

weighted

(optional) Whether to weight causal strength.

threads

(optional) Number of threads used.

higher.parallel

(optional) Whether to use a higher level of parallelism.

verbose

(optional) Whether to show the progress bar.

h

(optional) Prediction horizon.

nb

(optional) Neighbours list.

Value

A list (when libsizes is NULL) or data.frame. If libsizes is NULL, a list with two components is returned:

causality

A data.frame containing per-sample causality results.

summary

A data.frame summarizing overall causality metrics.

Note

pc only supports numeric input data.

References

Stavroglou, S.K., Pantelous, A.A., Stanley, H.E., Zuev, K.M., 2020. Unveiling causal interactions in complex systems. Proceedings of the National Academy of Sciences 117, 7599–7605.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg", package="spEDM"))
pc::pc(columbus, 1, 3, E = 5, k = 10, threads = 1)