2
Contents
1. Introduction 4
1.1. The toolbox 4
2. Demonstration 6
2.1. Time-domain G-causality 6
2.2. Frequency-domain G-causality 9
3. Data suitability, validation, and preprocessing 12
3.1. Covariance stationarity 12
3.2. Detrending and demeaning 13
3.3. Differencing 14
3.4. Windowing 15
3.5. Selecting the model order 15
4. G-causality analysis 18
4.1. Conditional G-causality 18
4.2. Multiple realization G-causality 20
4.3. Spectral G-causality 20
4.4. Partial G-causality 21
4.5. Granger autonomy 21
4.6. Model validity 22
5. Causal network statistics and visualization 24
5.1. Causal density 24
5.2. Causal flow 25
5.3. Plotting causal networks 25
6. Filtering 28
6.1. Bandpass filtering 28
6.2. Multi-taper and notch filtering 29
6.3. Filtering and model order 31
7. Bootstrap and permutation resampling 32
7.1. Bootstrap resampling 32
7.2. Permutation resampling 33
7.3. Demonstration 34
3
8. Additional resources 34
9. Limitations 34
Acknowledgements 36
Appendix A. Modifications from v1.x 36
References 37
4
1. Introduction
This toolbox provides an array of MATLAB (Mathworks, Natick, MA) functions for
evaluating the causal connectivity in the dynamics of a set of variables, for calculating
various statistical descriptors of causal connectivity, and for displaying the results in
graphical form. It is a substantially upgraded version of a previous MATLAB toolbox
first released in 2005 (Seth, 2005). The primary reference for the present toolbox is
Seth, A.K. (2010). A MATLAB toolbox for Granger causal connectivity analysis.
Journal of Neuroscience Methods 186:262-273
which should be cited whenever this toolbox is used.
The toolbox is based on ‘Granger-causality’ (G-causality) which implements a statistical
interpretation of causality in which A ‘Granger causes’ B if knowing the past of A can
help predict B, better than knowing the past of B alone (Ding, Chen, & Bressler, 2006;
Granger, 1969; Seth, 2007a). The standard implementation of G-causality is via vector
autoregressive (MVAR) modeling, in which a set of time series are modeled as weighted
sums of past values. This is the implementation underlying the present toolbox.
The main objective of the toolbox is to provide exploratory tools for general purpose G-
causality analysis which can be assimilated and deployed quickly, with minimal self-
training, by any reasonably competent MATLAB programmer. There is no graphical
user interface.
Comments, bug-fixes, and proposed enhancements are always welcome. There is a ‘wiki’
site for sharing experiences with the toolbox, which you are encouraged to read and
contribute to, at http://ccatoolbox.pbwiki.com/. The toolbox is free – use it at your own
risk. The toolbox is offered under the GNU general public license (version 3, see
www.gnu.org).
1.1 The toolbox
The toolbox consists of seven types of utilities:
Data validation and preprocessing
Multivariate autoregression (MVAR) modelling and G-causality analysis
Statistical tools for assessing significance and model validity etc.
Causal connectivity statistics, operating on significant interactions
Graphical display
Utility tools for e.g., removal of specific frequency components
Demonstration functions
To cut to the chase, before doing anything else, run ccaStartup which adds various
MATLAB paths. This function will throw an error if (i) certain files are not found (in
5
which case instructions are given to find them), or (ii) a support ‘mex’ file is not
compiled properly (in which case instructions will be given on how to compile the file).
Assuming all is OK, given a matrix M of the form variables (rows) by observations (cols),
the corresponding G-causalities can be computed by:
[ret] = cca_granger_regress(M,nlags);
where nlags is the ‘model order’ (the number of lagged observations to include in the
multivariate regression model). Typically 2<=nlags<=10, though this depends on the
data. This will return a structure ret which has several fields. These fields include
ret.prb
which gives the p-value for the variable j (the column variable) ‘G-causing’
the variable i (the row variable). A low p-value (~0) indicates a significant causal
interaction. The field ret.gc
gives the magnitude of the corresponding interactions,
for both significant and non-significant interactions.
To display the results in graphical form, do the following:
[PR] = cca_findsignificance(ret,0.01,1);
GC = GC.*PR;
cca_plotcausality(GC);
To get a better idea of what’s going on, let’s walk through the function
cca_demo().
