Tigramite

Tigramite is a python package for causal inference with a focus on time series data. It allows to efficiently estimate causal graphs from high-dimensional time series datasets (causal discovery) and to use graphs for the estimation and prediction of direct, total, and mediated effects.

2
mentions
1
contributor

Cite this software

What Tigramite can do for you

Tigramite – Causal inference for time series datasets

logo Version 5.2 (Python Package)

Github

Documentation

Tutorials

Overview

It's best to start with our Overview/review paper: Causal inference for time series

Update: Tigramite now has a new CausalEffects class that allows to estimate (conditional) causal effects and mediation based on assuming a causal graph. Have a look at the tutorial.

Further, Tigramite provides several causal discovery methods that can be used under different sets of assumptions. An application always consists of a method and a chosen conditional independence test, e.g. PCMCIplus together with ParCorr. The following two tables give an overview of the assumptions involved:

MethodAssumptionsOutput
(in addition to Causal Markov Condition and Faithfulness)
PCMCICausal stationarity, no contemporaneous causal links, no hidden variablesDirected lagged links, undirected contemporaneous links (for tau_min=0)
PCMCIplusCausal stationarity, no hidden variablesDirected lagged links, directed and undirected contemp. links (Time series CPDAG)
LPCMCICausal stationarityTime series PAG
RPCMCINo contemporaneous causal links, no hidden variablesRegime-variable and causal graphs for each regime with directed lagged links, undirected contemporaneous links (for tau_min=0)
J-PCMCI+Multiple datasets, causal stationarity, no hidden system confounding, except if context-relatedDirected lagged links, directed and undirected contemp. links (Joint time series CPDAG)
Conditional independence testAssumptions
ParCorrunivariate, continuous variables with linear dependencies and Gaussian noise
RobustParCorrunivariate, continuous variables with linear dependencies, robust for different marginal distributions
ParCorrWLSunivariate, continuous variables with linear dependencies, can account for heteroskedastic data
GPDC / GPDCtorchunivariate, continuous variables with additive dependencies
CMIknnmultivariate, continuous variables with more general dependencies (permutation-based test)
Gsquaredunivariate discrete/categorical variables
CMIsymbmultivariate discrete/categorical variables (permutation-based test)
RegressionCImixed datasets with univariate discrete/categorical and (linear) continuous variables

Remark: With the conditional independence test wrapper class PairwiseMultCI you can turn every univariate test into a multivariate test.

General Notes

Tigramite is a causal inference for time series python package. It allows to efficiently estimate causal graphs from high-dimensional time series datasets (causal discovery) and to use graphs for robust forecasting and the estimation and prediction of direct, total, and mediated effects. Causal discovery is based on linear as well as non-parametric conditional independence tests applicable to discrete or continuously-valued time series. Also includes functions for high-quality plots of the results. Please cite the following papers depending on which method you use:

Features

  • flexible conditional independence test statistics adapted to continuously-valued, discrete and mixed data, and different assumptions about linear or nonlinear dependencies
  • handling of missing values and masks
  • p-value correction and (bootstrap) confidence interval estimation
  • causal effect class to non-parametrically estimate (conditional) causal effects and also linear mediated causal effects
  • prediction class based on sklearn models including causal feature selection

Required python packages

  • python=3.7/3.8/3.9/3.10
  • numpy <1.24,>=1.18
  • scipy>=1.10.0
  • numba==0.56.4

Optional packages depending on used functions

  • scikit-learn>=1.2 # Gaussian Process (GP) Regression
  • matplotlib>=3.7.0 # Plotting
  • seaborn>=0.12.2 # Plotting
  • networkx>=3.0 # Plotting
  • torch>=1.13.1 # GPDC pytorch version (in conda install pytorch)
  • gpytorch>=1.9.1 # GPDC gpytorch version
  • dcor>=0.6 # GPDC distance correlation version
  • joblib>=1.2.0 # CMIsymb shuffle parallelization
  • ortools>=9.2 # RPCMCI

Installation

python setup.py install

This will install tigramite in your path.

To use just the ParCorr, CMIknn, and CMIsymb independence tests, only numpy/numba and scipy are required. For other independence tests more packages are required:

  • GPDC: scikit-learn is required for Gaussian Process regression and dcor for distance correlation

  • GPDCtorch: gpytorch is required for Gaussian Process regression

Note: Due to incompatibility issues between numba and numpy, we currently enforce soft dependencies on the versions.

User Agreement

By downloading TIGRAMITE you agree with the following points: TIGRAMITE is provided without any warranty or conditions of any kind. We assume no responsibility for errors or omissions in the results and interpretations following from application of TIGRAMITE.

You commit to cite above papers in your reports or publications.

License

Copyright (C) 2014-2023 Jakob Runge

See license.txt for full text.

GNU General Public License v3.0

TIGRAMITE is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. TIGRAMITE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Logo of Tigramite
Keywords
Programming languages
  • Jupyter Notebook 86%
  • Python 14%
License
  • GPL-3.0-or-later
</>Source code

Participating organisations

German Aerospace Center (DLR)
Technical University of Berlin

Mentions

Contributors

JR
Jakob Runge
Maintainer
German Aerospace Center and TU Berlin