TranCIT: Transient Causal Interaction Toolbox

TranCIT (Transient Causal Interaction Toolbox) is a Python package for quantifying causal relationships in multivariate time series data. It provides methods for analyzing directional influences using model-based statistical tools, inspired by information-theoretic and autoregressive frameworks.

🚀 Features

• Dynamic Causal Strength (DCS): Time-varying causal relationships
• Transfer Entropy (TE): Information-theoretic causality measures
• Granger Causality (GC): Linear causality detection
• Relative Dynamic Causal Strength (rDCS): Event-based causality
• VAR-based Modeling: Vector autoregressive time series analysis
• BIC Model Selection: Automatic model order selection
• Bootstrap Support: Statistical significance testing
• DeSnap Analysis: Debiased statistical analysis
• Pipeline Architecture: Modular, stage-based analysis pipeline

📦 Installation

From PyPI (Recommended)

bash pip install trancit

From Source

bash git clone https://github.com/CMC-lab/TranCIT.git cd TranCIT pip install -e .

Development Installation

bash git clone https://github.com/CMC-lab/TranCIT.git cd TranCIT pip install -e ".[dev]"

🎯 Quick Start

Basic Causality Analysis

```python import numpy as np from trancit import DCSCalculator, generate_signals

Generate synthetic data

data, , _ = generatesignals(T=1000, Ntrial=20, h=0.1, gamma1=0.5, gamma2=0.5, Omega1=1.0, Omega2=1.2)

Create DCS calculator

calculator = DCSCalculator(modelorder=4, timemode="inhomo")

Perform analysis

result = calculator.analyze(data) print(f"DCS shape: {result.causalstrength.shape}") print(f"Transfer Entropy shape: {result.transferentropy.shape}") ```

Event-Based Analysis Pipeline

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

Generate data

data, , _ = generatesignals(T=1200, Ntrial=20, h=0.1, gamma1=0.5, gamma2=0.5, Omega1=1.0, Omega2=1.2) original_signal = np.mean(data, axis=2)

Create detection signal: use second variable which often has clearer peaks

The detection signal must be 2D with shape (2, T)

detectionvar = originalsignal[1, :] detectionsignal = np.vstack([detectionvar, detection_var])

Configure pipeline

config = PipelineConfig( options=PipelineOptions(detection=True, causalanalysis=True), detection=DetectionParams(thresratio=1.2, aligntype="peak", lextract=150, lstart=75), bic=BicParams(morder=4), causal=CausalParams(reftime=75, estimmode="OLS"), output=OutputParams(filekeyword="example"), )

Run analysis

orchestrator = PipelineOrchestrator(config) try: result = orchestrator.run(originalsignal, detectionsignal)

Access results

if result.results.get("CausalOutput"): dcsvalues = result.results["CausalOutput"]["OLS"]["DCS"] tevalues = result.results["CausalOutput"]["OLS"]["TE"] print(f"DCS shape: {dcsvalues.shape}") else: print("No events detected. Try adjusting thresratio or use real data.") except Exception as e: print(f"Pipeline failed: {e}") print("Note: Event detection may fail with synthetic data. ") print("For reliable results, use real data or adjust detection parameters.") ```

VAR Model Estimation

```python import numpy as np from trancit import VAREstimator

Generate sample data

data = np.random.randn(2, 1000, 20) # (nvars, nobs, n_trials)

VAR estimation

estimator = VAREstimator(modelorder=4, timemode="inhomo") coefficients, residuals, loglikelihood, hessiansum = ( estimator.estimatevarcoefficients( data, modelorder=4, maxmodelorder=6, timemode="inhomo", lag_mode="infocrit" ) )

print(f"Coefficients shape: {coefficients.shape}") print(f"Log-likelihood: {log_likelihood:.4f}") ```

Controlling Logging Verbosity

By default, TranCIT uses INFO-level logging, which provides detailed progress information during analysis. If you find the logging output too verbose for your use case, you can reduce it:

```python import logging

Reduce logging to show only warnings and errors

logging.getLogger("trancit").setLevel(logging.WARNING)

Or set to ERROR for minimal output

logging.getLogger("trancit").setLevel(logging.ERROR)

For more detail, use DEBUG

logging.getLogger("trancit").setLevel(logging.DEBUG) ```

Note: The examples above will show INFO-level logging by default. To reduce verbosity, add the logging configuration at the beginning of your script. For debugging purposes, you can increase verbosity using logging.DEBUG.

📚 Documentation & Examples

For comprehensive documentation, tutorials, and API reference:

👉 ReadTheDocs Documentation

Examples

• Basic Usage: Simple causality analysis
• CA3-CA1 Causality Analysis: Local field potential causality analysis
• DCS Introduction: Interactive tutorial

🔬 Scientific Background

This package implements methods from:

• Shao et al. (2023): Information theoretic measures of causal influences during transient neural events
• Granger Causality: Linear causality detection in time series
• Transfer Entropy: Information-theoretic causality measures

🧪 Testing

```bash

Run all tests

pytest

Run with coverage

pytest --cov=trancit --cov-report=html

Run linting

flake8 trancit/ tests/

Format code

black trancit/ tests/ ```

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

bash git clone https://github.com/CMC-lab/TranCIT.git cd TranCIT pip install -e ".[dev]" pre-commit install

📖 Citing This Work

If you use TranCIT in your research, please cite:

```bibtex @article{shao2023information, title={Information theoretic measures of causal influences during transient neural events}, author={Shao, Kaidi and Logothetis, Nikos K and Besserve, Michel}, journal={Frontiers in Network Physiology}, volume={3}, pages={1085347}, year={2023}, publisher={Frontiers Media SA} }

@article{nouri2025trancit, title={TranCIT: Transient Causal Interaction Toolbox},
author={Nouri, Salar and Shao, Kaidi and Safavi, Shervin}, year={2025}, journal={arXiv preprint arXiv:2509.00602}, url={https://doi.org/10.48550/arXiv.2509.00602} } ```

And cite this software package:

bibtex @software{nouri_2025_trancit, author = {Nouri, Salar and Shao, Kaidi and Safavi, Shervin}, title = {TranCIT: Transient Causal Interaction Toolbox}, month = aug, year = 2025, publisher = {Zenodo}, doi = {10.5281/zenodo.16998396}, url = {https://doi.org/10.5281/zenodo.16998396}, }

📄 License

This project is licensed under the BSD 2-Clause License. See the LICENSE file for details.

🙏 Acknowledgments

• Based on research from the CMC-Lab
• Inspired by information-theoretic causality methods
• Built with support from the scientific Python community

📞 Contact

• Maintainer: Salar Nouri (salr.nouri@gmail.com)
• Issues: GitHub Issues
• Documentation: ReadTheDocs