Title: Information-Theoretic Measure of Causality
Version: 1.0
Description: Methods for quantifying temporal and spatial causality through information flow, and decomposing it into unique, redundant, and synergistic components, following the framework described in Martinez-Sanchez et al. (2024) <doi:10.1038/s41467-024-53373-4>.
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.3
URL: https://stscl.github.io/infocausality/, https://github.com/stscl/infocausality
BugReports: https://github.com/stscl/infocausality/issues
Depends: R (≥ 4.1.0)
LinkingTo: Rcpp
Imports: methods, reticulate (≥ 1.41.0), sdsfun, sf, terra
Suggests: gdverse, ggplot2, knitr, Rcpp, rmarkdown, spEDM, tEDM
VignetteBuilder: knitr
NeedsCompilation: yes
Packaged: 2025-10-29 11:25:13 UTC; 31809
Author: Wenbo Lv ORCID iD [aut, cre, cph]
Maintainer: Wenbo Lv <lyu.geosocial@gmail.com>
Repository: CRAN
Date/Publication: 2025-11-03 18:30:08 UTC

synergistic-unique-redundant decomposition of causality

Description

synergistic-unique-redundant decomposition of causality

Usage

## S4 method for signature 'data.frame'
surd(
  data,
  target,
  agents,
  lag = 1,
  bin = 5,
  max.combs = NULL,
  cores = 1,
  backend = "threading"
)

## S4 method for signature 'sf'
surd(
  data,
  target,
  agents,
  lag = 1,
  bin = 5,
  max.combs = NULL,
  cores = 1,
  backend = "threading",
  nb = NULL
)

## S4 method for signature 'SpatRaster'
surd(
  data,
  target,
  agents,
  lag = 1,
  bin = 5,
  max.combs = NULL,
  cores = 1,
  backend = "threading"
)

Arguments

data

observation data.

target

name of the target variable.

agents

names of agent variables.

lag

(optional) lag order.

bin

(optional) number of discretization bins.

max.combs

(optional) maximum combination order. If NULL, the standard SURD decomposition is applied.

cores

(optional) number of cores for parallel computation.

backend

(optional) Joblib backend: loky, threading, or multiprocessing.

nb

(optional) neighbours list.

Value

A list.

unique

Unique information contributions per variable.

synergistic

Synergistic information components by agent combinations.

redundant

Redundant information shared by agent subsets.

mutual_info

Mutual information measures for each combination.

info_leak

Information leak ratio.

References

Martinez-Sanchez, A., Arranz, G. & Lozano-Duran, A. Decomposing causality into its synergistic, unique, and redundant components. Nat Commun 15, 9296 (2024).

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg", package="spEDM"))

tryCatch(
  surd(columbus, "hoval", c("inc", "crime")),
  error = \(e) message("Skipping Python-dependent example: ", e$message)
)