asympPDC Package

version 3.0.6.5 (7.62 MB) by Koichi Sameshima
PDC/DTF connectivity analysis of multiple time series in frequency domain with rigorous asymptotic statistics by Granger causality concept.

22 Downloads

Updated 26 Oct 2022

From GitHub

View License on GitHub

asympPDC Package View asympPDC on File Exchange

by Koichi Sameshima and Luiz A. Baccalá

October 05, 2022

The asympPDC Package consists of MATLAB/Octave functions and scripts collection for the analysis of multiple time series, such as EEG, biological signals and climate data, for the inference of directed interactions between structures in the frequency domain using Partial Directed Coherence (PDC) — based on the concept of Granger causality — and Directed Transfer Function (DTF), both in three metrics (Euclidean, diagonal and information) under the strict asymptotic statistics with p-values and confidence intervals also provided in the frequency domain.

Installation and usage

The asympPDC Package contains MATLAB/Octave m-files and subdirectories that you may download and copy into your local preferred working directory. To start, you should go to the package root directory and run the startup.m script in the MATLAB/Octave command line window that will set paths and check for the requirements.

>> startup

Besides adding paths, startup.m will also check for the presence of required MATLAB toolboxes (Control System Toolbox(TM), Signal Processing Toolbox(TM), and Statistics Toolbox(TM) or Statistics or Machine Learning Toolbox(TM)) or Octave packages (control, signal, and statistics). This is a standalone package that will most likely work in the recent versions of Octave — 6.3.0, 6.4.0, 7.1.0 and 7.2.0 (this latter version tested on MX Linux 32-bit). (Please report problems or suggest corrections to any issues related to compatibility with Octave).

To run all examples provided in ./examples subdirectory and verify if your installation is working properly, execute:

>> run_all_examples

If run_all_examples.m completes successfully, congratulation, you should see 40+ overlapped figures that you could examine, in MATLAB, through

>> tilefigs1 or tilefigs2

These commands tile the screen with figure windows. The tilefigs1 and tilefigs2 functions do not seem to work in the Octave environment (on Octave v7.2.0 tilefigs2 and tilefigs2 recovered function to tile the figure windows, but these windows stay behind Octave IDE).

Schematic view of connectivity measures evolution

The figure bellow shows schematically the evolution path of directed connectivity, Granger causality and allied concepts developed along the last half-century from bivariate (N = 2) to multivariate (N > 2) time series, and from time domain to frequency domain analysis. The measures inside the yellow area are those implemented in asympPDC Package.


connectivity_measures_in_asymppdc.png


  1. Lütkepohl, H. (1993) Introduction to Multiple Time Series Analysis. 2nd Edition, Springer, Berlin.

  2. Saito, Y. and H. Harashima (1981) Tracking of information within multichannel record: causal analysis in EEG. In Recent Advances in EEG and EMG Data Processing. pp. 133–146, Amsterdam: Elsevier. (Hard to find !)

Getting started work flow

To get started, you may modify the analysis_template.m script file to adapt it to your needs and data sets. This template file contains four examples of data that might be of help to deal with your own data sets. The basic steps to set up and analyze a data set using asympPDC Package are:

  1. Importing or opening column- or row-vectors data file;

  2. Choosing proper label for your data, assigning values to chLabels variable, or leave it empty, [ ];

  3. Data pre-processing: filtering, detrending and standardization (optional);

  4. Multivariate autoregressive (MAR) model estimation, by choosing parameters, estimation algorithm and model order selection criterion;

  5. PDC or DTF estimation, choosing analysis parameters such as significance levels for connectivity inference (alpha, gct_signif and igct_signif) , metric for PDC/DTF, and number of frequency points, then call asymp_pdc or asymp_dtf function, and the analysis results will be saved in MATLAB struct variable that could be used for further analysis, or plotted;

  6. Visualization of analysis results through the use of xplot, xplot_pvalues and xplot_title functions that will properly format and plot PDC/DTF and corresponding p-values results saved in struct variable obtained in the previous step in the frequency domain. Several matrix-layout plotting using xplot and xplot_pvalues can be achieved choosing plotting parameters, i.e. flgPrinting, w_max, flgColor, flgScale, flgMax, and flgSignifColor. See further details in the xplot function.

Examples

Examples from the literature are provided in ./examples directory with complete m-files in program structure similar to analysis_template.m. We hope that the examples may help readers and users to understand and/or gain further insight into Granger causality, instantaneous Granger causality, PDC, and DTF concepts and the realm of connectivity analysis. Use MATLAB/Octave help command to look up more detail of each function or script. The help itself may also provide links to the corresponding literature materials.

We hope you enjoy it. Please give us feedback. Good luck.

References

A. The asympPDC Package implementation is based mainly on the following articles and books:

A. The asympPDC Package implementation is based mainly on the following articles and books

[1] L.A. Baccalá and K. Sameshima (2001). Partial directed coherence: a new concept in neural structure determination. Biol Cybern 84:463–474. https://doi.org/10.1007/PL00007990

[2] D.Y. Takahashi, L.A. Baccalá and K. Sameshima (2007), Connectivity inference between neural structures via partial directed coherence. J Appl Stat 34:1259–1273. https://doi.org/10.1080/02664760701593065

[3] L.A. Baccalá, C.S.N. De Brito, D.Y. Takahashi and K. Sameshima (2013). Unified asymptotic theory for all partial directed coherence forms. Philos T Roy Soc A 371:1–13. https://doi.org/10.1098/rsta.2012.0158

[4] M.J. Kamiński and K.J. Blinowska (1991). A new method of the description of the information flow in the brain structures. Biol Cybern 65:203–210. https://doi.org/10.1007/bf00198091

[5] L.A. Baccalá, D.Y. Takahashi and K. Sameshima (2016). Directed transfer function: unified asymptotic theory and some of its implications. IEEE T Bio-Med Eng 63:2450–2460. https://doi.org/10.1109/TBME.2016.2550199

[6] H. Lütkepohl (2005). New Introduction to Multiple Time Series Analysis. Springer-Verlag, Berlin. https://doi.org/10.1007/978-3-540-27752-1

[7] S.L. Marple Jr (1987). Digital Spectral Analysis with Application. Prentice-Hall, Englewood-Cliffs.

[8] T. Schneider and A. Neumaier (2001). Algorithm 808: ARfit - A Matlab package for the estimation of parameters and eigenmodes of multivariate autoregressive models. ACM Trans Math Softw 27:58–65. https://doi.org/10.1145/382043.382316

[9] K. Sameshima and L.A. Baccalá Eds. (2014). Methods in Brain Connectivity Inference through Multivariate Time Series Analysis. CRC Press, Boca Raton. https://doi.org/10.1201/b16550

B. Historical development: Biological Cybernetics 60th ANNIVERSARY RETROSPECTIVE

[10] L.A. Baccalá and K. Sameshima (2021). Partial directed coherence: twenty years on some history and an appraisal. Biol Cybern 115:195–204. https://doi.org/10.1007/s00422-021-00880-y

C. Things to come: Total PDC/DTF with asymptotic statistics, spectral factorization and faster PDC/DTF estimation algorithms . . .

[11] L.A. Baccalá and K. Sameshima (2021). Frequency domain repercussions of instantaneous Granger causality. Entropy 23:10.3390/e23081037 https://doi.org/10.3390/e23081037

[12] L.A. Baccalá and K. Sameshima (2022). Partial directed coherence and the vector autoregressive modelling myth and a caveat. Front Netw Physiol 2:845327. https://doi.org/10.3389/fnetp.2022.845327 (Note: MATLAB/Octave scripts and functions used to generate all four figures of this article are provided in ./demo/PDCVARMYTH2022 subdirectory. To use follow the instructions in Readme file.)

License

These routines are distributed under GNU General Public License v3.0 under authorship of Koichi Sameshima and Luiz A. Baccalá - July 2022.

Cite as

Koichi Sameshima and Luiz A. Baccalá (2022). asympPDC Package (Release v3.0), GitHub. Retrieved August 12, 2022.

View asympPDC on File Exchange

MATLAB Release Compatibility
Created with R2020a
Compatible with R2014b to R2020a
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.