Title:	Pattern Causality Analysis
Version:	0.2
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 Lyu et al. (2026) <doi:10.1016/j.compenvurbsys.2026.102435>.
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:	ggplot2, methods, sdsfun, sf, stats, terra
Suggests:	Rcpp, RcppThread, readr, infoxtr, spEDM, tEDM
NeedsCompilation:	yes
Packaged:	2026-04-10 09:56:50 UTC; dell
Author:	Wenbo Lyu [aut, cre, cph]
Maintainer:	Wenbo Lyu <lyu.geosocial@gmail.com>
Repository:	CRAN
Date/Publication:	2026-04-10 11:00:21 UTC

False Nearest Neighbors

Description

False Nearest Neighbors

Usage

## S4 method for signature 'data.frame'
fnn(
  data,
  target,
  E = 2:10,
  k = 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  rt = 10,
  eps = NULL,
  threads = length(E),
  higher.parallel = TRUE,
  ...
)

## S4 method for signature 'sf'
fnn(
  data,
  target,
  E = 3:10,
  k = 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  rt = 10,
  eps = NULL,
  threads = length(E),
  higher.parallel = TRUE,
  detrend = FALSE,
  nb = NULL,
  ...
)

## S4 method for signature 'SpatRaster'
fnn(
  data,
  target,
  E = 3:10,
  k = 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  rt = 10,
  eps = NULL,
  threads = length(E),
  higher.parallel = TRUE,
  detrend = FALSE,
  ...
)

Arguments

Value

A vector.

References

Kennel, M.B., Brown, R., Abarbanel, H.D.I., 1992. Determining embedding dimension for phase-space reconstruction using a geometrical construction. Physical Review A 45, 3403–3411.

Examples

crash = sf::read_sf(system.file("case/crash.gpkg", package = "pc"))
pc::fnn(crash, 1, threads = 1)

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,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  maximize = c("dark", "positive", "negative"),
  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 + 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  maximize = c("dark", "positive", "negative"),
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(E),
  higher.parallel = TRUE,
  detrend = FALSE,
  nb = NULL,
  ...
)

## S4 method for signature 'SpatRaster'
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,
  detrend = FALSE,
  ...
)

Arguments

Value

A list.

param

The selected optimal parameter combination.

xmap

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

Examples

crash = sf::read_sf(system.file("case/crash.gpkg", package = "pc"))
pc::ops(crash, 1, 2, E = 3:10, maximize = "positive", threads = 1)

Pattern Causality

Description

Pattern Causality

Usage

## S4 method for signature 'data.frame'
pc(
  data,
  target,
  source,
  libsizes = NULL,
  E = 3,
  k = E,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  replace = FALSE,
  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 + 1,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  replace = FALSE,
  seed = 42L,
  dist.metric = c("euclidean", "manhattan", "maximum"),
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  threads = length(libsizes),
  higher.parallel = TRUE,
  verbose = TRUE,
  detrend = FALSE,
  nb = NULL,
  ...
)

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

Arguments

Value

A list.

causality

A data.frame of causality results. When libsizes is NULL, it contains per-sample causality estimates; otherwise, it contains causality results evaluated across different library sizes.

summary

A data.frame summarizing overall causality metrics. Only returned when libsizes is NULL.

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

crash = sf::read_sf(system.file("case/crash.gpkg", package = "pc"))
p1 = pc::pc(crash, 1, 2, E = 8, k = 8, threads = 1)
print(p1)
plot(p1)

# convergence diagnostics
p2 = pc::pc(crash, 1, 2, libsizes = seq(10,172,40), E = 8, k = 8, threads = 1)
print(p2)
plot(p2)