dyconnmap package

Subpackages

Submodules

dyconnmap.analytic_signal module

Analytic Signal

For a time series \(x(t)\), filtered with a passband \(N\); first we compute its analytic representation (Cohen1995 , Freeman2007):

\[u_j(t) = \frac{1}{\pi} \textrm{PV} \int_{+\infty}^{-\infty} { \frac{V_j(t')}{t-t'} dt'}\]

where \(PV\) signifies the Cauchy Principal Value. The above equation results into a complex time-series \(V_j(t)\), with a real part \(v_j(t)\) (the original neuroelectric time-series) and an imaginary part \(u_j(t)\), both as functions of time. Where \(j\) the EEG recording electrode id.

From these parts, we are capable to determine the Instantaneous Amplitude:

\[A_j(t) = \sqrt{ v_j^2 (t) + u_j^2 (t) }\]

and its Instantaneous Phase counterpart, from:

\[\phi_j (t) = atan \frac{u_j(t)} {v_j(t)}\]

The values in \(\phi_j(t)\) are originally bound to \([-\pi, \pi]\), however we employed an unwrap transformation (a phase correction algorithm) in order to eliminate the discontinuities (Dimitriadis2010_, Freeman2002).


Cohen1995

Cohen, L. (1995). Time-frequency analysis (Vol. 1, No. 995,299). Prentice hall.

Freeman2007

Walter J. Freeman (2007) Hilbert transform for brain waves. Scholarpedia, 2(1):1338.

Dimitriadis2010

Dimitriadis, S. I., Laskaris, N. A., Tsirka, V., Vourkas, M., Micheloyannis, S., & Fotopoulos, S. (2010). Tracking brain dynamics via time-dependent network analysis. Journal of neuroscience methods, 193(1), 145-155.

Freeman2002

Freeman, W. J., & Rogers, L. J. (2002). Fine temporal resolution of analytic phase reveals episodic synchronization by state transitions in gamma EEGs. Journal of neurophysiology, 87(2), 937-945.

Butter1930

Butterworth, S. (1930). On the theory of filter amplifiers. Wireless Engineer, 7(6), 536-541.

dyconnmap.analytic_signal.analytic_signal(signal, fb=None, fs=None, order=3)[source]

Passband filtering and Hilbert transformation

Parameters

  • signal (real array-like, shape(n_rois, n_samples)) – Input signal

  • fb (list of length 2, optional) – The low and high frequencies.

  • fs (int, optional.) – Sampling frequency.

  • order (int, optional) – The Filter order. Default 3.

Returns

  • hilberted_signal (complex array-like, shape(n_rois, n_samples)) – The Hilbert representation of the input signal.

  • unwrapped_phase (real array-like, shape(n_rois, n_samples)) – The unwrapped phase of the Hilbert representation.

  • filtered_signal (real array-like, shape(n_rois, n_samples)) – The input signal, filtered within the given frequencies. This is returned only if fb and fs are passed.

Notes

Internally, we use SciPy’s Butterworth implementation (scipy.signal.butter) and the two-pass filter scipy.signal.filtfilt to achieve results identical to MATLAB.

dyconnmap.bands module

Commonly used band frequencies

For your convenience we have predefined some widely adopted brain rhythms. You can access them with

1 from dyconnmap.bands import *
2 print(bands['alpha'])

brainwave

frequency (Hz)

variable/index

δ

[1.0, 4.0]

bands[‘delta’]

θ

[4.0, 8.0]

bands[‘theta’]

α1

[7.0, 10.0]

bands[‘alpha1’]

α2

[10.0, 13.0]

bands[‘alpha2’]

α

[7.0, 13.0]

bands[‘alpha’]

μ

[8.0, 13.0]

band[‘mu’]

β

[13.0, 25.0]

bands[‘beta’]

γ

[25.0, 40.0]

bands[‘gamma’]

dyconnmap.sliding_window module

Sliding Window

dyconnmap.sliding_window.sliding_window(data, estimator_instance, window_length=25, step=1, pairs=None)[source]
dyconnmap.sliding_window.sliding_window_indx(data, window_length, overlap=0.75, pairs=None)[source]

Compute the indices and pairs using a sliding window.

Slide a window over data, and return the indices and offsets.

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • window_length (int) – Number of samples to be used in the computation of the connectivity.

  • overlap (float) – Percentage of the window_length by which the window will overlap when sliding forward.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

indices – Indices of pairs.

Return type

array - like, shape(n_windows, start_offset, end_offset, n_channels, n_channels)

dyconnmap.tvfcgs module

Time-Varying Functional Connectivity Graphs

Time-varying functional connectivity graphs (TVFCGs) (Dimitriadis2010_, Falani2008) introduce the idea of processing overlapping segments of neuroelectric signals by defining a frequency-dependent time window in which the synchronization is estimated; and then tabulating the results as adjacency matrices. These matrices have a natural graph-based representation called “functional connectivity graphs” (FCGs).

An important aspect of the TVFCGs is the “cycle-criterion” (CC) (Cohen2008). It regulates the amount of the oscillation cycles that will be considered in measuring the phase synchrony. In the original proposal \(CC = 2.0\) was introduced, resulting into a time-window with width twice the lower period. TVFCGs on the other, consider the given lower frequency that correspond to the possibly synchronized oscillations of each brain rhythm and the sampling frequency. This newly defined frequency-depedent time-window is sliding over the time series and the network connectivity is estimated. The overlapping is determined by an arbitrary step parameter.

Given a multi-channel recording data matrix \(X^{m \times n}\) of size \(m \times n\) (with \(m\) channels, and \(n\) samples), a frequency range with \(F_{up}\) and \(F_{lo}\) the upper and lower limits, \(fs\) the sampling frequency, \(step\) and \(CC\), the computation of these graphs proceeds as follows:

Firstly, based on the \(CC\) and the specified frequency range (\(F_{lo}\) and \(fs\) ) the window size calculated:

\[w_{len} = \frac{ CC }{ F_{lo} } fs\]

Then, this window is moving per \(step\) samples and the average synchronization is computed (between the channels, in a pairwise manner) resulting into \(\frac{n}{step}\) adjacency matrices of size \(n \times n\).


Cohen2008

Cohen, M. X. (2008). Assessing transient cross-frequency coupling in EEG data. Journal of neuroscience methods, 168(2), 494-499.

Dimitriadis2010

Dimitriadis, S. I., Laskaris, N. A., Tsirka, V., Vourkas, M., Micheloyannis, S., & Fotopoulos, S. (2010). Tracking brain dynamics via time-dependent network analysis. Journal of neuroscience methods, 193(1), 145-155.

Falani2008

Fallani, F. D. V., Latora, V., Astolfi, L., Cincotti, F., Mattia, D., Marciani, M. G., … & Babiloni, F. (2008). Persistent patterns of interconnection in time-varying cortical networks estimated from high-resolution EEG recordings in humans during a simple motor act. Journal of Physics A: Mathematical and Theoretical, 41(22), 224014.

dyconnmap.tvfcgs.tvfcg(data, estimator_instance, fb, fs, cc=2.0, step=5.0, pairs=None)[source]

Time-Varying Functional Connectivity Graphs

The TVFCGs are computed from the input data by employing the given synchronization estimator (estimator_instance).

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • estimator_instance (object) – An object of type dyconnmap.fc.Estimator.

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed FCGs.

Return type

array-like, shape(n_windows, n_channels, n_channels)

dyconnmap.tvfcgs.tvfcg_cfc(data, estimator_instance, fb_lo, fb_hi, fs=128, cc=2.0, step=5, pairs=None)[source]

Time-Varying Functional Connectivity Graphs (for Cross frequency Coupling)

The TVFCGs are computed from the input data by employing the given cross frequency coupling synchronization estimator (estimator_instance).

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • estimator_instance (object) – An object of type dyconnmap.fc.Estimator.

  • fb_lo (list of length 2) – The low and high frequencies.

  • fb_hi (list of length 2) – The low and high frequencies.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed Cross-Frequency FCGs.

Return type

array-like, shape(n_windows, n_channels, n_channels)

Notes

Not all available estimators in the dyconnmap.fc are valid for estimating cross frequency coupling.

dyconnmap.tvfcgs.tvfcg_compute_windows(data, fb_lo, fs, cc, step)[source]

Compute TVFCGs Sliding Windows

A helper function that computes the size and number of sliding windows given the parameters.

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • fb_lo –

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – Stepping.

Returns

  • windows (int) – The total number of sliding windows.

  • window_length (int) – The length of a sliding window; number of samples used to estimated the connectivity.

dyconnmap.tvfcgs.tvfcg_ts(ts, fb, fs=128, cc=2.0, step=5, pairs=None, avg_func=<function mean>)[source]

Time-Varying Function Connectivity Graphs (from time series)

This implementation operates directly on the given estimated synchronization time series (ts) and the mean value inside the window is computed.

Parameters

  • ts (array-like, shape(n_channels, n_samples)) – Multichannel synchronization time series.

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed FCGs.

Return type

array-like

Module contents

dyconnmap.analytic_signal(signal, fb=None, fs=None, order=3)[source]

Passband filtering and Hilbert transformation

Parameters

  • signal (real array-like, shape(n_rois, n_samples)) – Input signal

  • fb (list of length 2, optional) – The low and high frequencies.

  • fs (int, optional.) – Sampling frequency.

  • order (int, optional) – The Filter order. Default 3.

Returns

  • hilberted_signal (complex array-like, shape(n_rois, n_samples)) – The Hilbert representation of the input signal.

  • unwrapped_phase (real array-like, shape(n_rois, n_samples)) – The unwrapped phase of the Hilbert representation.

  • filtered_signal (real array-like, shape(n_rois, n_samples)) – The input signal, filtered within the given frequencies. This is returned only if fb and fs are passed.

Notes

Internally, we use SciPy’s Butterworth implementation (scipy.signal.butter) and the two-pass filter scipy.signal.filtfilt to achieve results identical to MATLAB.

dyconnmap.sliding_window(data, estimator_instance, window_length=25, step=1, pairs=None)[source]
dyconnmap.sliding_window_indx(data, window_length, overlap=0.75, pairs=None)[source]

Compute the indices and pairs using a sliding window.

Slide a window over data, and return the indices and offsets.

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • window_length (int) – Number of samples to be used in the computation of the connectivity.

  • overlap (float) – Percentage of the window_length by which the window will overlap when sliding forward.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

indices – Indices of pairs.

Return type

array - like, shape(n_windows, start_offset, end_offset, n_channels, n_channels)

dyconnmap.tvfcg(data, estimator_instance, fb, fs, cc=2.0, step=5.0, pairs=None)[source]

Time-Varying Functional Connectivity Graphs

The TVFCGs are computed from the input data by employing the given synchronization estimator (estimator_instance).

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • estimator_instance (object) – An object of type dyconnmap.fc.Estimator.

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed FCGs.

Return type

array-like, shape(n_windows, n_channels, n_channels)

dyconnmap.tvfcg_cfc(data, estimator_instance, fb_lo, fb_hi, fs=128, cc=2.0, step=5, pairs=None)[source]

Time-Varying Functional Connectivity Graphs (for Cross frequency Coupling)

The TVFCGs are computed from the input data by employing the given cross frequency coupling synchronization estimator (estimator_instance).

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • estimator_instance (object) – An object of type dyconnmap.fc.Estimator.

  • fb_lo (list of length 2) – The low and high frequencies.

  • fb_hi (list of length 2) – The low and high frequencies.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed Cross-Frequency FCGs.

Return type

array-like, shape(n_windows, n_channels, n_channels)

Notes

Not all available estimators in the dyconnmap.fc are valid for estimating cross frequency coupling.

dyconnmap.tvfcg_compute_windows(data, fb_lo, fs, cc, step)[source]

Compute TVFCGs Sliding Windows

A helper function that computes the size and number of sliding windows given the parameters.

Parameters

  • data (array-like, shape(n_channels, n_samples)) – Multichannel recording data.

  • fb_lo –

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – Stepping.

Returns

  • windows (int) – The total number of sliding windows.

  • window_length (int) – The length of a sliding window; number of samples used to estimated the connectivity.

dyconnmap.tvfcg_ts(ts, fb, fs=128, cc=2.0, step=5, pairs=None, avg_func=<function mean>)[source]

Time-Varying Function Connectivity Graphs (from time series)

This implementation operates directly on the given estimated synchronization time series (ts) and the mean value inside the window is computed.

Parameters

  • ts (array-like, shape(n_channels, n_samples)) – Multichannel synchronization time series.

  • fb (list of length 2) – The lower and upper frequency.

  • fs (float) – Sampling frequency.

  • cc (float) – Cycle criterion.

  • step (int) – The amount of samples the window will move/slide over the time series.

  • pairs (array-like or None) –

    • If an array-like is given, notice that each element is a tuple of length two.

    • If None is passed, complete connectivity will be assumed.

Returns

fcgs – The computed FCGs.

Return type

array-like