SURD: Synergistic-Unique-Redundant Decomposition of causality

SURD is a method for causal inference in time series. It measures the information that past observations of a set of variables carry about the future of a target variable and splits it into redundant, unique and synergistic contributions. The method also quantifies the causality leak, the part of the future of the target that the observed variables cannot explain. SURD needs only pairs of past and future events, so it applies to simulations and experiments alike. It handles several variables, dependencies at different time lags and instantaneous links. The method is described in Martínez-Sánchez, Arranz & Lozano-Durán, Nature Communications 15, 9296 (2024). The subpackage surd.states resolves the same decomposition over the states of the variables, following Martínez-Sánchez & Lozano-Durán, Communications Physics 9, 15 (2025). See Causality by states.

Installation

From PyPI:

pip install surd

From a clone of this repository:

git clone https://github.com/ALD-Lab/SURD.git
cd SURD
pip install .

With conda, the environment file installs the dependencies and the package:

conda env create -f environment.yml
conda activate surd

SURD depends on NumPy, SciPy, Matplotlib and tqdm and runs on Python 3.9 or newer, on Linux, macOS and Windows. The optional extras are:

• pip install "surd[parallel]" adds pymp-pypi, which runs the loop over target variables of surd.run_parallel in parallel (Linux and macOS). Without it the targets run one after another with the same result. Example E03 of surd.states uses it too.
• pip install "surd[transport]" adds mpart for density estimation with transport maps (example E07). On osx-arm64 use pip install mpart, since the conda package does not exist for that platform. See the MParT documentation.
• pip install "surd[states]" adds scikit-image and scikit-learn for the isosurfaces of states.plot_states_3d and the density estimate of states.it_tools.hist_knn. The decomposition by states needs neither.
• pip install "surd[examples]" adds JupyterLab and marimo to run the notebooks.
• pip install "surd[docs]" adds Sphinx to build the documentation in docs/.

The cost of SURD grows with the number of variables and bins, since it estimates joint probability distributions. The examples run on a laptop with 16 GB of RAM.

Quick start

Two independent bits and a target equal to their XOR one step later. Each bit alone says nothing about the target, so the information is synergistic.

import numpy as np
import surd

rng = np.random.default_rng(0)
q1, q2 = rng.integers(0, 2, size=(2, 200_000))    # two independent bits in time
target = np.roll(q1 ^ q2, 1)                      # their XOR, one step later
Y = np.vstack([target[1:], q1[:-1], q2[:-1]])     # future of the target first, sources after
hist, _ = np.histogramdd(Y.T, bins=2)
I_R, I_S, MI, info_leak = surd.surd(hist)
surd.nice_print(I_R, I_S, MI, info_leak)

    Redundant (R):
        (1, 2)      : 0.0000
    Unique (U):
        (1,)        : 0.0000
        (2,)        : 0.0000
    Synergystic (S):
        (1, 2)      : 1.0000
    Information Leak:  0.00%

How to use the method

The input is a histogram of the joint distribution of the future of the target and the present of the sources. Axis 0 is the target and axes 1 to N are the sources. The outputs are dictionaries keyed by tuples of source indices, counted from 1.

surd.it_tools has the entropies, conditional entropies, mutual information and transfer entropy used by the method. surd.analytic_eqs has the benchmark systems of the paper. surd.transport_map estimates densities with transport maps and needs mpart.

Scripts written for the previous layout, which added utils/ to sys.path and imported surd, it_tools, analytic_eqs and transport_map as top-level modules, keep working. The files in utils/ load the package.

Examples

The notebooks in examples/ reproduce the cases of the paper. Run them from the examples folder. They import the installed package and fall back to ../src from a plain clone.

The data for E03 and E10 are in data/. E02 writes the signals it generates to data/ on the first run.

Causality by states

SURD says which variables are causal. surd.states says in which states they are. The method quantifies causality as the information gained about the future states of the target, resolved over the states of the sources and of the target, and splits it into redundant, unique and synergistic contributions as above. A state of a source is causal for a future state of the target when knowing it makes that future state more likely, and non-causal when it makes it less likely. The formulation needs only pairs of past and future events, so it applies to simulations and experiments alike. It handles several variables, dependencies at different time lags and instantaneous links, and it reports the causality that unobserved variables leave unexplained. The method is described in Martínez-Sánchez & Lozano-Durán, Communications Physics 9, 15 (2025).

A source that acts only when it is positive. Un[(1,)][t, s] is the unique causality from state s of the source to state t of the target, so the rows of positive q1 carry it.

import numpy as np
from surd import states

rng = np.random.default_rng(0)
q1, q3 = rng.standard_normal((2, 1_000_000))                                  # two sources
q2 = np.where(q1 > 0, np.sin(q1), 0.0) + 0.1 * rng.standard_normal(q1.size)  # future target: q1 acts only when positive
hist, edges = np.histogramdd(np.vstack([q2, q1, q3]).T, bins=25)              # target first, sources after
I_R, I_S, MI, leak, Rd, Un, Sy = states.surd_states(hist)                     # Rd, Un, Sy: one array per term, indexed by states
states.nice_print(I_R, I_S, MI, leak)

    Redundant (R):
        (1, 2)      : 0.0002
    Unique (U):
        (1,)        : 0.9982
        (2,)        : 0.0000
    Synergystic (S):
        (1, 2)      : 0.0016
    Information Leak: 63.40%

states.it_tools and states.analytic_eqs are the versions that ship with the paper and differ from surd.it_tools and surd.analytic_eqs: no regularization of the histogram, and the benchmark systems source and target instead of the mediator and collider cases.

The notebooks in examples/states/ reproduce the cases of the paper. Run them from that folder. The marimo/ subfolder has the same examples as marimo notebooks, which also run as plain Python scripts.

E01 and E02 generate their signals and store them in examples/states/data/ on the first run. E01 and E02 need scikit-image for the 3-D maps.

Citation

If you use SURD in your research or software, please cite the paper:

@article{surd,
author={Mart{\'\i}nez-S{\'a}nchez, {\'A}lvaro and Arranz, Gonzalo and Lozano-Dur{\'a}n, Adri{\'a}n},
title={Decomposing causality into its synergistic, unique, and redundant components},
journal={Nature Communications},
year={2024},
month={Nov},
day={01},
volume={15},
number={1},
pages={9296},
issn={2041-1723},
doi={10.1038/s41467-024-53373-4}
}

If you use surd.states, please also cite:

@article{martinez2025,
  author  = {Mart{\'i}nez-S{\'a}nchez, {\'A}lvaro and Lozano-Dur{\'a}n, Adri{\'a}n},
  title   = {Observational causality by states and interaction type for scientific discovery},
  journal = {Communications Physics},
  year    = {2025},
  month   = {Dec},
  day     = {16},
  volume  = {9},
  number  = {1},
  pages   = {15},
  issn    = {2399-3650},
  doi     = {10.1038/s42005-025-02447-w}
}

The file CITATION.cff carries both references in machine-readable form.

Acknowledgements

Enrico Foglia packaged and documented the SURD-states code that became surd.states.

License

This project is licensed under the MIT License. See LICENSE.