SURD (Synergistic-Unique-Redundant Decomposition)

When performing causality analysis on time-series data, the results are highly dependent on the time lag. A common strategy is to find the lag that maximizes the 'unique causality' between different variables (excluding self-causality).

Workflow:

1. Normalize your data (zero mean, unit variance).
2. Iterate through a range of lag values.
3. For each lag, compute the joint histogram of the variables.
4. Run surd.surd(hist) to get the Redundant causality I_R.
5. Sum the unique causalities for cross-variable interactions (e.g., key != (i + 1,)).
6. Normalize this sum by the total entropy $H$ to find the relative strength.
7. Select the lag that maximizes this value.

# Simplified logic for finding optimal lag
nlags_range = range(1, 3001, 1)
cross_unique_lag = np.zeros((nvars, len(nlags_range)))

for nlag in nlags_range:
    # Prepare lagged data
    Y = np.vstack([X[i, nlag:], X[:, :-nlag]])
    hist, _ = np.histogramdd(Y.T, bins=10)
    I_R, I_S, MI, info_leak = surd.surd(hist)
    H = it.entropy_nvars(hist, (0,))

    # Sum causalities for cross-variable interactions
    single_digit_keys = [key for key in I_R.keys() if len(key) == 1 and key != (i + 1,)]
    sum_causalities = sum(I_R[key] for key in single_digit_keys)
    
    cross_unique_lag[i, nlag - 1] = sum_causalities / H

# The optimal lag is the index of the maximum value
max_lag = cross_unique_lag[target_idx, :].argmax()

To ensure accurate causality computation, you may need to find the optimal time lag for each variable. A common strategy is to select the lag that maximizes the unique causality (excluding self-causality).

Algorithm:

1. Iterate through a range of possible lags (nlags_range).
2. For each lag, construct the lagged matrix $Y$ and compute the histogram.
3. Run surd.surd(hist).
4. Sum the redundant/unique contributions for all single-digit tuples (excluding the variable's own self-causality).
5. Choose the lag that maximizes this sum.

# Conceptual implementation for finding optimal lag
for i in range(nvars):
    for nlag in nlags_range:
        # Prepare the data
        Y = np.vstack([X[i, nlag:], X[:, :-nlag]])
        hist, _ = np.histogramdd(Y.T, bins=nbins)
        I_R, I_S, MI, info_leak = surd.surd(hist)
        
        # Calculate sum of causalities for single-digit tuples (excluding self)
        single_digit_keys = [key for key in I_R.keys() if len(key) == 1 and key != (i+1,)]
        sum_causalities = sum(I_R[key] for key in single_digit_keys)
        
        # Track the sum to find the maximum
        unique_lag[i].append(sum_causalities)

The Moran effect can be simulated using a custom function that models the interaction between growth rates, delays, and environmental noise.

In the provided example, the system is defined by the following parameters:

• N: Total number of time steps.
• r1, r2: Growth rates for the $R$ variables.
• s1, s2: Growth rates for the $N$ variables.
• D1, D2: Time delays.
• psi1, psi2: Sensitivity parameters to environmental noise.
• R0: Initial value for $R$.
• N0: Initial value for $N$.

The function returns four arrays representing the time series for $R_1, N_1, R_2,$ and $N_2$.

def moran_effect(N, r1, r2, s1, s2, D1, D2, psi1, psi2, R0, N0):
    # ... implementation ...
    return R1, N1, R2, N2

# Usage
N = 10**7
r1, r2 = 3.4, 2.9
s1, s2 = 0.4, 0.35
D = 4
psi1, psi2 = 0.5, 0.6
R0, N0 = 1, 0.5

R1, N1, R2, N2 = moran_effect(N, r1, r2, s1, s2, D1=D, D2=D, psi1=psi1, psi2=psi2, R0=R0, N0=N0)

To perform SURD (Synergistic-Unique-Redundant Decomposition) analysis, you need to prepare your data as a 2D array where rows represent variables and columns represent time steps. You then pass this data to tmap.transport_map to compute the probability density function (PDF), and finally pass that PDF to surd.surd to extract causal metrics.

Workflow:

1. Prepare Data: Create a matrix Y where Y[i, :] is the time series for variable $i$. If using time-lagged analysis, ensure the dimensions of the target and predictor variables are aligned.
2. Compute Transport Map: Use tmap.transport_map(Y, nbins) to get the pdf and grids.
3. Decompose Causality: Use surd.surd(pdf) to calculate the decomposition components.

Metrics returned by surd.surd(pdf):

• I_R: Redundant information.
• I_S: Synergistic information.
• MI: Mutual Information.
• info_leak: Information leak.

import surd
import transport_map as tmap
import numpy as np

# Y is your prepared data matrix (variables x time_steps)
# nbins is the discretization level
nbins = 50

# 1. Compute the transport map PDF
pdf, grids = tmap.transport_map(Y, nbins)

# 2. Run SURD decomposition
I_R, I_S, MI, info_leak = surd.surd(pdf)

# 3. Print formatted results
surd.nice_print(I_R, I_S, MI, info_leak)