(c)2014 Ute Wibral

- 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, Viola Priesemann
Coypright (C) 2012, Michael Lindner, Raul Vicente, Michael Wibral, Nicu Pampu and Patricia Wollstadt, Viola Priesemann,  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)

Overview:  News, Roadmap, BUGS, Installation, Example

Current Status and News:

2014-07-24 TRENTOOL's GPU routines are being ported to OPENCL, to make users with non-nvidia hardware happy, too.

2014-06-13 Bugfix in the routines computing the embedding delay ('tau'). Please update to the latest verison 3.2.

2013-06-21 Thanks to the very hard work of Mario Martinez Zarzuela and Patricia Wollstadt a stable TRENTOOL version for the analysis of nonstatinary data via the ensemble method of Gomez-Herrero and Vicente (http://arxiv.org/abs/1008.0539) is available. Note that you will need a larger amount of trials than usual to make this work nicely (at least 150 trials of 100ms at 1.2kHz sampling rate is recommended). Due to the necessary changes in surrogate statistics for the ensemble method, this will  only run with GPU acceleration. The code for the next neighbour search on GPU was written by Mario in CUDA. When 'installing' TRENTOOL you will now have to run a little compiler script in MATLAB to compile the CUDA code for your card (if you want to use this functionality). To use it, you will need a CUDA capable graphics card. There is no need to heavily invest though as a gtx 580 should work (the algorithm uses single precision arithmetics for now, as this is what our EEGs and MEGs deliver in useful resolution anyway).
Downlaod the latest version (3.0) here.

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

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).
9. Compile the CUDA code if you want GPU acceleration by calling install.m from the MATLAB command line in the TERNTOOL folder. There is also a HOWTO.txt included.


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.