Welcome to the IDTxl wiki!

For more details read the Installation and Requirements page.

If you want to cite IDTxl in your publication, please use

P. Wollstadt, J. T. Lizier, R. Vicente, C. Finn, M. Martinez-Zarzuela, P. Mediano, L. Novelli, M. Wibral (2019). IDTxl: The Information Dynamics Toolkit xl: a Python package for the efficient analysis of multivariate information dynamics in networks. Journal of Open Source Software, 4(34), 1081. https://doi.org/10.21105/joss.01081

Also have a look at a list of Publications using IDTxl.

You can test your installation of IDTxl and run your first Information Network Inference on a small simulated dataset.

# Import classes
from idtxl.multivariate_te import MultivariateTE
from idtxl.data import Data
from idtxl.visualise_graph import plot_network
import matplotlib.pyplot as plt

# a) Generate test data
data = Data()
data.generate_mute_data(n_samples=1000, n_replications=5)

# b) Initialise analysis object and define settings
network_analysis = MultivariateTE()
settings = {'cmi_estimator': 'JidtGaussianCMI',
            'max_lag_sources': 5,
            'min_lag_sources': 1}

# c) Run analysis
results = network_analysis.analyse_network(settings=settings, data=data)

# d) Plot inferred network to console and via matplotlib
results.print_edge_list(weights='max_te_lag', fdr=False)
plot_network(results=results, weights='max_te_lag', fdr=False)
plt.show()

In order to run a meaningful analysis on your dataset, make sure you understand the key theoretical concepts underlying IDTxl algorithms. To learn more about the data class, analysis settings, and the output format, have a look at the Tutorials Section as well as the full Documentation.

Multivariate transfer entropy (mTE) is an extension of transfer entropy (TE), a directed measure of information transfer between a source and a target process, introduced by Thomas Schreiber (2000, Phys. Rev. Lett., see also Bossomaier, 2016). Schreiber formulated the TE for the bivariate case, i.e., between a single source and a single target. In a multivariate setting, however, bivariate analysis may lead to false positive or false negative results. In particular:

• bivariate analysis may infer spurious or redundant interactions, where multiple sources provide the same information about the target;
• bivariate analysis may miss synergistic interactions between multiple relevant sources and the target, where these multiple sources jointly transfer more information into the target than what could be detected from examining source contributions individually.

Hence, tools for multivariate TE estimation are required to account for all relevant sources of a target. Yet, an exhaustive multivariate approach is computationally intractable, even for a small number of potential sources in the data. Thus, a suitable approximation algorithm is needed.

IDTxl implements a greedy, iterative algorithm for mTE estimation that has been proposed individually by Lizier (2012, Max Planck Preprint No. 25) and Faes (2011, Phys. Rev. E). The algorithm infers all relevant sources of a target by iteratively including variables from a source's past that maximise a conditional mutual information criterion. IDTxl thus builds the set of parent sources for each target node in the network (Lizier, 2012, Max Planck Preprint No. 25; Faes, 2011, Phys. Rev. E). This iterative conditioning is designed to both remove redundancies and capture synergistic interactions in building each parent set, thus addressing the two aforementioned shortcomings of bivariate analysis. The inclusion of source variables requires repeated statistical testing of each investigated past variable in each iteration. IDTxl handles this multiple testing, in particular the family-wise error rate (FWER), by implementing a so-called maximum statistic test. Further statistical tests are aimed at pruning the selected parent set and providing control of the FMER also at the network level (see below). At the same time, IDTxl automates the optimization of parameters necessary for the estimation of mTE.

We encourage you to read our short theoretical introduction.

If you are looking for a full and detailed picture of the theoretical background, refer to the Literature.

For theoretical run times and some benchmarks, refer to the Runtimes and Benchmarking page.

• Demo scripts
  • Multivariate Transfer Entropy / Granger causality
  • Bivariate TE / Granger causality
  • Multivariate mutual information
  • Bivariate mutual information
  • MPI-supported (C)MI-estimation with SLURM script
• Details
  1. Import data
     • The Data Class
  2. Define analysis settings
     • CMI estimators
     • Source and target lags
     • Statistical significance tests
     • Strategies for Generating Surrogate Data
     • Conditioning on specific variables
  3. Run analysis
     • Single target analysis
     • Whole network analysis
     • Parallel analysis on a computing cluster using PBS
     • Parallel analysis using MPI
     • Combine single target results
     • The Results class
  4. Plot and export inferred network
     • Plot inferred networks
     • Export results as networkx graph object or as input to Brain Net Viewer
  5. Statistical comparison of inferred networks
     • Compare (sets of) inferred networks
     • Compare individual links within the same network
     • Visualization of comparison results

• Demo scripts
  • Active Information Storage
  • Bivariate partial Information decomposition (BROJA estimator)
  • Multivariate partial Information decomposition (SxPID estimator)
  • History-dependence estimator
• Details: Active Information Storage
  1. Import data
     • The Data class
  2. Define analysis settings
     • CMI estimators
     • Maximum lag
     • Statistical significance tests
  3. Run analysis
     • Single process analysis
     • Whole network analysis
     • The Results Class
• Details: Partial Information Decomposition
  1. Import data
     • The Data class
  2. Define analysis settings
     • Lags
     • PID estimators
  3. Run analysis
     • Single target analysis
     • Whole network analysis
     • The Results Class
• Details: History-dependence estimator (HDE) for neural spiking data
  1. Installation
  2. Import data
     • The Spiketime Data class
  3. Define analysis settings
  4. Run analysis

IDTxl's core estimators (for mutual information, partial information decomposition, etc.) may be accessed directly, i.e., independently of the network inference algorithms:

• General usage

• MATLAB importer
• FieldTrip importer
• Export networkx graph object
• Export to BrainNet viewer
• Visualise inferred networks
• Generate Synthetic Test Data
  • MuTE network
  • Coupled Autoregressive processes
  • Coupled Logistic maps

Refer to the Documentation for class structure, methods and parameters.

• Contributing to IDTxl
• Install IDTxl in editable mode
• Testing
• Adding a new estimator to IDTxl

• How to auto-generate class diagrams

• Setting up virtual environments on Ubuntu 14.04