blockMVAR - Toolbox for block-based MVAR connectivity analysis
The
present study introduces a new framework for the frequency-domain
evaluation of directional influences in jointly stationary multivariate
vector processes. The framework extends to the study of vector
processes the DC/PDC framework, and provides a full multivariate
account for the Geweke framework. As such, it is recommended for the
evaluation of causal relationships between multiple blocks of time
series, with typical application in neurophysiology where multichannel
data acquisition technologies allow to monitor many regions of interest
with many recordings per region. The proposed framework is exploited to
define new frequency domain connectivity measures, which are shown (i)
to possess desirable theoretical properties of causality measures; (ii)
to be able to reflect either direct causality or total (i.e.,
direct+indirect) causality from one vector process to another in the
multivariate representation; (iii) to reduce to known causality
measures derived from the Geweke framework in the case of bivariate
vector processes, and from the DC/PDC framework in the case of
multivariate scalar processes.
The blockMVAR Matlab toolbox is based on the papers:
L.Faes and G. Nollo, "Measuring Frequency Domain Granger Causality for Multiple Blocks of Interacting Time Series", Biological Cybernetics 2013. DOI: 10.1007/s00422-013-0547-5
L.Faes, S. Erla and G. Nollo, "Block Partial Directed Coherence: a New Tool for the Structural Analysis of Brain Networks", International Journal of Bioelectromagnetism, Vol. 14, No. 4, pp. 162 - 166, 2012
DOWNLOAD:
Zip file with all scripts and functions: blockMVAR.zip
DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITY The code is supplied as is and all use is at your own risk. The authors disclaim all warranties of any kind, either express or implied, as to the softwares, including, but not limited to, implied warranties of fitness for a particular purpose, merchantability or non - infringement of proprietary rights. Neither this agreement nor any documentation furnished under it is intended to express or imply any warranty that the operation of the software will be error - free. Under no circumstances shall the authors of the softwares provided here be liable to any user for direct, indirect, incidental, consequential, special, or exemplary damages, arising from the software, or user' s use or misuse of the softwares. Such limitation of liability shall apply whether the damages arise from the use or misuse of the data provided or errors of the software.
DESCRIPTION OF THE TOOLBOX
Functions:
- block_fdMVAR.m : performs block-based frequency domain connectivity analysis from the parameters of a strictly causal MVAR model; returns the following coupling measures block directed coherence, block partial directed coherence, multivariate direct causality, multivariate total causality.
- block_fdMVAR_diag.m : similar to block_fdmvar, but forces the input covariance and its inverse to be diagonal matrices. This is to prevent negative values of the causality functions on real applications where the model inputs may be correlated (so the model is not strictly causal as it should be for these analyses). These functions realize for the block case the so-called "generalized" formulation (gDTF=DC,gPDC) defined in the Baccalà papers, while the functions above with non-diagonal covariances realize the so-called "information" formulation. This modification was proposed in the IJBEM paper, and is used in the practical analysis of the Biol Cyb paper.
- Geweke_f.m : estimates f and f_cond, logarithmic frequency domain causality and conditional causality measures, defined in Geweke (1982) and Geweke (1984) seminal papers.
Scripts:
- example.m : runs the theoretical example of Faes and Nollo, generating Figure 2 of the paper, i.e., analytical computation of frequency domain logarithmic and non-logarithmic causality measures for an illustrative theoretical example.
- example_Fig6.m : runs the simulated example of Faes and Nollo, generating Figure 6 of the paper, i.e., estimation of frequency domain logarithmic causality measures for several realizations of the illustrative theoretical example, and comparison with estimated known Geweke measures.
Other functions:
The toolbox makes also use of functions taken from the eMVAR toolbox:
- idMVAR.m : identification of strictly causal MVAR model: estimates model coefficients, innovations and innovation covariance from a given time series and a given model order. The default identification algorithm is the standard least squares method, but several other algorithms may be recalled.
- MVARfilter.m : yields a single realization of a strictly causal MVAR process of assigned dimensionality and length, given strictly causal coefficients and residuals.