spectral_connectivity.connectivity.Connectivity

class Connectivity(fourier_coefficients: ~numpy.ndarray, expectation_type: str = 'trials_tapers', frequencies: ~typing.Optional[~numpy.ndarray] = None, time: ~typing.Optional[~numpy.ndarray] = None, blocks: ~typing.Optional[int] = None, dtype: ~numpy.dtype = <class 'numpy.complex128'>)

Bases: object

Computes brain connectivity measures based on the cross spectral matrix.

Note that spectral granger methods that require estimation of transfer function and noise covariance use minimum phase decomposition [1] to decompose the cross spectral matrix into square roots, which then can be used to non-parametrically estimate the transfer function and noise covariance.

Parameters:

• fourier_coefficients (array, shape (n_time_windows, n_trials, n_tapers, n_fft_samples, n_signals)) – The compex-valued coefficients from a fourier transform. Note that this is expected to be the two-sided fourier coefficients (both the positive and negative lags). This is needed for the Granger-based methods to work.

• expectation_type (('trials_tapers' | 'trials' | 'tapers'), optional) – How to average the cross spectral matrix. ‘trials_tapers’ averages over the trials and tapers dimensions. ‘trials’ only averages over the trials dimensions (leaving tapers) and ‘tapers’ only averages over tapers (leaving trials).

• frequencies (array, shape (n_fft_samples,), optional) – Frequency of each sample, by default None

• time (np.ndarray, shape (n_time_windows,) optional) – Time of each window, by default None

• blocks (int, optional) – Number of blocks to split up input arrays to do block computation, by default None

• dtype (np.dtype, optional) – Data type of the fourier coefficients, by default xp.complex128

References

[1]

Dhamala, M., Rangarajan, G., and Ding, M. (2008). Analyzing information flow in brain networks with noxparametric Granger causality. NeuroImage 41, 354-362.

Attributes:

all_frequencies

Positive and negative frequencies of the transform

frequencies

Non-negative frequencies of the transform

n_observations

Number of observations

Methods

blockwise_spectral_granger_prediction()	Not implemented
canonical_coherence(group_labels)	Finds the maximal coherence between each combination of groups.
coherence_magnitude()	The magnitude squared of the complex coherency.
coherence_phase()	The phase angle of the complex coherency.
coherency()	The complex-valued linear association between time series in the frequency domain.
conditional_spectral_granger_prediction()	Not implemented
debiased_squared_phase_lag_index()	The square of the phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
debiased_squared_weighted_phase_lag_index()	The square of the weighted phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
delay([frequencies_of_interest, ...])	Find a range of possible delays from the coherence phase.
direct_directed_transfer_function()	A combination of the directed transfer function estimate of directional influence between signals and the partial coherence's accounting for the influence of other signals.
directed_coherence()	The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).
directed_transfer_function()	The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).
from_multitaper(multitaper_instance[, ...])	Construct connectivity class using a multitaper instance
generalized_partial_directed_coherence()	The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).
global_coherence([max_rank])	The linear combinations of signals that capture the most coherent power at each frequency and time window.
group_delay([frequencies_of_interest, ...])	The average time-delay of a broadband signal.
imaginary_coherence()	The normalized imaginary component of the cross-spectrum.
pairwise_phase_consistency()	The square of the phase locking value corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
pairwise_spectral_granger_prediction()	The amount of power at a node in a frequency explained by (is predictive of) the power at other nodes.
partial_directed_coherence([keep_cupy])	The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).
phase_lag_index()	A non-parametric synchrony measure designed to mitigate power differences between realizations (tapers, trials) and volume-conduction.
phase_locking_value()	The cross-spectrum with the power for each signal scaled to a magnitude of 1.
phase_slope_index([frequencies_of_interest, ...])	The weighted average of slopes of a broadband signal projected onto the imaginary axis.
power()	Power of the signal.
weighted_phase_lag_index()	Weighted average of the phase lag index using the imaginary coherency magnitudes as weights.

Methods

blockwise_spectral_granger_prediction	Not implemented
canonical_coherence	Finds the maximal coherence between each combination of groups.
coherence_magnitude	The magnitude squared of the complex coherency.
coherence_phase	The phase angle of the complex coherency.
coherency	The complex-valued linear association between time series in the frequency domain.
conditional_spectral_granger_prediction	Not implemented
debiased_squared_phase_lag_index	The square of the phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
debiased_squared_weighted_phase_lag_index	The square of the weighted phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
delay	Find a range of possible delays from the coherence phase.
direct_directed_transfer_function	A combination of the directed transfer function estimate of directional influence between signals and the partial coherence's accounting for the influence of other signals.
directed_coherence	The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).
directed_transfer_function	The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).
from_multitaper	Construct connectivity class using a multitaper instance
generalized_partial_directed_coherence	The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).
global_coherence	The linear combinations of signals that capture the most coherent power at each frequency and time window.
group_delay	The average time-delay of a broadband signal.
imaginary_coherence	The normalized imaginary component of the cross-spectrum.
pairwise_phase_consistency	The square of the phase locking value corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.
pairwise_spectral_granger_prediction	The amount of power at a node in a frequency explained by (is predictive of) the power at other nodes.
partial_directed_coherence	The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).
phase_lag_index	A non-parametric synchrony measure designed to mitigate power differences between realizations (tapers, trials) and volume-conduction.
phase_locking_value	The cross-spectrum with the power for each signal scaled to a magnitude of 1.
phase_slope_index	The weighted average of slopes of a broadband signal projected onto the imaginary axis.
power	Power of the signal.
weighted_phase_lag_index	Weighted average of the phase lag index using the imaginary coherency magnitudes as weights.

Attributes

all_frequencies	Positive and negative frequencies of the transform
frequencies	Non-negative frequencies of the transform
n_observations	Number of observations

property all_frequencies

Positive and negative frequencies of the transform

blockwise_spectral_granger_prediction()

Not implemented

canonical_coherence(group_labels)

Finds the maximal coherence between each combination of groups.

The canonical coherence finds two sets of weights such that the coherence between the linear combination of group1 and the linear combination of group2 is maximized.

Parameters:

group_labels (array-like, shape (n_signals,)) – Links each signal to a group.

Returns:

• canonical_coherence (array, shape (n_time_samples, n_fft_samples, n_groups, n_groups)) – The maximimal coherence for each group pair

• labels (array, shape (n_groups,)) – The sorted unique group labels that correspond to n_groups

References

[1]

Stephen, E.P. (2015). Characterizing dynamically evolving functional networks in humans with application to speech. Boston University.

coherence_magnitude()

The magnitude squared of the complex coherency. Note that the squared modulus of coherency (originally a complex quantity) is the magnitude-squared coherence (i.e., the normalized, real component of coherency). This value should bounded by 0 and 1.

Hansson-Sandsten M (2011) Cross-spectrum and coherence function estimation using time-delayed Thomson multitapers. In: 2011 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), pp 4240–4243.

Returns:

magnitude

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

coherence_phase()

The phase angle of the complex coherency.

Returns:

phase

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

coherency()

The complex-valued linear association between time series in the frequency domain.

Returns:

complex_coherency

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

conditional_spectral_granger_prediction()

Not implemented

debiased_squared_phase_lag_index()

The square of the phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.

Returns:

phase_lag_index

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., and Pennartz, C.M.A. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. NeuroImage 55, 1548-1565.

debiased_squared_weighted_phase_lag_index()

The square of the weighted phase lag index corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.

Returns:

weighted_phase_lag_index

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., and Pennartz, C.M.A. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. NeuroImage 55, 1548-1565.

delay(frequencies_of_interest=None, frequency_resolution=None, significance_threshold=0.05, n_range=3)

Find a range of possible delays from the coherence phase.

The delay (and phase) at each frequency is indistinguishable from 2 pi phase jumps, but we can look at a range of possible delays and see which one is most likely.

Parameters:

• frequencies_of_interest (array-like, shape (2,)) –

• frequencies (array-like, shape (n_fft_samples,)) –

• frequency_resolution (float) –

• n_range (int) – Number of phases to consider.

Returns:

possible_delays

Return type:

array, shape (…, n_frequencies, (n_range * 2) + 1, n_signals, n_signals)

direct_directed_transfer_function()

A combination of the directed transfer function estimate of directional influence between signals and the partial coherence’s accounting for the influence of other signals.

Returns:

direct_directed_transfer_function

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Korzeniewska, A., Manczak, M., Kaminski, M., Blinowska, K.J., and Kasicki, S. (2003). Determination of information flow direction among brain structures by a modified directed transfer function (dDTF) method. Journal of Neuroscience Methods 125, 195-207.

directed_coherence()

The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).

This measure is the same as the directed transfer function but the signal inflow is scaled by the noise variance.

Returns:

directed_coherence

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Baccala, L., Sameshima, K., Ballester, G., Do Valle, A., and Timo-Iaria, C. (1998). Studying the interaction between brain structures via directed coherence and Granger causality. Applied Signal Processing 5, 40.

directed_transfer_function()

The transfer function coupling strength normalized by the total influence of other signals on that signal (inflow).

Characterizes the direct and indirect coupling to a node.

Returns:

directed_transfer_function

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Kaminski, M., and Blinowska, K.J. (1991). A new method of the description of the information flow in the brain structures. Biological Cybernetics 65, 203-210.

property frequencies

Non-negative frequencies of the transform

classmethod from_multitaper(multitaper_instance, expectation_type='trials_tapers', blocks=None, dtype=<class 'numpy.complex128'>)

Construct connectivity class using a multitaper instance

generalized_partial_directed_coherence()

The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).

The partial directed coherence tries to regress out the influence of other observed signals, leaving only the direct coupling between two signals.

The generalized partial directed coherence scales the relative strength of coupling by the noise variance.

Returns:

generalized_partial_directed_coherence

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Baccala, L.A., Sameshima, K., and Takahashi, D.Y. (2007). Generalized partial directed coherence. In Digital Signal Processing, 2007 15th International Conference on, (IEEE), pp. 163-166.

global_coherence(max_rank=1)

The linear combinations of signals that capture the most coherent power at each frequency and time window.

This is a frequency domain analog of PCA over signals at a given frequency/time window.

Parameters:

max_rank (int, optional) – The number of components to keep (like the number of PC dimensions)

Returns:

• global_coherence (ndarray, shape (n_time_windows,) – n_fft_samples,

  n_components)

  The vector of global coherences (square of the singular values)

• unnormalized_global_coherence (ndarray, shape (n_time_windows, n_fft_samples, n_signals, n_components)) – The (unnormalized) global coherence vectors

References

[1]

Cimenser, A., Purdon, P.L., Pierce, E.T., Walsh, J.L., Salazar-Gomez, A.F., Harrell, P.G., Tavares-Stoeckel, C., Habeeb, K., and Brown, E.N. (2011). Tracking brain states under general anesthesia by using global coherence analysis. Proceedings of the National Academy of Sciences 108, 8832–8837.

group_delay(frequencies_of_interest=None, frequency_resolution=None, significance_threshold=0.05)

The average time-delay of a broadband signal.

Parameters:

• frequencies_of_interest (array-like, shape (2,)) –

• frequencies (array-like, shape (n_fft_samples,)) –

• frequency_resolution (float) –

Returns:

• delay (array, shape (…, n_signals, n_signals))

• slope (array, shape (…, n_signals, n_signals))

• r_value (array, shape (…, n_signals, n_signals))

References

[1]

Gotman, J. (1983). Measurement of small time differences between EEG channels: method and application to epileptic seizure propagation. Electroencephalography and Clinical Neurophysiology 56, 501-514.

imaginary_coherence()

The normalized imaginary component of the cross-spectrum.

Projects the cross-spectrum onto the imaginary axis to mitigate the effect of volume-conducted dependencies. Assumes volume-conducted sources arrive at sensors at the same time, resulting in a cross-spectrum with phase angle of 0 (perfectly in-phase) or pi (anti-phase) if the sensors are on opposite sides of a dipole source. With the imaginary coherence, in-phase and anti-phase associations are set to zero.

Returns:

imaginary_coherence_magnitude

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Nolte, G., Bai, O., Wheaton, L., Mari, Z., Vorbach, S., and Hallett, M. (2004). Identifying true brain interaction from EEG data using the imaginary part of coherency. Clinical Neurophysiology 115, 2292-2307.

property n_observations

Number of observations

pairwise_phase_consistency()

The square of the phase locking value corrected for the positive bias induced by using the magnitude of the complex cross-spectrum.

Returns:

phase_locking_value

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Vinck, M., van Wingerden, M., Womelsdorf, T., Fries, P., and Pennartz, C.M.A. (2010). The pairwise phase consistency: A bias-free measure of rhythmic neuronal synchronization. NeuroImage 51, 112-122.

pairwise_spectral_granger_prediction()

The amount of power at a node in a frequency explained by (is predictive of) the power at other nodes.

Also known as spectral granger causality.

References

[1]

Geweke, J. (1982). Measurement of Linear Dependence and Feedback Between Multiple Time Series. Journal of the American Statistical Association 77, 304.

partial_directed_coherence(keep_cupy=False)

The transfer function coupling strength normalized by its strength of coupling to other signals (outflow).

The partial directed coherence tries to regress out the influence of other observed signals, leaving only the direct coupling between two signals.

Returns:

partial_directed_coherence

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Baccala, L.A., and Sameshima, K. (2001). Partial directed coherence: a new concept in neural structure determination. Biological Cybernetics 84, 463-474.

phase_lag_index()

A non-parametric synchrony measure designed to mitigate power differences between realizations (tapers, trials) and volume-conduction.

The phase lag index is the average sign of the imaginary component of the cross-spectrum. The imaginary component sets in-phase or anti-phase signals to zero and the sign scales it to have the same magnitude regardless of phase.

Note that this is the signed version of the phase lag index. In order to obtain the unsigned version, as in [1], take the absolute value of this quantity.

Returns:

phase_lag_index

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Stam, C.J., Nolte, G., and Daffertshofer, A. (2007). Phase lag index: Assessment of functional connectivity from multi channel EEG and MEG with diminished bias from common sources. Human Brain Mapping 28, 1178-1193.

phase_locking_value()

The cross-spectrum with the power for each signal scaled to a magnitude of 1.

The phase locking value attempts to mitigate power differences between realizations (tapers or trials) by treating all values of the cross-spectrum as the same power. This has the effect of downweighting high power realizations and upweighting low power realizations.

Returns:

phase_locking_value

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Lachaux, J.-P., Rodriguez, E., Martinerie, J., Varela, F.J., and others (1999). Measuring phase synchrony in brain signals. Human Brain Mapping 8, 194-208.

phase_slope_index(frequencies_of_interest=None, frequency_resolution=None)

The weighted average of slopes of a broadband signal projected onto the imaginary axis.

The phase slope index finds the complex weighted average of the coherency between frequencies where the weights correspond to the magnitude of the coherency at that frequency. This is projected on to the imaginary axis to avoid volume conduction effects.

Parameters:

• frequencies_of_interest (array-like, shape (2,)) –

• frequencies (array-like, shape (n_fft_samples,)) –

• frequency_resolution (float) –

Returns:

phase_slope_index

Return type:

array, shape (…, n_signals, n_signals)

References

[1]

Nolte, G., Ziehe, A., Nikulin, V.V., Schlogl, A., Kramer, N., Brismar, T., and Muller, K.-R. (2008). Robustly Estimating the Flow Direction of Information in Complex Physical Systems. Physical Review Letters 100.

power()

Power of the signal. Only returns the non-negative frequencies

weighted_phase_lag_index()

Weighted average of the phase lag index using the imaginary coherency magnitudes as weights.

Returns:

weighted_phase_lag_index

Return type:

array, shape (…, n_fft_samples, n_signals, n_signals)

References

[1]

Vinck, M., Oostenveld, R., van Wingerden, M., Battaglia, F., and Pennartz, C.M.A. (2011). An improved index of phase-synchronization for electrophysiological data in the presence of volume-conduction, noise and sample-size bias. NeuroImage 55, 1548-1565.