Home

Welcome to the IDTxl wiki!

Installation

For more details read the Installation and Requirements page.

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 print_res_to_console, plot_network

# 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
print_res_to_console(data=data, res=results)
plot_network(res=results, n_nodes=data.n_processes)

In order to run a meaningful analysis on your dataset, make sure you understand the key theoretical concepts underlying IDTxl algorithms.

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 the short theoretical introduction.

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

Tutorials

• Algorithms for network inference

  • Multivariate Transfer Entropy / Granger causality

    1. Import data
       • The Data Class
    2. Define analysis settings
       • CMI Estimators
       • Source and Target Lags
       • Statistical Significance Tests
       • Conditioning on specific variables
    3. Run analysis
       • Single Target analysis
       • Whole Network analysis
       • Results Dictionary
    4. Plot inferred network
       • networkx interface

  • Bivariate TE / Granger causality

• Algorithms for node dynamics

  • Active Information Storage
  • Entropy

• Core estimators

  • General usage

• Input/Output

  • MATLAB importer
  • FieldTrip importer
  • Neo importer
  • Export networkx graph object
  • Export to BrainNet viewer

• Generate Synthetic Test Data

  • Coupled Autoregressive processes
  • MuTE network
  • Coupled Logistic maps

Documentation

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

Developer's section

• Testing
• Package IDTXL
• Adding a new estimator to IDTxl
• Generate UML structure
• List of variable names

Misc

• Setting up virtual environments on Ubuntu 14.04