Introduction

The Dynamic Synchronization Toolbox (DST) is an implementation of the pipeline used in our previous article [10] to calculate phase connectivity based dynamic graphs. This study dealt with the analysis of EEG data recorded during externally triggered finger movements in younger and older subjects. We used this pipeline to get in depth information on the connectivity dynamics during movement planning and movement execution and especially how these dynamics are changed in healthy aged persons. For this purpose it was necessary to use a non-static connectivity measure which can detect instantaneous changes in the coupling of the signals. Compared to other toolboxes that allow connectivity analyses of EEG signals, we focused here on ensuring the highest possible temporal resolution. Other toolboxes such as Dynamic Causal Modeling (DCM, [4]) as a function of the Statistical Parametric Mapping toolbox (SPM, [1]) for instance, require static connectivity and thus do not allow for time course analysis. Also, connectivity approaches, like Granger Causality [3] or Mutual Information [7], assume stationary signals and thus have a fairly low temporal resolution.

The Brain Connectivity Toolbox (BCT, [11]) comes into play after connectivity has been determined to perform further network-related calculations. It is a very powerful toolbox that includes different graph theoretic measures. For this reason, we also use this functionality for the calculation of network properties in our toolbox.

The scripts presented here have been generalized as much as possible to allow application not only to EEG data as in our prior publication, but to a wide variety of data as long as they were transformed to phase space. Thereby, this toolbox has a high reuse potential also in other fields of research, e.g Geophysics, Geomorphology, Systems Biology, Ecology or Social Network Sciences, that deal with dynamic connectivity, i.e. interactions of signals at different ‘recording sites’.

Implementation and architecture

The toolbox presented here provides a MATLAB implementation of the pipeline for creating and graph theoretically analyzing dynamic networks as has been introduced in [10]. The pipeline consists of three major steps (Figure 1): First, phase-locking values between two measuring sites, e.g. electrodes, are computed relative to a defined baseline period, second, the calculated connectivities are used to define dynamic graphs at the group level by testing for significant increase compared to baseline using t-tests and last, the dynamic graphs are analyzed using graph-theoretic measures from the BCT [11].

In the first step, the input data, that has been epoched and transformed to phase space prior application, undergoes a connectivity analysis based on the relative phase-locking value (rPLV), which is defined as follows:

where t denotes time, f frequency and ${\phi }_{m_k}$M3 \documentclass[10pt]{article} \usepackage{wasysym} \usepackage[substack]{amsmath} \usepackage{amsfonts} \usepackage{amssymb} \usepackage{amsbsy} \usepackage[mathscr]{eucal} \usepackage{mathrsfs} \usepackage{pmc} \usepackage[Euler]{upgreek} \pagestyle{empty} \oddsidemargin -1.0in \begin{document} \[ {\varphi _{{m_k}}} \] \end{document} in Eq. (1) the phase of the signal at measuring site m in the k-th trial. N is the total number of trials, i.e. repeating segments of measurements, and i is the imaginary unit. In Eq. (2) the previously calculated PLV is normalized relative to the mean PLV in a predefined baseline period.

In the second step, t-tests are used to define periods of significally increased phase-connectivity for each signal pair. In the toolbox we included the options to compare the rPLV against zero or against an artificially computed baseline signal consisting of random noise with the same mean and standard deviation as the baseline period and of the same length as the test interval. We further implemented three options for dealing with multiple comparisons: (i) no correction (for simple checks), (ii) false discovery rate (FDR) correction for single pairs and (iii) FDR correction pooled over all timepoints and signal pairs. A connection is assigned between a signal pair if the rPLV is significantly greater than zero or the artificial baseline.

Dynamic graphs were then defined as the ordered set G(t) = {G_t |t ϵ [1,…, T]} of binary undirected graphs G_t = (V,E_t), where the graph G is defined by a set of vertices V and edges E_t: V × V → R, for each point in time t.

In the last step, we added the option to compute several graph measures from the BCT. These are, the node degree (i.e. the number of connections of a node), a Louvain community detection (also called clustering), the node flexibility (i.e. how often the nodes switch between the clusters) and the HUB nodes (i.e. the most influencial nodes) of the networks. We determined all of these measures at all given points in time to obtain their overall dynamics. For a better overview, we added an optimization step for community detection. Here, we always used the previous cluster configuration as the initial condition for the following community detection. Additionally, we post-hoc assigned the label for each community, minimizing the number of label switches between time points, which prevents the same cluster from being assigned different cluster labels at consecutive time points.

A more detailed description of the methods used can be found in [10].

Script architecture

The DST is fully implemented in MATLAB. It includes a main directory consisting of the master function dynamic_synchronization_toolbox_function.m, a documentation file readme.m and subfolders for data and scripts.

The master script is used to specify various options used for further processing. In this script we define the subject IDs, which will afterwards be loaded from the subfolders of the same name in the subject folder, e.g.:

subjects=[‘Sub01’;’Sub02’];

These subject folders are organized in a BIDS (Brain Imaging Data Structure; [2, 8]) like fashion, i.e. each subject has its own subfolder within the data folder. These subfolders then consist of a mat-file containing the epoched EEG data transformed to phase space and a trial definition file (in case of multiple experimental conditions).

Within the master script, an options structure is defined which sets several options for calculating the rPLV in step 1. See Table 1 for all available options. The rPLVs are then computed by calling the function rplv_func.m (Figure 2, step 1).

Furthermore, we define the stats structure which sets several options for statistical analysis of the rPLV in step 2. See Table 2 for all available options. As described above, we included three options for multiple comparison, which can be set by stats.pid. The corresponding thresholds for t-tests and FDR correction can be defined in this structure. Additionally, this structure includes an option stats.comp to select the desired statistical comparison, i.e. against an artificial baseline (described above) or against zero. Subsequently the function stats_rplv.m is called to compute the significant edges and construct the dynamic graphs (Figure 2, step 2).

The optional calculation of node degree, community detection, node flexibility and HUB nodes can be altered by adjusting the variable graph_measures = True or False (Figure 2, step 3).

Script application

The first step for using the DST pipeline is to arrange the preprocessed data in a BIDS-like data structure in the Data subfolder. The data set of each subject should be stored in a subfolder SubID of the Data folder and labelled SubID_eeg.mat. Each preprocessed (e.g. transformed to time-frequency phase-space) data set has to be stored in a mat-file with the dimensions [channels × frequencies × timepoints × trials]. In order to use the pipeline for multiple experimental conditions an additional file called SubID_trialselection.mat with dimensions [Trials × Conditions] giving boolean information about the condition of each trial is needed. In the second step, the user has to set the options for the calculation of the synchronization metric in structures (as defined above) options, stats and graphs as well as a list of subject IDs and the path to the subject data subfolder. In the last step, the main function dynamic_connectivity_toolbox_function.m has to be executed with the previously defined options. This will at the end produce the following output variables:

The optional graph metric generates the following additional outputs:

Quality control

To ensure sufficient quality control, two sample datasets of artificial data each consisting of four conditions were added to the scripts, one exhibiting a high degree of connectivity and the other a low degree of connectivity. The data are created by running the script sample_data_creation.m located in the “Data” subfolder. The data consists of two identical subjects with the dimensions [61 channels, 48 frequencies, 800 timepoints, 100 trials]. A set of 27 channels is perfectly phase-locked after artifical stimulation in the time-interval [300:500] for trials [1:25] and [51:75]. In contrast, the remaining channels are phase-locked in the same interval, but for trials [26:50] and [76:100]. We also provide two figures depicting the rPLV for all possible connections: First, the connectivity is shown for all four conditions in the originally created dataset (File rplv_sampledata_original.png) and second, there is a version after switching a set of electrodes and merging conditions 1 with 2 and 3 with 4 (File rplv_sampledata_merged.png). In the first case the contrast of conditions 1 and 2 will show a huge difference in rPLV between two distinct sets of measurement sites (e.g. left and right hemispheric electrodes). In the second case this difference should disappear since those two groups were swapped in the second condition leading to equal experimental conditions. These figures are located in the folder “Quality control”. This makes it possible to check if the definition of the networks was successful. In the following, this data will also be used to ensure the correct integration of the scripts from the BCT.

The data associated with the original article, analyzed with the toolbox, has been made available [9].

Operating system

DST is a pure MATLAB code, and should function on all operating systems in which MATLAB is supported.

Programming language

MATLAB (developed in vR2018b).

Additional system requirements

None.

Dependencies

The graph analysis is based on significant edges which depend on the Statistic toolbox [6]). The optional calculation of dynamic graph metrics makes use of the Brain Connectivity Toolbox [11]).

List of contributors

Nils Rosjat wrote the software and is its current maintainer. Silvia Daun: Conceptualization, Supervision, Project administration, Funding acquisition.

Support

Support requests of any kind are preferably to be submitted in GitHub as an issue or sent to the corresponding author Nils Rosjat via email.

Software location

Language

English.