TRENTOOL

- the Transfer Entropy Toolbox for the Fieldtrip data format.
Coypright (C) 2009, Michael Lindner, Raul Vicente and Michael Wibral
Coypright (C) 2012, Michael Lindner, Raul Vicente, Michael Wibral, Nicu Pampu and Patricia Wollstadt
Coypright (C) 2012, Michael Lindner, Raul Vicente, Michael Wibral, Nicu Pampu and Patricia Wollstadt, Mario Martinez-Zarzuela

TRENTOOL acknowledges the support of :
Research Grant LOEWE-NeFF 'Neuronale Koordination Forschungsschwerpunkt Frankfurt' (MW,RV,NP, MMZ)

TRENTOOL is distributed under the GNU public license version 3 (or later)

A version for the analysis of nonstatinary data via the ensemble method is available. Contact us for code.
Download the latest version (2.0.6.b) here. This version adds support for MATLAB parallel computing toolbox. The previous version added version adds support for reconstructing interaction delays from the data (functions starting with InteractionDelayReconstruction_...) by means of a new transfer entropy estimator ( called 'VW_ds' which also the default from now on, see HELP TEprepare) and for using them to prune spurious interactions from the graph. It also adds binomial second-level statistics to check evidence for the existence of interactions at the group-level. Other goodies to come with future 2.x vesrions will be support for the matlab parallel computing toolbox and CUDA parallel computing for nearest neighbour search.
Download the last version of the 1.x branch (1.0.3) of the toolbox (NOTE: by downloading you accept the terms of the GPL v3 license) here. Note: This update is absolutely necessary when working with the cfg.sgncmb option, i.e. when working with channelcombinations instead of channels and all-to-all analyses !!
A diagram of the dataflow between the different modules of the toolbox can be downloaded here.
A small simulation and plotting tool was kindly provided by Felix Siebenhuehner and can be downloaded here. (NOTE: by downloading you accept the terms of the GPL v3 license). As usual the code comes as is and without any warranty.
We appreciate any kind of feedback: suggestions for features, usability improvements, crash reports etc.,!

Overview: News, Roadmap, BUGS, Installation, Example

Current Status and News:
2013-04-02 Analysis of non-stationary time series is now possible: New routines for the ensemble approach suggest by Gomez-Herrero and Raul Vicente (here), have been implemented together with the corresponding statistical tools by Mario Martinez Zarzuela and Patricia Wollstadt. You will need a CUDA-capable GPU (e.g. gtx580 is fine) to run this code. Contact us via email for a beta version of the code.

2012-12-18 Support for the MATLAB paralle computing toolbox added - see the header of TEsurrogatestats.m for help on the new options in the configuration (cfg).

2012-08-30 Presentation at EBMC 2012 San Diego on the model-free reconstruction of interaction delays with transfer entropy. A paper in the conference proceedings should appear soon. Another paper detailing the mathematical theory behind delay reconstruction with transfer entropy was submitted.

2012-07-04 Thanks to the work of Nicu Pampu and Patricia Wollstadt, version 2.0.3 adds the possibility to reconstruct the delays of interactions and to use these reconstructed interaction delays to mark potentially spurious interactions in the graph (cascade effects, common drive effects). Moreover second-level binomial statistics have been added to check for the existence of a direcetd interaction (at the group level).

2012-05-07 Updated the example script below with a comment demonstrating how to use cfg.sgncmb to analyze only specific signal combinations (which might save a lot of time, if one is only interested in these).

2012-04-30 The TRENTOOL course seems to have been a great success. Please find the course slides here. The new version (2.0.0) is available for download (see above). There are also the Course materials. Note that these examples run if you set the paths in the scripts accordingly, and they run only on Matlab 2008b or higher and only on Linux 64 bit machines (Win and Mac users will have get other variants of the TSTool toolbox (see Installation below)).

2012-02-17 Two new developers joined the TRENTOOL team. We officially welcome Nicu Pampu from the Coneural Institute in Kluj-Napoca, Rumania and Patricia Wollstadt from Goethe University Frankfurt as new developers. Nicu has ported TRENTOOL to MATLAB's parallel computing toolbox, and will look into CUDA support. Patricia is working on graph-theoretical extesion to the toolbox. These changes will be available upon release of TRENTOOL2. Beta-testers may contact michael.wibral <AT> web.de.

2012-02-17 TRENTOOL course announcement. Togther with the NeFF Symposium on "Non-linear and model-free measures of directed interactions in neuroscience" there will be a two-afternoon course for TRENTOOL users. Reistration fee for course and symposium will be 50 EUR. To apply send an email to michael.wibral <at> web.de.

2012-02-17 A new experimental version of TRENTOOL2 is available which offers better organisation of the code and additional features, including experiemntal support for MATLABs parallel computing toolbox. Please send an email to michael.wibral <at> web.de if you are interested in beta-testing.

2011-11-04 The paper on TRENTOOL was published in BMC Neuroscience (they publish software-papers which is great and they're open access which is an added plus), find the provisional pdf here.

2011-08-17 Nico Pampu from the Coneural Center for Cognitive and Neural Studies pointed out that TRENTOOL at the moment can only handle trials that are all equal length - as opposed to Fieldtrip code that can in many processing stages also handle variable length trials. Using variable length trials would mean using variable time--of-interest windows as well - which might require a large rework of the software. At the moment all we can offer is to check for equal length trials and report an error for variable length trials. This will be done in the next bugfix.

2011-08-04 A poster detailing the motivation for using trentool and its special merits was persented at the annual meeting of the Orgnaisation for Computational Neuroscience (OCNS) in Stockholm. download poster

2011-08-04 BUGFIX release TRENTOOL 1.0.1. This bugfix release adresses a problem that was encountered when only a subset of channels in the dataset was used in cfg.channel in combibnation with the Ragwitz criterion.

2011-06-13 Felix Siebenhühner contributed a small tool to simulate batches of coupled AR processes with linear, quadratic, threshold and mmodulatory/multtiplicatory coupling (Thanks Felix!).
Apart from simulating data, the toolbox does some simple descriptive statistics and graphs for the batched simulations and TE analyses: true positive rate, false positive, number of times volume conduction, instantaneous causality was found ...
You can download the MATLAB code here. (NOTE: by downloading you accept the terms of the GPL v3 license). As usual the code comes as is and without any warranty.

2011-05-25 First release version of TRENTOOL (1.0) accompanies the submission of a paper on the use of the toolbox (send an email michael.wibral<at>web.de for preprint). Added some changes to the installation instruction.

2011-01-19 Fixed a bug in the Ragwitz criterion that caused occsaional chrashes.

2011-01-12 Added a download link for the toolbox. Note that it is still advised to contact michael.wibral<at>web.de before installation.

2010-11-30
Added installation instructions and a short example script - see bottom of this page.

2010-11-18
A paper using TRENTOOL demonstrating the analysis of cortical and cerebellar networks at the MEG source level has been accpepted for publication in 'Progress in Biophysics and Molecular Biology / Special issue: Brain Modes'.

2010-07-27
A first paper using TRENTOOL has been accpeted in Journal of Computational Neuroscience (open access link).

Future Plans

We will introduce a normalized variant of TE for group analysis.
We are working on porting the neighbour search to GPU (cuda)
We will implement Vicente's ensemble method (see open access article on arXiv)

BUGS:
Status: open

Status: closed
2012-07-25 Version2.0.3 TRENTOOL does not check whther the number of available trials is sufficient for the requested permutations statistics. As a workaround use cfg. minnrtrials = ... to set the number of trials needed for reasonable permutation statistics.

2012-09-05 Version 2.0.3 and earlier - bug in determination of the statistical threshold for one-tailed permutation testing produced overyl conservative results.
Please update to version 2.0.4

2011-09-26 Version 1.0.1 - problems with cfg.sgncmb trying to access nr(trials) produces indices that are out of range
Please update to version 1.0.2.

2011-08-23 Version 1.0.1 - Problems with access of MEX files on certain 32 bit archtictures
When you have problems running the open TSTool MEX files for your 32 bit architecture, please update to version 1.0.1a or later

2011-07-20 Version 1.0 - Crash when using channels selection via cfg.channel together with the ragwitz criterion
When using the ragwitz criterion and only a subset of all available channels that are combined into channel combinations by TRENTOOL (i.e. you do not use cfg.sgncmb explicitely, but rather cfg.channel) a wrong matrix of autocorrelation time gets computed (for all channels instead of the used ones) and its size causes a chrash in TEprepare around line 470.
WORKAROUND: (a) use all channels of your dataset (works) (b) give an explicit cfg.sgncmb (unknown) (c) prepare a dataset that only contains the desired channels (works) (d) use the cao criterion instead (works)

Installation instruction
1. Get the open source MATLAB(R) toolbox TSTool for your architecture (!) from the Juelich Group (http://www.physik3.gwdg.de/tstool/) and unpack.
2. Get a current version of the open source MATLAB(R) toolbox Fieldtrip from the Donders Centre (http://fieldtrip.fcdonders.nl/) and unpack.
3. Get TRENTOOL.
4. Put the top folder of TRENTOOL in the MATLAB path.
5. Put the top folder of Fieldtrip in the MATLAB path.
6. ( Do not touch the MATLAB path after this - everything else will be handled from inside Fieldtrip and TRENTOOL).
7. Always run the command ft_defaults; at the beginning of your matlab session or the beginning of your analysis script.
8. DO NOT put TSTool in your MATLAB path !! Instead in your script specify the path to TStools via: cfg.Path2TSTOOL = '/your/path/goes/here/OpenTSTOOL_v1-2'; (this avoid all kinds of nasty problems with mex files on different architectures).

A short example script
filedtripdefs;

% load the data
    load(datafilename)); % say this contains the variable "data"

    %%% TE prepare settings %%%
    cfg=[];
    cfg.optimizemethod='cao'; % select the CAO method to estimate embedding dimensions
    cfg.toi = [-0.85 0.05]; % the time interval of interest in secs
    cfg.predicttime_u = 32; % the prediction time im ms (e.g. the axonal delay; always choose bigger values when in doubt - also see the Vicente, 2010 paper)
    cfg.channel = data.label; % a cell array with the names of the channles you want to analyze. here all cahnnels in the dataset are analyzed
    % Alternative: use cfg.sgncmb to just analyze specific signal combinations e.g. from a channel named channel1 to a channel named channel101,
    % and from a channel named channelA to a channel named channelB :
    % cfg.sgncmb={'channel1', 'channel101';
    % 'channelA', 'channelB'}
    cfg.caodim = 1:8; % check dimensions between 1 and 8;
    cfg.caokth_neighbors = 3;
    cfg.actthrvalue=120; % Do not accpet trials that have a longer autocorrelation decay time (ACT) than this (helps to avoid 'out of data' errors)
    cfg.minnrtrials=10; % abort calculations if we do not have a least this number of trials with acceptable ACT
    cfg.Path2TSTOOL = '/data/common/OpenTSTOOL_v1-2'; % the path where you unpacked the TStool toolbox
    cfg.feedback = 'no'; % ...
    data=TEprepare(cfg,data); % the actual command that prepares the data for subsequent TE analysis

    %%% stats section %%%
    cfg = [];
    cfg.surrogatetype = 'trialshuffling'; % the type of surrogates that are created for significance testing
    cfg.shifttesttype='TEshift>TE'; % the type of shift test that is used (Vicente, J Comp Neursci, 2010 and Wibral, Prog Biophys Mol Biol, 2010)
    cfg.fileidout = strcat('My_prefix_'); % a prefix for the results filename
    TEsurrogatestats(cfg,data); % the actual command that computes transfer entropy for the original data, the surrogate data, and the shifttest data and that performs the statistical test.