surd 1.1.0__py3-none-any.whl

surd/__init__.py

@@ -0,0 +1,77 @@
+"""SURD: Synergistic-Unique-Redundant Decomposition of causality.
+
+SURD measures the information that past observations of a set of source
+variables carry about the future of a target variable and splits it into
+redundant, unique and synergistic contributions. The remaining uncertainty
+is the causality leak from unobserved variables.
+
+Reference: Martínez-Sánchez, Arranz & Lozano-Durán, "Decomposing causality
+into its synergistic, unique, and redundant components", Nature
+Communications 15, 9296 (2024). https://doi.org/10.1038/s41467-024-53373-4
+
+Typical use::
+
+    import numpy as np
+    import surd
+
+    hist, _ = np.histogramdd(Y.T, bins)      # Y[0] target, Y[1:] sources
+    I_R, I_S, MI, info_leak = surd.surd(hist)
+    surd.nice_print(I_R, I_S, MI, info_leak)
+
+Submodules:
+
+- ``surd.it_tools``: entropies, mutual information and transfer entropy
+  on discrete distributions.
+- ``surd.analytic_eqs``: the stochastic benchmark systems of the paper
+  (mediator, confounder, synergistic and redundant colliders).
+- ``surd.transport_map``: density estimation with triangular transport
+  maps. Imported on first access and needs the optional ``mpart`` package.
+"""
+
+import importlib
+
+from . import it_tools
+from .core import (
+    nice_print,
+    plot,
+    plot_multiple_lags,
+    plot_nlabels,
+    run,
+    run_multiple_lags,
+    run_parallel,
+    surd,
+    surd_hd,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "surd",
+    "surd_hd",
+    "run",
+    "run_parallel",
+    "run_multiple_lags",
+    "plot",
+    "plot_nlabels",
+    "plot_multiple_lags",
+    "nice_print",
+    "it_tools",
+    "analytic_eqs",
+    "transport_map",
+    "__version__",
+]
+
+# Submodules loaded on first access. ``analytic_eqs`` seeds NumPy's global
+# random generator when imported, and ``transport_map`` needs ``mpart``,
+# so neither is imported by a plain ``import surd``.
+_LAZY_SUBMODULES = ("analytic_eqs", "transport_map")
+
+
+def __getattr__(name):
+    if name in _LAZY_SUBMODULES:
+        return importlib.import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_SUBMODULES))

surd/analytic_eqs.py

@@ -0,0 +1,39 @@
+import numpy as np
+np.random.seed(10)
+
+def mediator(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q2[n]) + 0.001*W1[n]
+        q2[n+1] = np.cos(q3[n]) + 0.01*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def confounder(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q1[n] + q3[n]) + 0.01*W1[n]
+        q2[n+1] = np.cos(q2[n] - q3[n]) + 0.01*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def synergistic_collider(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q2[n] * q3[n]) + 0.001*W1[n]
+        q2[n+1] = 0.5*q2[n] + 0.1*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def redundant_collider(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        # q1[n+1] = 0.3*q1[n] + 0.7*(np.sin(q2[n]*q3[n]) + 0.1*W1[n])
+        q1[n+1] = 0.3*q1[n] + (np.sin(q2[n]*q3[n]) + 0.001*W1[n])
+        q2[n+1] = 0.5*q2[n] + 0.1*W2[n]
+        q3[n+1] = q2[n+1]
+    return q1, q2, q3

surd/core.py

@@ -0,0 +1,658 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+import itertools
+from itertools import combinations as icmb
+from itertools import chain as ichain
+from typing import Tuple, Dict
+from . import it_tools as it
+import warnings
+try:
+    import pymp  # optional: parallel loop in run_parallel (Linux and macOS)
+except ImportError:
+    pymp = None
+# Suppress all UserWarnings
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+def surd(p: np.ndarray) -> Tuple[Dict, Dict, Dict, float]:
+    '''
+    Decompose the mutual information between a target variable and a set 
+    of agent variables into three terms: Redundancy (I_R), Synergy (I_S), 
+    and Unique (I_U) information.
+    
+    The surd function is designed to compute a decomposition of 
+    the mutual information between a target variable T (signal in the future) 
+    and agent variables A (signals in the present). This decomposition results 
+    in terms related to redundancy (overlapping information), synergy 
+    (information that arises only when considering multiple variables together),
+    and unique information.
+    
+    Parameters:
+    - p (np.ndarray): A multi-dimensional array of the histogram, where the first dimension 
+      represents the target variable, and subsequent dimensions represent agent variables.
+      
+    Returns:
+    - I_R (dict): Redundancies and unique information for each variable combination.
+    - I_S (dict): Synergies for each variable combination.
+    - MI (dict): Mutual information for each variable combination.
+    - info_leak (float): Estimation of the information leak
+
+    Example: To understand the mutual information between target variable T and 
+    a combination of agent variables A1, A2, and A3, you can use:
+    I_R, I_S, MI, info_leak = surd(p)
+    '''
+
+    # Ensure no zero values in the probability distribution to avoid NaNs during log computations
+    p += 1e-14
+    # Normalize the distribution
+    p /= p.sum()
+
+    # Total number of dimensions (target + agents)
+    Ntot = p.ndim
+    # Number of agent variables
+    Nvars = Ntot - 1
+    # Number of states for the target variable
+    Nt = p.shape[0]
+    inds = range(1, Ntot)
+
+    # Calculation of information leak
+    H  = it.entropy_nvars(p, (0,) )
+    Hc = it.cond_entropy(p, (0,), range(1,Ntot) )
+    info_leak = Hc/H
+
+    # Compute the marginal distribution of the target variable
+    p_s = p.sum(axis=(*inds,), keepdims=True)
+
+    # Prepare for specific mutual information computation
+    combs, Is = [], {}
+    
+    # Iterate over all combinations of agent variables
+    for i in inds:
+        for j in list(icmb(inds, i)):
+            combs.append(j)
+            noj = tuple(set(inds) - set(j))
+            
+            # Compute joint and conditional distributions for current combinations
+            p_a = p.sum(axis=(0, *noj), keepdims=True)
+            p_as = p.sum(axis=noj, keepdims=True)
+
+            p_a_s = p_as / p_s
+            p_s_a = p_as / p_a
+
+            # Compute specific mutual information
+            Is[j] = (p_a_s * (it.mylog(p_s_a) - it.mylog(p_s))).sum(axis=j).ravel()
+
+    # Compute mutual information for each combination of agent variables
+    MI = {k: (Is[k] * p_s.squeeze()).sum() for k in Is.keys()}
+    
+    # Initialize redundancy and synergy terms
+    I_R = {cc: 0 for cc in combs}
+    I_S = {cc: 0 for cc in combs[Nvars:]}
+
+    # Process each value of the target variable
+    for t in range(Nt):
+        # Extract specific mutual information for the current target value
+        I1 = np.array([ii[t] for ii in Is.values()])
+        
+        # Sorting specific mutual information
+        i1 = np.argsort(I1)
+        lab = [combs[i_] for i_ in i1]
+        lens = np.array([len(l) for l in lab])
+
+        # Update specific mutual information based on existing maximum values
+        I1 = I1[i1]
+        for l in range(1, lens.max()):
+            inds_l2 = np.where(lens == l+1)[0]
+            Il1max = I1[lens==l].max()
+            inds_ = inds_l2[I1[inds_l2] < Il1max]
+            I1[inds_] = 0
+
+        # Recompute sorting of updated specific mutual information values
+        i1 = np.argsort(I1)
+        lab = [lab[i_] for i_ in i1]
+        
+        # Compute differences in sorted specific mutual information values
+        Di = np.diff(I1[i1], prepend=0.)
+        red_vars = list(inds)
+
+        # Distribute mutual information to redundancy and synergy terms
+        for i_, ll in enumerate(lab):
+            info = Di[i_] * p_s.squeeze()[t]
+            if len(ll) == 1:
+                I_R[tuple(red_vars)] += info
+                red_vars.remove(ll[0])
+            else:
+                I_S[ll] += info
+
+    return I_R, I_S, MI, info_leak
+
+
+def surd_hd(Y: np.ndarray, nbins, max_combs) -> Tuple[Dict, Dict, Dict]:
+    '''
+    Extension of surd to high-dimensional systems. It computes the 
+    the decomposition of information up to a given number of maximum combination
+    between variables.
+    
+    Parameters:
+    - Y (np.ndarray): A multi-dimensional array with the temporal evolution of the variables. 
+    The first dimension represents the target variable, and subsequent dimensions represent 
+    agent variables.
+    - nbins: Number of bins to discretize the histogram.
+    - max_combs: maximum order of combitations for synergistic contributions
+      
+    Returns:
+    - I_R (dict): Redundancies and unique information for each variable combination.
+    - I_S (dict): Synergies for each variable combination.
+    - MI (dict): Mutual information for each variable combination.
+
+    Example: To understand the mutual information between target variable T and 
+    a combination of agent variables A1, A2, and A3, you can use:
+    I_R, I_S, MI = surd(p)
+    '''
+
+    # Total number of dimensions (target + agents)
+    Ntot = Y.shape[0]
+    # Number of agent variables
+    Nvars = Ntot - 1
+    # Limit the maximum number of combinations to max_combs
+    max_inds = range(1, max_combs+1)
+    tot_inds = range(1, Ntot)
+
+    # Compute the marginal distribution of the target variable
+    p_target = it.myhistogram(Y[0,:].T, nbins)
+    p_target = p_target.reshape((nbins,) + (1,) * (Ntot - 1))
+
+    # Prepare for specific mutual information computation
+    combs, Is = [], {}
+    red_combs= []
+    
+    # Iterate over all combinations of agent variables
+    for i in max_inds:
+        for j in list(icmb(tot_inds, i)):
+                combs.append(j)
+                # noj = tuple(set(inds) - set(j))
+
+                shape = np.ones(Ntot, dtype=int)
+            
+                # Compute joint distributions for current combinations
+                p_a = it.myhistogram(Y[j,:].T, nbins)
+                for index in j:
+                    shape[index] = nbins
+                p_a = p_a.reshape(tuple(shape))
+                p_as = it.myhistogram(Y[(0,) + j,:].T, nbins)
+                shape[0] = nbins
+                p_as = p_as.reshape(tuple(shape))
+
+                # Compute conditional distributions for current combinations
+                p_a_s = p_as / p_target
+                p_s_a = p_as / p_a
+
+                # Compute specific mutual information
+                Is[j] = (p_a_s * (it.mylog(p_s_a) - it.mylog(p_target))).sum(axis=j).ravel()
+
+    # Compute mutual information for each combination of agent variables
+    MI = {k: (Is[k] * p_target.squeeze()).sum() for k in Is.keys()}
+    
+    # Initialize redundancy and synergy terms
+    for i in tot_inds:
+        for j in list(icmb(tot_inds, i)):
+            red_combs.append(j)
+    I_R = {cc: 0 for cc in red_combs}
+    I_S = {cc: 0 for cc in combs[Nvars:]}
+
+    # Process each value of the target variable
+    for t in range(nbins):
+        # Extract specific mutual information for the current target value
+        I1 = np.array([ii[t] for ii in Is.values()])
+        
+        # Sorting specific mutual information
+        i1 = np.argsort(I1)
+        lab = [combs[i_] for i_ in i1]
+        lens = np.array([len(l) for l in lab])
+
+        # Update specific mutual information based on existing maximum values
+        I1 = I1[i1]
+        for l in range(1, lens.max()):
+            inds_l2 = np.where(lens == l+1)[0]
+            Il1max = I1[lens==l].max()
+            inds_ = inds_l2[I1[inds_l2] < Il1max]
+            I1[inds_] = 0
+
+        # Recompute sorting of updated specific mutual information values
+        i1 = np.argsort(I1)
+        lab = [lab[i_] for i_ in i1]
+        
+        # Compute differences in sorted specific mutual information values
+        Di = np.diff(I1[i1], prepend=0.)
+        red_vars = list(tot_inds)
+
+        # Distribute mutual information to redundancy and synergy terms
+        for i_, ll in enumerate(lab):
+            info = Di[i_] * p_target.squeeze()[t]
+            if len(ll) == 1:
+                I_R[tuple(red_vars)] += info
+                red_vars.remove(ll[0])
+            else:
+                I_S[ll] += info
+
+    return I_R, I_S, MI
+
+
+def plot(I_R, I_S, info_leak, axs, nvars, threshold=0):
+    """
+    This function computes and plots information flux for given data.
+    :param I_R: Data for redundant contribution
+    :param I_S: Data for synergistic contribution
+    :param axs: Axes for plotting
+    :param colors: Colors for redundant, unique and synergistic contributions
+    :param nvars: Number of variables
+    :param threshold: Threshold as a percentage of the maximum value to select contributions to plot
+    """
+    colors = {}
+    colors['redundant'] = mcolors.to_rgb('#003049')
+    colors['unique'] = mcolors.to_rgb('#d62828')
+    colors['synergistic'] = mcolors.to_rgb('#f77f00')
+
+    for key, value in colors.items():
+        rgb = mcolors.to_rgb(value)
+        colors[key] = tuple([c + (1-c) * 0.4 for c in rgb])
+
+    # Generate keys and labels
+    # Redundant Contributions
+    I_R_keys = []
+    I_R_labels = []
+    for r in range(nvars, 0, -1):
+        for comb in icmb(range(1, nvars + 1), r):
+            prefix = 'U' if len(comb) == 1 else 'R'
+            I_R_keys.append(prefix + ''.join(map(str, comb)))
+            I_R_labels.append(f"$\\mathrm{{{prefix}}}{{{''.join(map(str, comb))}}}$")
+    
+    # Synergestic Contributions
+    I_S_keys = ['S' + ''.join(map(str, comb)) for r in range(2, nvars+1) for comb in icmb(range(1, nvars + 1), r)]
+    I_S_labels = [f"$\\mathrm{{S}}{{{''.join(map(str, comb))}}}$" for r in range(2, nvars+1) for comb in icmb(range(1, nvars + 1), r)]
+
+    label_keys, labels = I_R_keys + I_S_keys, I_R_labels + I_S_labels
+
+    # Extracting and normalizing the values of information measures
+    values = [I_R.get(tuple(map(int, key[1:])), 0) if 'U' in key or 'R' in key 
+          else I_S.get(tuple(map(int, key[1:])), 0) 
+          for key in label_keys]
+    values /= sum(values)
+    max_value = max(values)
+
+    # Filtering based on threshold
+    labels = [label for value, label in zip(values, labels) if value >= threshold]
+    values = [value for value in values if value > threshold]
+    
+    # Plotting the bar graph of information measures
+    for label, value in zip(labels, values):
+        if 'U' in label:
+            color = colors['unique']
+        elif 'S' in label:
+            color = colors['synergistic']
+        else:
+            color = colors['redundant']
+        axs[0].bar(label, value, color=color, edgecolor='black',linewidth=1.5)
+
+    if nvars == 2:
+        axs[0].set_box_aspect(1/2.5)
+    else:
+        axs[0].set_box_aspect(1/4)
+
+    # Plotting the information leak bar
+    axs[1].bar(' ', info_leak, color='gray', edgecolor='black')
+    axs[1].set_ylim([0, 1])
+    axs[0].set_yticks([0., 1.])
+    axs[0].set_ylim([0., 1.])
+
+    # change all spines
+    for axis in ['top','bottom','left','right']:
+        axs[0].spines[axis].set_linewidth(2)
+        axs[1].spines[axis].set_linewidth(2)
+
+    # increase tick width
+    axs[0].tick_params(width=3)
+    axs[1].tick_params(width=3)
+
+    return dict(zip(label_keys, values))
+
+
+def plot_nlabels(I_R, I_S, info_leak, axs, nvars, nlabels=-1):
+    """
+    This function computes and plots information flux for given data.
+    :param I_R: Data for redundant contribution
+    :param I_S: Data for synergistic contribution
+    :param axs: Axes for plotting
+    :param colors: Colors for redundant, unique and synergistic contributions
+    :param nvars: Number of variables
+    :param threshold: Threshold as a percentage of the maximum value to select contributions to plot
+    """
+    colors = {}
+    colors['redundant'] = mcolors.to_rgb('#003049')
+    colors['unique'] = mcolors.to_rgb('#d62828')
+    colors['synergistic'] = mcolors.to_rgb('#f77f00')
+
+    for key, value in colors.items():
+        rgb = mcolors.to_rgb(value)
+        colors[key] = tuple([c + (1-c) * 0.4 for c in rgb])
+
+    # Generate keys and labels
+    # Redundant Contributions
+    I_R_keys = []
+    I_R_labels = []
+    for r in range(nvars, 0, -1):
+        for comb in icmb(range(1, nvars + 1), r):
+            prefix = 'U' if len(comb) == 1 else 'R'
+            I_R_keys.append(prefix + ''.join(map(str, comb)))
+            I_R_labels.append(f"$\\mathrm{{{prefix}}}{{{''.join(map(str, comb))}}}$")
+    
+    # Synergestic Contributions
+    I_S_keys = ['S' + ''.join(map(str, comb)) for r in range(2, nvars+1) for comb in icmb(range(1, nvars + 1), r)]
+    I_S_labels = [f"$\\mathrm{{S}}{{{''.join(map(str, comb))}}}$" for r in range(2, nvars+1) for comb in icmb(range(1, nvars + 1), r)]
+
+    label_keys, labels = I_R_keys + I_S_keys, I_R_labels + I_S_labels
+
+    # Extracting and normalizing the values of information measures
+    values = [I_R.get(tuple(map(int, key[1:])), 0) if 'U' in key or 'R' in key 
+          else I_S.get(tuple(map(int, key[1:])), 0) 
+          for key in label_keys]
+    values /= sum(values)
+    max_value = max(values)
+
+    # Filtering based on threshold
+    top_n_indices = np.argsort(values)[-nlabels:]
+
+    # Filter both the values and labels arrays
+    filtered_values = values[top_n_indices]
+    filtered_labels = np.array(labels)[top_n_indices]
+    original_order_indices = np.argsort(top_n_indices)
+    filtered_values_in_original_order = filtered_values[original_order_indices]
+    filtered_labels_in_original_order = filtered_labels[original_order_indices]
+
+    # Convert filtered arrays back to lists if necessary
+    values = filtered_values_in_original_order
+    labels = filtered_labels_in_original_order.tolist()
+    
+    # Plotting the bar graph of information measures
+    for label, value in zip(labels, values):
+        if 'U' in label:
+            color = colors['unique']
+        elif 'S' in label:
+            color = colors['synergistic']
+        else:
+            color = colors['redundant']
+        axs[0].bar(label, value, color=color, edgecolor='black',linewidth=1.5)
+
+    axs[0].set_box_aspect(1/4)
+
+    # Plotting the information leak bar
+    axs[1].bar(' ', info_leak, color='gray', edgecolor='black')
+    axs[1].set_ylim([0, 1])
+    axs[0].set_yticks([0., 1.])
+    axs[0].set_ylim([0., 1.])
+
+    # change all spines
+    for axis in ['top','bottom','left','right']:
+        axs[0].spines[axis].set_linewidth(2)
+        axs[1].spines[axis].set_linewidth(2)
+
+    # increase tick width
+    axs[0].tick_params(width=3)
+    axs[1].tick_params(width=3)
+
+    return dict(zip(label_keys, values))
+
+
+def nice_print( r_, s_, mi_, leak_ ):
+    '''Print the normalized redundancies, unique and synergy particles'''
+
+    r_ = {key: value / max(mi_.values()) for key, value in r_.items()}
+    s_ = {key: value / max(mi_.values()) for key, value in s_.items()}
+
+    print( '    Redundant (R):' )
+    for k_, v_ in r_.items():
+        if len(k_) > 1:
+            print( f'        {str(k_):12s}: {v_:5.4f}' )
+
+    print( '    Unique (U):' )
+    for k_, v_ in r_.items():
+        if len(k_) == 1:
+            print( f'        {str(k_):12s}: {v_:5.4f}' )
+
+    print( '    Synergystic (S):' )
+    for k_, v_ in s_.items():
+        print( f'        {str(k_):12s}: {v_:5.4f}' )
+
+    print(f'    Information Leak: {leak_ * 100:5.2f}%')
+
+
+def run(X, nvars, nlag, nbins, axs):
+
+    information_flux = {}
+
+    for i in range(nvars):
+        print(f'SURD CAUSALITY FOR SIGNAL {i+1}')
+
+        # Organize data (0 target variable, 1: agent variables)
+        Y = np.vstack([X[i, nlag:], X[:, :-nlag]])
+
+        # Run SURD
+        hist, _ = np.histogramdd(Y.T, nbins)
+        I_R, I_S, MI, info_leak = surd(hist)
+        
+        # Print results
+        nice_print(I_R, I_S, MI, info_leak)
+
+        # Plot SURD
+        information_flux[i+1] = plot(I_R, I_S, info_leak, axs[i,:], nvars, threshold=-0.01)
+        
+        # Plot formatting
+        axs[i,0].set_title(f'${{\\Delta I}}_{{(\\cdot) \\rightarrow {i+1}}} / I \\left(Q_{i+1}^+ ; \\mathrm{{\\mathbf{{Q}}}} \\right)$', pad=12)
+        axs[i,1].set_title(f'$\\frac{{{{\\Delta I}}_{{\\mathrm{{leak}} \\rightarrow {i+1}}}}}{{H \\left(Q_{i+1} \\right)}}$', pad=20)
+        axs[i,0].set_xticklabels(axs[i,0].get_xticklabels(), fontsize=20, rotation = 60, ha = 'right', rotation_mode='anchor')
+        print('\n')
+
+    # Show the results
+    for i in range(0,nvars-1):
+        axs[i,0].set_xticklabels('')
+
+    return I_R, I_S, MI, info_leak
+
+
+def run_parallel(X, nvars, nlag, nbins, axs):
+
+    information_flux = {}
+
+    def _one(i):
+        # Organize data (0 target variable, 1: agent variables)
+        Y = np.vstack([X[i, nlag:], X[:, :-nlag]])
+
+        # Run SURD
+        hist, _ = np.histogramdd(Y.T, nbins)
+        I_R, I_S, MI, info_leak = surd(hist)
+
+        # Print results
+        print(f'SURD CAUSALITY FOR SIGNAL {i+1}')
+        nice_print(I_R, I_S, MI, info_leak)
+        print('\n')
+        return I_R, I_S, MI, info_leak
+
+    if pymp is not None:
+        Rd_results = pymp.shared.dict({})  # Dictionary to store redundant contributions
+        Sy_results = pymp.shared.dict({})  # Dictionary to store synergistic contributions
+        MI_results = pymp.shared.dict({})   # Dictionary to store mutual information results
+        info_leak_results = pymp.shared.dict({})  # Dictionary to store information leak results
+        with pymp.Parallel(nvars) as par:
+            for i in par.range(nvars):
+                Rd_results[i+1], Sy_results[i+1], MI_results[i+1], info_leak_results[i+1] = _one(i)
+    else:  # pymp not installed (e.g. Windows): same computation, one target at a time
+        Rd_results, Sy_results, MI_results, info_leak_results = {}, {}, {}, {}
+        for i in range(nvars):
+            Rd_results[i+1], Sy_results[i+1], MI_results[i+1], info_leak_results[i+1] = _one(i)
+
+    for i in range(nvars):
+        # Plot SURD
+        information_flux[i+1] = plot(Rd_results[i+1], Sy_results[i+1], info_leak_results[i+1], axs[i,:], nvars, threshold=-0.01)
+        
+        # Plot formatting
+        axs[i,0].set_title(f'${{\\Delta I}}_{{(\\cdot) \\rightarrow {i+1}}} / I \\left(Q_{i+1}^+ ; \\mathrm{{\\mathbf{{Q}}}} \\right)$', pad=12)
+        axs[i,1].set_title(f'$\\frac{{{{\\Delta I}}_{{\\mathrm{{leak}} \\rightarrow {i+1}}}}}{{H \\left(Q_{i+1} \\right)}}$', pad=20)
+        axs[i,0].set_xticklabels(axs[i,0].get_xticklabels(), fontsize=20, rotation = 60, ha = 'right', rotation_mode='anchor')
+
+    # Show the results
+    for i in range(0,nvars-1):
+        axs[i,0].set_xticklabels('')
+
+    # Same return value as before: the decomposition for the first target
+    return Rd_results[1], Sy_results[1], MI_results[1], info_leak_results[1]
+
+
+def plot_multiple_lags(I_R, I_S, info_leak, axs, n_vars_lag, n_lag, threshold=0):
+    """
+    This function computes and plots information flux for given data.
+    :param I_R: Data for redundant contribution
+    :param I_S: Data for synergistic contribution
+    :param axs: Axis for plotting
+    :param n_vars_lag: Number of variables including lags
+    :param n_lag: Number of lags
+    :param threshold: Threshold as a percentage of the maximum value to select contributions to plot
+    """
+    colors = {}
+    colors['redundant'] = mcolors.to_rgb('#003049')
+    colors['unique'] = mcolors.to_rgb('#d62828')
+    colors['synergistic'] = mcolors.to_rgb('#f77f00')
+
+    for key, value in colors.items():
+        rgb = mcolors.to_rgb(value)
+        colors[key] = tuple([c + (1-c) * 0.4 for c in rgb])
+
+    # Generate keys and labels
+    n_vars = n_vars_lag // n_lag
+
+    # Redundant Contributions
+    I_R_keys = []
+    I_R_labels = []
+    # for r in range(1, n_vars_lag + 1):
+    for r in range(n_vars_lag, 0, -1):
+        for comb in itertools.combinations(range(1, n_vars_lag + 1), r):
+            prefix = 'U' if len(comb) == 1 else 'R'
+            I_R_keys.append(prefix + ''.join(map(str, comb)))
+
+            # New label generation with subscripts for lags
+            new_comb_labels = []
+            for c in comb:
+                lag_number = (c - 1) // n_vars
+                var_number = (c - 1) % n_vars + 1
+                new_label = f"{var_number}_{{{lag_number+1}}}"
+                new_comb_labels.append(new_label)
+
+            I_R_labels.append(f"$\\mathrm{{{prefix}}}{{{''.join(new_comb_labels)}}}$")
+    
+    # Synergestic Contributions
+    I_S_keys = []
+    I_S_labels = []
+    for r in range(2, n_vars_lag + 1):  # Starting from 2 because synergistic contributions require at least two variables
+        for comb in itertools.combinations(range(1, n_vars_lag + 1), r):
+            # Generating the key
+            I_S_keys.append('S' + ''.join(map(str, comb)))
+
+            # Generating the label with subscripts for lags
+            new_comb_labels = []
+            for c in comb:
+                lag_number = (c - 1) // n_vars
+                var_number = (c - 1) % n_vars + 1
+                new_label = f"{var_number}_{{{lag_number+1}}}"
+                new_comb_labels.append(new_label)
+
+            I_S_labels.append(f"$\\mathrm{{S}}{{{''.join(new_comb_labels)}}}$")
+
+    label_keys, labels = I_R_keys + I_S_keys, I_R_labels + I_S_labels
+
+    # Extracting and normalizing the values of information measures
+    values = [I_R.get(tuple(map(int, key[1:])), 0) if 'U' in key or 'R' in key 
+          else I_S.get(tuple(map(int, key[1:])), 0) 
+          for key in label_keys]
+    values /= sum(values)
+    max_value = max(values)
+
+    # Filtering based on threshold
+    labels = [label for value, label in zip(values, labels) if value >= threshold]
+    values = [value for value in values if value > threshold]
+
+    # Plotting the bar graph of information measures
+    for label, value in zip(labels, values):
+        if 'U' in label:
+            color = colors['unique']
+        elif 'S' in label:
+            color = colors['synergistic']
+        else:
+            color = colors['redundant']
+        axs[0].bar(label, value, color=color, edgecolor='black',linewidth=1.5)
+    
+    # Plotting the bar graph of information measures
+    axs[0].set_xticks(range(len(values)))
+    shift_labels = axs[0].set_xticklabels(labels, fontsize=15, rotation = 60, ha = 'right', rotation_mode='anchor')
+    axs[0].set_box_aspect(1/5)
+
+    # Plotting the information leak bar
+    axs[1].bar(' ', info_leak, color='gray', edgecolor='black')
+    axs[1].set_ylim([0, 1])
+
+    # change all spines
+    for axis in ['top','bottom','left','right']:
+        axs[0].spines[axis].set_linewidth(1.5)
+        axs[1].spines[axis].set_linewidth(1.5)
+
+    # increase tick width
+    axs[0].tick_params(width=1.5)
+    axs[1].tick_params(width=1.5)
+
+    return dict(zip(label_keys, values))
+
+
+def run_multiple_lags(X, nvars, nlag, nbins, max_combs, axs):
+    "Run SURD causality for different lags (from lag 1 up to nlag)"
+    information_flux = {}
+
+    for i in range(nvars):
+        print(f'SURD CAUSALITY FOR SIGNAL {i+1}')
+
+        # Organize data (0 target variable, 1: agent variables)
+        Y = X[i, nlag+1:]
+        # Create the lagged versions of X and append to the list
+        for lag in range(nlag, 0, -1):
+            Y = np.vstack([Y, X[:, lag:-nlag + lag - 1]])
+
+        # Run SURD
+        I_R, I_S, MI = surd_hd(Y, nbins, max_combs)
+
+        # Calculate information leak
+        hist = it.myhistogram(Y[0,:].T, nbins)
+        H  = it.entropy_nvars(hist, (0,) )
+        info_leak = 1 - (sum(I_R.values()) + sum(I_S.values())) / H
+        
+        # Print results
+        nice_print(I_R, I_S, MI, info_leak)
+        print('\n')
+
+        # Plot SURD
+        information_flux[i+1] = plot_multiple_lags(I_R, I_S, info_leak, axs[i,:], nvars*nlag, nlag, threshold=-0.01)
+        
+        # Plot formatting
+        axs[i,0].set_title(f'${{\\Delta I}}_{{(\\cdot) \\rightarrow {i+1}}} / I \\left(Q_{i+1}^+ ; \\mathrm{{\\mathbf{{Q}}}} \\right)$', pad=10)
+        axs[i,1].set_title(f'$\\frac{{{{\\Delta I}}_{{\\mathrm{{leak}} \\rightarrow {i+1}}}}}{{H \\left(Q_{i+1} \\right)}}$', pad=18)
+        axs[i,1].set_yticks([0,1])
+        axs[i,0].set_xticklabels(axs[i,0].get_xticklabels(), fontsize=14, rotation = 60, ha = 'right', rotation_mode='anchor')
+
+        # change all spines
+        for axis in ['top','bottom','left','right']:
+            axs[i,0].spines[axis].set_linewidth(2.5)
+            axs[i,1].spines[axis].set_linewidth(2.5)
+        axs[i,0].set_box_aspect(1/4.5)
+
+    # Show the results
+    for i in range(0,nvars-1):
+        axs[i,0].set_xticklabels('')
+
+    return I_R, I_S, MI, info_leak

surd/it_tools.py

@@ -0,0 +1,166 @@
+import numpy as np
+
+
+def myhistogram(x, nbins):
+
+    hist, _ = np.histogramdd(x, nbins)
+
+    hist += 1e-14
+    hist /= hist.sum()
+
+    return hist
+
+
+def mylog(x):
+    """
+    Compute the logarithm in base 2 avoiding singularities.
+    
+    Parameters:
+    - x (np.array): Input data.
+
+    Returns:
+    - np.array: Logarithm in base 2 of the input.
+    """
+    valid_indices = (x != 0) & (~np.isnan(x)) & (~np.isinf(x))
+    
+    log_values = np.zeros_like(x)
+    log_values[valid_indices] = np.log2(x[valid_indices])
+    
+    return log_values
+
+
+def entropy(p):
+    """
+    Compute the entropy of a discrete probability distribution function.
+
+    Parameters:
+    - p (np.array): Probability distribution of the signal.
+
+    Returns:
+    - float: Entropy of the given distribution.
+    """
+    return -np.sum(p * mylog(p))
+
+
+def entropy_nvars(p, indices):
+    """
+    Compute the joint entropy for specific dimensions of a probability distribution.
+
+    Parameters:
+    - p (np.array): N-dimensional joint probability distribution.
+    - indices (tuple): Dimensions over which the entropy is to be computed.
+
+    Returns:
+    - float: Joint entropy for specified dimensions.
+
+    Example: compute the joint entropy H(X0,X3,X7)
+    >>> entropy_nvars(p, (0,3,7))
+    """
+    excluded_indices = tuple(set(range(p.ndim)) - set(indices))
+    marginalized_distribution = p.sum(axis=excluded_indices)
+
+    return entropy(marginalized_distribution)
+
+
+def cond_entropy(p, target_indices, conditioning_indices):
+    """
+    Compute the conditional entropy between two sets of variables.
+
+    Parameters:
+    - p (np.array): N-dimensional joint probability distribution.
+    - target_indices (tuple): Variables for which entropy is to be computed.
+    - conditioning_indices (tuple): Conditioning variables.
+
+    Returns:
+    - float: Conditional entropy.
+
+    Example: compute the conditional entropy H(X0,X2|X7)
+    >>> cond_entropy(p, (0, 2), (7,))
+    """
+    joint_entropy = entropy_nvars(p, set(target_indices) | set(conditioning_indices))
+    conditioning_entropy = entropy_nvars(p, conditioning_indices)
+
+    return joint_entropy - conditioning_entropy
+
+
+def mutual_info(p, set1_indices, set2_indices):
+    """
+    Compute the mutual information between two sets of variables.
+
+    Parameters:
+    - p (np.array): N-dimensional joint probability distribution.
+    - set1_indices (tuple): Indices of the first set of variables.
+    - set2_indices (tuple): Indices of the second set of variables.
+
+    Returns:
+    - float: Mutual information.
+
+    Example: compute the mutual information I(X0,X5;X4,X2)
+    >>> mutual_info(p, (0, 5), (4, 2))
+    """
+    entropy_set1 = entropy_nvars(p, set1_indices)
+    conditional_entropy = cond_entropy(p, set1_indices, set2_indices)
+
+    return entropy_set1 - conditional_entropy
+
+
+def cond_mutual_info(p, ind1, ind2, ind3):
+    """
+    Compute the conditional mutual information between two sets of variables 
+    conditioned to a third set.
+
+    Parameters:
+    - p (np.array): N-dimensional joint probability distribution.
+    - ind1 (tuple): Indices of the first set of variables.
+    - ind2 (tuple): Indices of the second set of variables.
+    - ind3 (tuple): Indices of the conditioning variables.
+
+    Returns:
+    - float: Conditional mutual information.
+
+    Example: compute the conditional mutual information I(X0,X5;X4,X2|X1)
+    cond_mutual_info(p, (0, 5), (4, 2), (1,)))
+    """
+    # Merge indices of ind2 and ind3
+    combined_indices = tuple(set(ind2) | set(ind3))
+    
+    # Compute conditional mutual information
+    return cond_entropy(p, ind1, ind3) - cond_entropy(p, ind1, combined_indices)
+
+
+def transfer_entropy(p, target_var):
+    """
+    Calculate the transfer entropy from each input variable to the target variable.
+
+    Parameters:
+    - p (np.array): Multi-dimensional array containing the pdfs of the variables.
+      The first dimension corresponds to the index of the variable:
+          p[0]  -> target variable (in future)
+          p[1:] -> input variables (at present time)
+
+    Returns:
+    - np.array: Transfer entropy values for each input variable.
+    """
+    num_vars = len(p.shape) - 1  # Excluding the future variable
+    TE = np.zeros(num_vars)
+    
+    for i in range(1, num_vars + 1):
+        # The indices for the present variables
+        present_indices = tuple(range(1, num_vars + 1))
+        
+        # The indices for the present variables excluding the i-th variable
+        # conditioning_indices = tuple([target_var] + [j for j in range(1, num_vars + 1) if j != i])
+        conditioning_indices = tuple([target_var] + [j for j in range(1, num_vars + 1) if j != i and j != target_var])
+        
+        # Conditional entropy of the future state of the target variable given its own past
+        cond_ent_target_given_past = cond_entropy(p, (0,), conditioning_indices)
+        
+        # Conditional entropy of the future state of the target variable given its own past and the ith input variable
+        cond_ent_target_given_past_and_input = cond_entropy(p, (0,), present_indices)
+        
+        # Transfer entropy calculation
+        TE[i-1] = cond_ent_target_given_past - cond_ent_target_given_past_and_input
+    
+    return TE
+
+

surd/transport_map.py

@@ -0,0 +1,86 @@
+import numpy as np
+import mpart as mt
+from scipy.stats import multivariate_normal
+from scipy.optimize import minimize
+print('Kokkos is using', mt.Concurrency(), 'threads')
+
+# Negative log likelihood objective
+def obj(coeffs, tri_map,x):
+    """ Evaluates the log-likelihood of the samples using the map-induced density. """
+    num_points = x.shape[1]
+    tri_map.SetCoeffs(coeffs)
+
+    # Reference density
+    rho1 = multivariate_normal(np.zeros(1),np.eye(1))   
+
+    # Compute the map-induced density at each point
+    map_of_x = tri_map.Evaluate(x)
+    rho_of_map_of_x = rho1.logpdf(map_of_x.T)
+    log_det = tri_map.LogDeterminant(x)
+
+    # Return the negative log-likelihood of the entire dataset
+    return -np.sum(rho_of_map_of_x + log_det)/num_points
+
+def grad_obj(coeffs, tri_map, x):
+    """ Returns the gradient of the log-likelihood objective wrt the map parameters. """
+    num_points = x.shape[1]
+    tri_map.SetCoeffs(coeffs)
+
+    # Evaluate the map
+    map_of_x = tri_map.Evaluate(x)
+
+    # Now compute the inner product of the map jacobian (\nabla_w S) and the gradient (which is just -S(x) here)
+    grad_rho_of_map_of_x = -tri_map.CoeffGrad(x, map_of_x)
+
+    # Get the gradient of the log determinant with respect to the map coefficients
+    grad_log_det = tri_map.LogDeterminantCoeffGrad(x)
+
+    return -np.sum(grad_rho_of_map_of_x + grad_log_det, 1)/num_points
+
+def pullback_pdf(tri_map,rho,x):
+    r = tri_map.Evaluate(x)
+    log_pdf = rho.logpdf(r.T)+tri_map.LogDeterminant(x)
+    return np.exp(log_pdf)
+
+def transport_map(x, nbins):
+    nvars = x.shape[0]      # Number of variables
+    total_order = 4         # Total order of the polynomial expansion
+    components = []         # To store each component of the map
+
+    for var in range(1, nvars + 1):
+        # Create a FixedMultiIndexSet for each variable up to the total order
+        fixed_mset = mt.FixedMultiIndexSet(var, total_order)
+        map_options = mt.MapOptions()
+        S = mt.CreateComponent(fixed_mset, map_options)
+
+        # Optimize the component
+        optimizer_options = {'gtol': 1e-4, 'disp': True}
+        res = minimize(obj, S.CoeffMap(), args=(S, x[:var, :]), jac=grad_obj, method='BFGS', options=optimizer_options)
+
+        # Store the optimized component
+        components.append(S)
+
+    # Assemble the TriangularMap from the optimized components
+    transport_map = mt.TriangularMap(components)
+    
+    # Set coefficients for the entire map (assuming obj and grad_obj functions can handle this structure)
+    coeffs = np.concatenate([comp.CoeffMap() for comp in components])
+    transport_map.SetCoeffs(coeffs)
+
+    # Evaluation grid
+    grids = []
+    for i in range(x.shape[0]):
+        grid_i = np.linspace(x[i, :].min(), x[i, :].max(), nbins)
+        grids.append(grid_i)
+    
+    meshgrids = np.meshgrid(*grids, indexing='ij')
+    grid_points = np.vstack([grid.flatten() for grid in meshgrids])
+
+    # Compute joint pdf
+    ref_distribution = multivariate_normal(np.zeros(nvars), np.eye(nvars))
+    map_induced_pdf = pullback_pdf(transport_map, ref_distribution, grid_points)
+
+    # Construct the shape tuple for reshaping
+    reshaped = (nbins,) * nvars
+
+    return map_induced_pdf.reshape(reshaped), meshgrids

surd-1.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: surd
+Version: 1.1.0
+Summary: Synergistic-Unique-Redundant Decomposition of causality for time series
+Project-URL: Repository, https://github.com/ALD-Lab/SURD
+Project-URL: Paper, https://doi.org/10.1038/s41467-024-53373-4
+Project-URL: Changelog, https://github.com/ALD-Lab/SURD/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ALD-Lab/SURD/issues
+Author: Álvaro Martínez-Sánchez, Gonzalo Arranz, Adrián Lozano-Durán
+License-Expression: MIT
+License-File: LICENSE
+Keywords: causal inference,causality,information theory,mutual information,redundancy,synergy,time series,turbulence
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Provides-Extra: examples
+Requires-Dist: jupyterlab; extra == 'examples'
+Provides-Extra: parallel
+Requires-Dist: pymp-pypi; (platform_system != 'Windows') and extra == 'parallel'
+Provides-Extra: transport
+Requires-Dist: mpart; extra == 'transport'
+Description-Content-Type: text/markdown
+
+# SURD: Synergistic-Unique-Redundant Decomposition of causality
+
+[![tests](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml/badge.svg)](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/surd.svg)](https://pypi.org/project/surd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Paper](https://img.shields.io/badge/Nat.%20Commun.-10.1038%2Fs41467--024--53373--4-blue)](https://doi.org/10.1038/s41467-024-53373-4)
+
+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).
+
+![SURD diagram](https://github.com/user-attachments/assets/937fa18d-1179-4cfe-ae5a-e262582614a0)
+
+## Installation
+
+From PyPI:
+```sh
+pip install surd
+```
+
+From a clone of this repository:
+```sh
+git clone https://github.com/ALD-Lab/SURD.git
+cd SURD
+pip install .
+```
+
+With conda, the environment file installs the dependencies and the package:
+```sh
+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. Three optional extras exist:
+
+- `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.
+- `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](https://measuretransport.github.io/MParT/).
+- `pip install "surd[examples]"` adds JupyterLab to run the notebooks.
+
+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.
+
+```python
+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.
+
+| Function | What it does |
+|---|---|
+| `surd.surd(p)` | Decomposition of the histogram `p`. Returns `I_R` (redundant terms, with the unique terms under the one-element keys), `I_S` (synergistic terms), `MI` (mutual information of each subset of sources with the target) and `info_leak`, the causality leak in [0, 1]. |
+| `surd.surd_hd(Y, nbins, max_combs)` | Same decomposition from the signals `Y` (target first) for systems with many variables. Synergies are computed up to `max_combs` sources at a time. Returns `I_R`, `I_S` and `MI`. |
+| `surd.run(X, nvars, nlag, nbins, axs)` | Runs `surd.surd` with each of the `nvars` signals of `X` as target at lag `nlag`, prints and plots the result. |
+| `surd.run_parallel(...)` | Same as `surd.run`, with the targets in parallel when `pymp` is available. |
+| `surd.run_multiple_lags(X, nvars, nlag, nbins, max_combs, axs)` | Same as `surd.run` with all lags from 1 to `nlag` as sources. |
+| `surd.nice_print(I_R, I_S, MI, info_leak)` | Prints the terms normalized by the mutual information of the full set of sources and the leak in percent. |
+| `surd.plot(I_R, I_S, info_leak, axs, nvars, threshold)` | Bar chart of the normalized terms (blue redundant, red unique, orange synergistic) and a separate bar for the leak. |
+
+`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/`](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.
+
+| Notebook | What it shows |
+|---|---|
+| [E01](examples/E01_logic_gates.ipynb) | Logic gates. A duplicated source is redundant, a copied source is unique, an XOR is synergistic. |
+| [E02](examples/E02_building_blocks.ipynb) | Building blocks of causal interactions: mediator, confounder, synergistic collider and redundant collider. |
+| [E03](examples/E03_energy_cascade.ipynb) | Energy cascade in isotropic turbulence. Causality between the energy transfer at four scales from a direct numerical simulation. |
+| [E04](examples/E04_lagged_dependencies.ipynb) | Stochastic systems with dependencies at several time lags, linear and nonlinear. |
+| [E05](examples/E05_Moran_effect.ipynb) | Moran effect. Two populations driven by a common environmental forcing that is not observed. |
+| [E06](examples/E06_logistic_system.ipynb) | Coupled logistic maps with one-way and two-way coupling. |
+| [E07](examples/E07_transport_map.ipynb) | Density estimation with transport maps instead of histograms (needs `mpart`). |
+| [E08](examples/E08_eight_species.ipynb) | System with eight interacting species. Decomposition with synergies truncated at a given order. |
+| [E09](examples/E09_contemporaneous.ipynb) | Systems with contemporaneous links on top of mediator, confounder and synergistic interactions. |
+| [E10](examples/E10_inner_outer.ipynb) | Experimental data from a turbulent boundary layer. Causality between inner-layer and outer-layer velocity motions as a function of the time lag. |
+
+The data for E03 and E10 are in [`data/`](data). E02 writes the signals it generates to `data/` on the first run.
+
+## Citation
+
+If you use SURD in your research or software, please cite the paper:
+
+```bibtex
+@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}
+}
+```
+
+The file [`CITATION.cff`](CITATION.cff) carries the same reference in machine-readable form.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

surd-1.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+surd/__init__.py,sha256=OrqXAu2IN48Uqg5jJE_IYOxMUiuJneV4P_KA4oC7oW8,2176
+surd/analytic_eqs.py,sha256=L0pzMtZrD7Z-5Av68oMVH-p3qhyrxxwm-FObB3ZJdpY,1542
+surd/core.py,sha256=5Ikb2ACxgtZBdUidDXj0rAZXfV80S1-xeBggaoCyqqA,25132
+surd/it_tools.py,sha256=Omx1LjeWF3TMlR26-F0V4vw5SGw9Qu-o4H0O3pBVThg,5223
+surd/transport_map.py,sha256=6LaVYyVxju8FJLuQVGHO75x1kHneFzNlaieaMWdWxSg,3228
+surd-1.1.0.dist-info/METADATA,sha256=EFZpjq6JYGp_k1d5C1TpSRaC17u1RNpsR5QL9z_jZBk,9513
+surd-1.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+surd-1.1.0.dist-info/licenses/LICENSE,sha256=v2fBj03zZIq4jRRC6nk1irOrFj141DdJKUtG_DT-dco,1091
+surd-1.1.0.dist-info/RECORD,,

surd-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

surd-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MIT Computational Turbulence Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.