Package {pc}

Title:	Pattern Causality Analysis
Version:	0.3
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
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, knitr, rmarkdown
VignetteBuilder:	knitr
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.1.0
NeedsCompilation:	yes
Packaged:	2026-10-10 05:17:14 UTC; 31809
Author:	Wenbo Lyu [aut, cre, cph]
Maintainer:	Wenbo Lyu <lyu.geosocial@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-10 05:30:02 UTC

Delayed Mutual Information

Description

Delayed Mutual Information

Usage

## S4 method for signature 'data.frame'
dmi(
  data,
  target,
  tau = 1:10,
  pred = NULL,
  k = 3,
  base = exp(1),
  normalize = FALSE,
  threads = length(tau),
  ...
)

Arguments

Value

A vector.

Note

dmi is only supported for time-series inputs.

References

Fraser, A.M., Swinney, H.L., 1986. Independent coordinates for strange attractors from mutual information. Physical Review A 33, 1134–1140.

Kraskov, A., Stogbauer, H., Grassberger, P., 2004. Estimating mutual information. Physical Review E 69, 066138.

Examples

abun = readr::read_csv(system.file("case/abundance.csv", package = "pc"))
pc::dmi(abun, 2)

False Nearest Neighbors

Description

False Nearest Neighbors

Usage

## S4 method for signature 'data.frame'
fnn(
  data,
  target,
  E = 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 = 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 = 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,
  source,
  target,
  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,
  source,
  target,
  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,
  source,
  target,
  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.

causality

A data.frame containing results across parameter settings.

Examples

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

Pattern Causality

Description

Pattern Causality

Usage

## S4 method for signature 'data.frame'
pc(
  data,
  source,
  target,
  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,
  source,
  target,
  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,
  source,
  target,
  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, 2, 1, E = 3, k = 7, threads = 1)
print(p1)
plot(p1)

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