TimeAwarePC: A Python Package for Finding Causal Connectivity from Time Series Data

TimeAwarePC is a Python package that implements the Time-Aware PC Algorithm for finding the Causal Functional Connectivity from time series data, based on recent research in directed probabilistic graphical modeling with time series [1]. The package also includes implementations of Granger Causality and the PC algorithm.

Installation

Recommended: conda environment (handles R + kpcalg automatically)

$ git clone https://github.com/shlizee/TimeAwarePC.git
$ cd TimeAwarePC
$ conda env create -f environment.yml
$ conda activate timeawarepc
$ Rscript install_r_deps.R   # installs kpcalg from CRAN archive

This installs Python, R, rpy2, all required R packages (graph, RBGL, pcalg), and TimeAwarePC v2.0.0 in a single isolated environment.

Manual install (alternative)

If you prefer to install without conda:

• Python >=3.9, <3.11
• R >= 4.0
• R package kpcalg and its dependencies, installed via R or RStudio:

> install.packages("BiocManager")
> BiocManager::install("graph")
> BiocManager::install("RBGL")
> install.packages("pcalg")
> install.packages("https://cran.r-project.org/src/contrib/Archive/kpcalg/kpcalg_1.0.1.tar.gz")

• Then:

$ pip install timeawarepc

To use Granger Causality, also install nitime (pip install nitime).

Documentation

Documentation is available at readthedocs.org

Tutorial

See the Quick Start Guide for a quick tutorial of the main functionalities of this library and check if it is installed properly.

What's new in v2.0.0

• cfc_tpc now defaults to no bootstrap subsampling: a single PC run is performed on the full time-delayed data.
  • To use bootstrap stability scoring, pass subsampsize and niter together (e.g., subsampsize=50, niter=25).
  • Both arguments must be specified together (or both left as the default None).
• partial_corr now fits an intercept and is shift-invariant. Previously the regression was forced through the origin, biasing residuals when the data was not mean-centered.
• See CHANGELOG.md for the full list of changes and migration notes.

Contributing

Your help is absolutely welcome! Please do reach out or create a feature branch!

Citation

Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://doi.org/10.1371/journal.pcbi.1010653

Biswas, R., & Shlizerman, E. (2021). Statistical Perspective on Functional and Causal Neural Connectomics: A Comparative Study. Frontiers in Systems Neuroscience. https://doi.org/10.3389/fnsys.2022.817962

References

R Clay Reid. (2012) From functional architecture to functional connectomics. Neuron, 75(2):209–217.

Smith, S. M., Miller, K. L., Salimi-Khorshidi, G., Webster, M., Beckmann, C. F., Nichols, T. E., ... & Woolrich, M. W. (2011). Network modelling methods for FMRI. Neuroimage, 54(2), 875-891.

Judea Pearl. (2009) Causality. Cambridge University press.

Markus Kalisch and Peter Bhlmann. (2007) Estimating high-dimensional directed acyclic graphs with the pc-algorithm. In The Journal of Machine Learning Research, Vol. 8, pp. 613-636.

Peter Spirtes, Clark N Glymour, Richard Scheines, and David Heckerman. (2000) Causation, prediction, and search. MIT press.