Package 'infocausality'

Title: Information-Theoretic Measure of Causality
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>.
Authors: Wenbo Lyu [aut, cre, cph] (ORCID: <https://orcid.org/0009-0002-6003-3800>)
Maintainer: Wenbo Lyu <[email protected]>
License: GPL-3
Version: 1.2
Built: 2026-05-20 06:17:52 UTC
Source: https://github.com/stscl/infocausality

Help Index

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)
)