Home

Welcome to the IDTxl wiki!

Installation

For more details read the Installation and Requirements page.

Citation

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.

Your first Information Network Inference with 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.

Theoretical background

Why multivariate transfer entropy estimation?

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.

Want to know more?

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.

Tutorials

Algorithms for network inference

Demo scripts
Details
1. Import data
  - The Data Class
2. Define analysis settings
3. Run analysis
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

Algorithms for node dynamics

Demo scripts
Details: Active Information Storage
1. Import data
  - The Data class
2. Define analysis settings
3. Run analysis
Details: Partial Information Decomposition
1. Import data
  - The Data class
2. Define analysis settings
  - Lags
  - PID estimators
3. Run analysis
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

Core estimators

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