Quickstart

This quickstart guide will get you up and running with TranCIT: Transient Causal Interaction Toolbox analysis in just a few minutes.

We’ll cover the most common use cases with the class-based API, which provides clean interfaces and robust error handling.

Installation Check

First, verify your installation:

import trancit
print(f"TranCIT version: {trancit.__version__}")

If this works, you’re ready to go! If not, see the Installation guide.

Basic Causality Analysis

The simplest way to analyze causal relationships is using the DCSCalculator class:

import numpy as np
from trancit import DCSCalculator, generate_signals

# Generate synthetic bivariate time series data
data, _, _ = generate_signals(
    T=1000, Ntrial=20, h=0.1,
    gamma1=0.5, gamma2=0.5,
    Omega1=1.0, Omega2=1.2
)

print(f"Data shape: {data.shape}")  # (2, 1000, 20) = (variables, time, trials)

# Create DCS calculator
calculator = DCSCalculator(model_order=4, time_mode="inhomo")

# Perform analysis
result = calculator.analyze(data)

# Access results
print(f"Causal Strength shape: {result.causal_strength.shape}")
print(f"Transfer Entropy shape: {result.transfer_entropy.shape}")
print(f"Granger Causality shape: {result.granger_causality.shape}")

# Display mean causality values
print(f"Mean DCS (X→Y): {result.causal_strength[:, 0].mean():.4f}")
print(f"Mean DCS (Y→X): {result.causal_strength[:, 1].mean():.4f}")

Key Points:

• model_order=4: Number of time lags to include in the VAR model

• time_mode="inhomo": Use time-inhomogeneous analysis (recommended)

• Results contain causality measures with shape (n_time_points, 2) where column 0 is Y→X and column 1 is X→Y

Pipeline-Based Event Analysis

For event-based analysis (detecting and analyzing specific time windows), use the PipelineOrchestrator:

import numpy as np
from trancit import generate_signals, PipelineOrchestrator
from trancit.config import (
    PipelineConfig, PipelineOptions, DetectionParams,
    CausalParams, BicParams, OutputParams
)

# Generate synthetic data
data, _, _ = generate_signals(
    T=1200, Ntrial=20, h=0.1,
    gamma1=0.5, gamma2=0.5,
    Omega1=1.0, Omega2=1.2
)

# Prepare signals for pipeline
original_signal = np.mean(data, axis=2)  # Average across trials
detection_signal = original_signal * 1.5  # Amplify for event detection

# Configure the analysis pipeline
config = PipelineConfig(
    options=PipelineOptions(
        detection=True,           # Enable event detection
        bic=False,               # Skip BIC model selection (faster)
        causal_analysis=True,    # Enable causality analysis
        bootstrap=False,         # Skip bootstrap (faster)
        save_flag=False,         # Don't save intermediate results
        debiased_stats=False     # Skip debiased analysis
    ),
    detection=DetectionParams(
        thres_ratio=2.0,         # Detection threshold (higher = fewer events)
        align_type="peak",       # Align events to peaks
        l_extract=150,           # Length of extracted windows
        l_start=75,              # Start offset within windows
        remove_artif=True        # Remove artifact-contaminated trials
    ),
    causal=CausalParams(
        ref_time=75,             # Reference time for rDCS calculation
        estim_mode="OLS"         # Ordinary Least Squares estimation
    ),
    bic=BicParams(morder=4),
    output=OutputParams(file_keyword="quickstart_example")
)

# Run the analysis pipeline
orchestrator = PipelineOrchestrator(config)

try:
    result = orchestrator.run(original_signal, detection_signal)

    # Access results
    if result.results.get("CausalOutput"):
        causal_output = result.results["CausalOutput"]["OLS"]

        if "DCS" in causal_output:
            dcs_values = causal_output["DCS"]
            print(f"DCS shape: {dcs_values.shape}")
            print(f"Number of events detected: {dcs_values.shape[0]}")
            print(f"Mean DCS (X→Y): {dcs_values[:, 1].mean():.4f}")
            print(f"Mean DCS (Y→X): {dcs_values[:, 0].mean():.4f}")

        if "TE" in causal_output:
            te_values = causal_output["TE"]
            print(f"Mean TE (X→Y): {te_values[:, 1].mean():.4f}")
            print(f"Mean TE (Y→X): {te_values[:, 0].mean():.4f}")

        if "rDCS" in causal_output:
            rdcs_values = causal_output["rDCS"]
            print(f"Mean rDCS (X→Y): {rdcs_values[:, 1].mean():.4f}")
            print(f"Mean rDCS (Y→X): {rdcs_values[:, 0].mean():.4f}")
    else:
        print("No causal output generated - check signal characteristics")

except Exception as e:
    print(f"Pipeline analysis failed: {e}")
    print("Tip: Try adjusting thres_ratio or using simpler configuration")

Key Pipeline Components:

• Event Detection: Finds time windows of interest based on signal characteristics

• Snapshot Extraction: Extracts fixed-length windows around detected events

• Causality Analysis: Computes GC, TE, DCS, and rDCS for each event window

• Bootstrap Analysis: Optional statistical significance testing

Different Types of Analysis

DCS provides several specialized calculators for different causality measures:

from trancit import (
    DCSCalculator,              # Dynamic Causal Strength
    TransferEntropyCalculator,  # Information-theoretic measure
    GrangerCausalityCalculator, # Linear causality detection
    RelativeDCSCalculator       # Event-based relative causality
)

# Sample bivariate data
data = np.random.randn(2, 500, 15)

# 1. Dynamic Causal Strength Analysis
dcs_calc = DCSCalculator(model_order=3, time_mode="inhomo")
dcs_result = dcs_calc.analyze(data)
print(f"DCS computed for {dcs_result.causal_strength.shape[0]} time points")

# 2. Transfer Entropy Analysis
te_calc = TransferEntropyCalculator(model_order=3)
te_result = te_calc.analyze(data)
print(f"TE computed: {te_result.transfer_entropy.shape}")

# 3. Granger Causality Analysis
gc_calc = GrangerCausalityCalculator(model_order=3)
gc_result = gc_calc.analyze(data)
print(f"GC p-values shape: {gc_result.pvalues.shape}")

# 4. Relative DCS (requires event data and statistics)
# This is typically used within the pipeline, but can be used standalone
# rdcs_calc = RelativeDCSCalculator(model_order=3, reference_time=25)
# rdcs_result = rdcs_calc.analyze(event_data, event_stats)

Working with Real Data

Here’s how to apply DCS to your own time series data:

import numpy as np
from trancit import DCSCalculator
from trancit.utils.preprocess import normalize_data

# Load your data (example with NumPy)
# Your data should have shape (n_variables, n_timepoints, n_trials)
# For DCS: n_variables must be 2 (bivariate analysis)

# Example: loading data from a file
# data = np.load('my_time_series.npy')  # Shape should be (2, T, N)

# For demonstration, create sample data
np.random.seed(42)

# Simulate two coupled time series
T, N = 1000, 25  # 1000 time points, 25 trials

# Generate correlated signals (simple example)
noise1 = np.random.randn(T, N)
noise2 = np.random.randn(T, N)

signal1 = np.zeros((T, N))
signal2 = np.zeros((T, N))

# Create coupling: X influences Y with delay
for t in range(3, T):
    signal1[t] = 0.7 * signal1[t-1] - 0.1 * signal1[t-2] + noise1[t]
    signal2[t] = 0.6 * signal2[t-1] + 0.3 * signal1[t-3] + noise2[t]  # Y depends on past X

# Arrange in DCS format: (n_vars, n_time, n_trials)
data = np.array([signal1.T, signal2.T])

print(f"Data shape: {data.shape}")

# Optional: normalize your data
data_normalized = normalize_data(data, method="zscore", axis=1)

# Perform DCS analysis
calculator = DCSCalculator(model_order=5, time_mode="inhomo")

try:
    result = calculator.analyze(data_normalized)

    print("Analysis successful!")
    print(f"X→Y causality: {result.causal_strength[:, 1].mean():.4f}")
    print(f"Y→X causality: {result.causal_strength[:, 0].mean():.4f}")

    # Plot results (optional)
    try:
        import matplotlib.pyplot as plt

        plt.figure(figsize=(12, 4))
        plt.subplot(1, 2, 1)
        plt.plot(result.causal_strength[:, 1], label='X→Y', alpha=0.7)
        plt.plot(result.causal_strength[:, 0], label='Y→X', alpha=0.7)
        plt.xlabel('Time')
        plt.ylabel('Causal Strength')
        plt.legend()
        plt.title('Dynamic Causal Strength')

        plt.subplot(1, 2, 2)
        plt.plot(result.transfer_entropy[:, 1], label='X→Y', alpha=0.7)
        plt.plot(result.transfer_entropy[:, 0], label='Y→X', alpha=0.7)
        plt.xlabel('Time')
        plt.ylabel('Transfer Entropy')
        plt.legend()
        plt.title('Transfer Entropy')

        plt.tight_layout()
        plt.show()

    except ImportError:
        print("Install matplotlib to plot results: pip install matplotlib")

except Exception as e:
    print(f"Analysis failed: {e}")
    print("Check your data format and try adjusting model_order")

Common Troubleshooting

Issue: “Input data must be bivariate”

• DCS is designed for analyzing relationships between two time series

• Ensure your data has shape (2, n_timepoints, n_trials)

Issue: “Insufficient observations”

• Your time series is too short for the chosen model order

• Try reducing model_order or collecting more data

• Rule of thumb: need at least model_order * 10 time points

Issue: “Singular matrix errors”

• Your data may have perfect correlations or insufficient variation

• Try normalizing your data: normalize_data(data, method="zscore")

• Consider adding small amount of noise for numerical stability

Issue: Pipeline finds no events

• Your thres_ratio might be too high - try lowering it (e.g., 1.5 instead of 3.0)

• Check if your detection signal has sufficient variability

• Visualize your signal to understand its characteristics

What’s Next?

Now that you understand the basics:

• Explore Examples: Check out examples/basic_usage.py and examples/lfp_pipeline.py

• Read API Documentation: See API Reference for complete class and function references

• Learn Advanced Features: Check Examples for specialized use cases

• Understand the Science: Read about the theoretical background in our scientific paper

Configuration Tips:

• Start with model_order=3 or 4 for most applications

• Use time_mode="inhomo" for non-stationary signals (recommended)

• Enable bootstrap=True in pipeline for statistical significance testing

• Use BIC model selection for automatic model order selection

Need help? Check our ../TROUBLESHOOTING guide or open an issue on GitHub.