spectral_connectivity.connectivity.Connectivity

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

Bases: object

Compute functional and directed connectivity measures from spectral data.

This class provides a comprehensive suite of connectivity analysis methods based on cross-spectral matrices derived from Fourier-transformed time series. Methods range from basic coherence to advanced Granger causality measures.

Parameters:

• fourier_coefficients (NDArray[complexfloating],) – shape (n_time_windows, n_trials, n_tapers, n_frequencies, n_signals) Complex-valued Fourier coefficients from spectral analysis. Must be two-sided (positive and negative frequencies) for Granger methods. Usually obtained from multitaper or other spectral estimation methods. Validation: Must be 5-dimensional with at least 2 signals and contain only finite values (no NaN/Inf).

• expectation_type ({"trials_tapers", "trials", "tapers", "time",) – “time_trials”, “time_tapers”, “time_trials_tapers”}, default=”trials_tapers” Specifies how to average the cross-spectral matrix: - “trials_tapers”: average over trials and tapers (most common) - “trials”: average over trials only (keep taper dimension) - “tapers”: average over tapers only (keep trial dimension) - “time”: average over time windows - combinations: average over multiple dimensions

• frequencies (NDArray[floating], shape (n_frequencies,), optional) – Frequency values in Hz corresponding to FFT bins. If None, uses normalized frequencies.

• time (NDArray[floating], shape (n_time_windows,), optional) – Time values in seconds for each time window. If None, uses indices.

• blocks (int, optional) –

  Number of blocks for memory-efficient computation of large connectivity matrices. When specified, the cross-spectral matrix is computed in chunks rather than all at once, reducing peak memory usage.

  When to use blocks:

  • Large number of signals (n_signals >= 50, as a rough guideline; benefit increases with more signals)

  • Memory-constrained environments

  • High-resolution spectrograms (large n_time_windows × n_frequencies)

  • GPU computing with limited VRAM

  When NOT to use blocks:

  • Small datasets (n_signals < 50): The overhead of block management may exceed the memory benefit, making blocks=None faster

  • When speed is critical and memory is abundant

  Memory-Speed Tradeoff:

  • Without blocks (default): Fastest for small datasets, but requires memory for full (n_time_windows × n_frequencies × n_signals × n_signals) array

  • With blocks: Reduces peak memory by 70-80% for large arrays (measured 73% reduction for n_signals=50, blocks=5), with minimal speed penalty (typically <10%)

  Quick Decision Guide:

  • n_signals < 50: Use default (blocks=None)

  • 50 ≤ n_signals < 100: Use blocks=5 if memory is limited

  • n_signals ≥ 100: Recommended blocks=5 or blocks=10

  • Out of memory errors: Increase blocks value (try doubling)

  Important: Results are numerically identical whether using blocks or not (validated to floating-point precision).

• dtype (np.dtype, default=complex128) – Data type for internal computations. Should match input precision.

n_observations

Effective number of independent observations after averaging, used for statistical inference.

Type:

int

Examples

>>> import numpy as np
>>> from spectral_connectivity import Connectivity
>>> # Simulate coherent signals
>>> n_times, n_trials, n_tapers, n_freqs, n_signals = 50, 10, 5, 100, 2
>>> # Create complex coefficients with some coherence
>>> phase_diff = np.pi/4  # 45 degree phase difference
>>> coeffs = np.random.randn(n_times, n_trials, n_tapers, n_freqs, n_signals) +     ...          1j * np.random.randn(n_times, n_trials, n_tapers, n_freqs, n_signals)
>>> # Add coherence at specific frequencies
>>> coeffs[:, :, :, 10, 1] = coeffs[:, :, :, 10, 0] * np.exp(1j * phase_diff)
>>>
>>> # Compute connectivity
>>> conn = Connectivity(coeffs, expectation_type="trials_tapers")
>>> coherence = conn.coherence_magnitude()  # Shape: (n_times, n_freqs, 2, 2)
>>> phase_lag = conn.coherence_phase()
>>> print(f"Coherence shape: {coherence.shape}")
>>> print(f"Peak coherence: {np.max(coherence[:, 10, 0, 1]):.3f}")

Notes

The class supports both CPU (NumPy) and GPU (CuPy) computation depending on the SPECTRAL_CONNECTIVITY_ENABLE_GPU environment variable. For Granger causality measures, minimum phase decomposition [1] is used to estimate transfer functions and noise covariances non-parametrically.

References

[1]

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

[2]

Bastos, A. M., & Schoffelen, J. M. (2016). A tutorial review of functional connectivity analysis methods and their interpretational pitfalls. Frontiers in systems neuroscience, 9, 175.

Attributes:

all_frequencies

Return positive and negative frequencies of the transform.

frequencies

Return non-negative frequencies of the transform.

n_observations

Return number of observations.

Methods

blockwise_spectral_granger_prediction()	Raise NotImplementedError for blockwise spectral Granger prediction.
canonical_coherence(group_labels)	Find the maximal coherence between each combination of groups.
coherence_magnitude()	Return the magnitude squared of the complex coherency.
coherence_phase()	Return the phase angle of the complex coherency.
coherency()	Return the complex-valued linear association between time series.
conditional_spectral_granger_prediction()	Raise NotImplementedError for conditional spectral Granger prediction.
debiased_squared_phase_lag_index()	Return square of phase lag index corrected for positive bias.
debiased_squared_weighted_phase_lag_index()	Return square of weighted phase lag index corrected for bias.
delay([frequencies_of_interest, ...])	Find a range of possible delays from the coherence phase.
direct_directed_transfer_function()	Return combination of directed transfer function and partial coherence.
directed_coherence()	Return transfer function coupling strength normalized by inflow.
directed_transfer_function()	Return transfer function coupling strength normalized by inflow.
from_multitaper(multitaper_instance[, ...])	Construct connectivity class using a multitaper instance.
generalized_partial_directed_coherence()	Return generalized partial directed coherence.
global_coherence([max_rank])	Find linear combinations that capture the most coherent power.
group_delay([frequencies_of_interest, ...])	Return the average time-delay of a broadband signal.
imaginary_coherence()	Return the normalized imaginary component of the cross-spectrum.
pairwise_phase_consistency()	Return square of phase locking value corrected for bias.
pairwise_spectral_granger_prediction()	Return amount of power at a node explained by other nodes.
partial_directed_coherence([keep_cupy])	Return transfer function coupling strength normalized by outflow.
phase_lag_index()	Return non-parametric synchrony measure mitigating power differences.
phase_locking_value()	Return the cross-spectrum with power scaled to magnitude 1.
phase_slope_index([frequencies_of_interest, ...])	Return weighted average of slopes projected onto imaginary axis.
power()	Return power of the signal.
subset_pairwise_spectral_granger_prediction(pairs)	Return predictive power for a subset of signal pairs.
weighted_phase_lag_index()	Return weighted average of phase lag index using imaginary coherency magnitudes.

Methods

blockwise_spectral_granger_prediction	Raise NotImplementedError for blockwise spectral Granger prediction.
canonical_coherence	Find the maximal coherence between each combination of groups.
coherence_magnitude	Return the magnitude squared of the complex coherency.
coherence_phase	Return the phase angle of the complex coherency.
coherency	Return the complex-valued linear association between time series.
conditional_spectral_granger_prediction	Raise NotImplementedError for conditional spectral Granger prediction.
debiased_squared_phase_lag_index	Return square of phase lag index corrected for positive bias.
debiased_squared_weighted_phase_lag_index	Return square of weighted phase lag index corrected for bias.
delay	Find a range of possible delays from the coherence phase.
direct_directed_transfer_function	Return combination of directed transfer function and partial coherence.
directed_coherence	Return transfer function coupling strength normalized by inflow.
directed_transfer_function	Return transfer function coupling strength normalized by inflow.
from_multitaper	Construct connectivity class using a multitaper instance.
generalized_partial_directed_coherence	Return generalized partial directed coherence.
global_coherence	Find linear combinations that capture the most coherent power.
group_delay	Return the average time-delay of a broadband signal.
imaginary_coherence	Return the normalized imaginary component of the cross-spectrum.
pairwise_phase_consistency	Return square of phase locking value corrected for bias.
pairwise_spectral_granger_prediction	Return amount of power at a node explained by other nodes.
partial_directed_coherence	Return transfer function coupling strength normalized by outflow.
phase_lag_index	Return non-parametric synchrony measure mitigating power differences.
phase_locking_value	Return the cross-spectrum with power scaled to magnitude 1.
phase_slope_index	Return weighted average of slopes projected onto imaginary axis.
power	Return power of the signal.
subset_pairwise_spectral_granger_prediction	Return predictive power for a subset of signal pairs.
weighted_phase_lag_index	Return weighted average of phase lag index using imaginary coherency magnitudes.

Attributes

all_frequencies	Return positive and negative frequencies of the transform.
frequencies	Return non-negative frequencies of the transform.
n_observations	Return number of observations.

property all_frequencies: ndarray[tuple[int, ...], dtype[floating]] | None

Return positive and negative frequencies of the transform.

Returns:

All frequency values including negative frequencies.

Return type:

NDArray[floating], shape (n_frequencies,)

blockwise_spectral_granger_prediction() → None

Raise NotImplementedError for blockwise spectral Granger prediction.

Raises:

NotImplementedError – This method is not yet implemented.

canonical_coherence(group_labels: ndarray[tuple[int, ...], dtype[integer]]) → tuple[ndarray[tuple[int, ...], dtype[floating]], ndarray[tuple[int, ...], dtype[integer]]]

Find 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 maximal coherence for each group pair.

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

Notes

Range: [0, 1]. Maximal coherence values are bounded like coherence magnitude.

References

[1]

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

coherence_magnitude() → ndarray[tuple[int, ...], dtype[floating]]

Return 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 be bounded by 0 and 1.

Returns:

magnitude – Magnitude-squared coherence values.

Return type:

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

Notes

Range: [0, 1]. Implementation may produce tiny numerical excursions beyond bounds due to floating-point precision.

References

[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.

coherence_phase() → ndarray[tuple[int, ...], dtype[floating]]

Return the phase angle of the complex coherency.

Returns:

phase – Phase angles in radians.

Return type:

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

Notes

Range: [−π, π]. Phase angles in radians for complex coherency.

coherency() → ndarray[tuple[int, ...], dtype[complexfloating]]

Return the complex-valued linear association between time series.

Computed in the frequency domain.

Returns:

complex_coherency – Complex coherency between all signal pairs.

Return type:

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

Notes

Range: Magnitude |C_{xy}(f)| ∈ [0, 1]; phase ∈ [−π, π]. Values lie in the unit disk of the complex plane.

conditional_spectral_granger_prediction() → None

Raise NotImplementedError for conditional spectral Granger prediction.

Raises:

NotImplementedError – This method is not yet implemented.

debiased_squared_phase_lag_index() → ndarray[tuple[int, ...], dtype[floating]]

Return square of phase lag index corrected for positive bias.

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 – Debiased squared phase lag index values.

Return type:

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

Notes

Range: [0, 1]. Bias-corrected version of squared phase lag index.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return square of weighted phase lag index corrected for bias.

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 – Shape (…, n_fft_samples, n_signals, n_signals). Debiased squared weighted phase lag index values.

Return type:

array

Notes

Range: [0, 1]. Bias-corrected weighted phase lag index squared.

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: ndarray[tuple[int, ...], dtype[floating]] | None = None, frequency_resolution: float | None = None, significance_threshold: float = 0.05, n_range: int = 3) → ndarray[tuple[int, ...], dtype[floating]]

Find a range of possible delays from the coherence phase.

The delay (and phase) at each frequency is indistinguishable from 2π 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,), optional) – Frequency band of interest.

• frequency_resolution (float, optional) – Frequency resolution for independent samples.

• significance_threshold (float, default=0.05) – P-value threshold for significance.

• n_range (int, default=3) – Number of phases to consider.

Returns:

possible_delays – Shape (…, n_frequencies, (n_range * 2) + 1, n_signals, n_signals). Array of possible delay values.

Return type:

array

direct_directed_transfer_function() → ndarray[tuple[int, ...], dtype[floating]]

Return combination of directed transfer function and partial coherence.

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 – Shape (…, n_fft_samples, n_signals, n_signals). Direct directed transfer function values.

Return type:

array

Notes

Range: [0, 1]. Normalized combination of DTF and partial coherence.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return transfer function coupling strength normalized by inflow.

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 – Directed coherence values.

Return type:

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

Notes

Range: [0, 1]. Normalized directional connectivity measure.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return transfer function coupling strength normalized by inflow.

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 – Shape (…, n_fft_samples, n_signals, n_signals). Directed transfer function values.

Return type:

array

Notes

Range: [0, 1] (normalized). Represents proportion of inflow via transfer function.

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: ndarray[tuple[int, ...], dtype[floating]] | None

Return non-negative frequencies of the transform.

Returns:

Non-negative frequency values.

Return type:

NDArray[floating], shape (n_frequencies,)

classmethod from_multitaper(multitaper_instance: Multitaper, expectation_type: str = 'trials_tapers', blocks: int | None = None, dtype: ~typing.Any = <class 'numpy.complex128'>) → Connectivity

Construct connectivity class using a multitaper instance.

Parameters:

• multitaper_instance (Multitaper) – Instance of Multitaper class.

• expectation_type (str, default="trials_tapers") – How to average the cross-spectral matrix.

• blocks (int, optional) – Number of blocks for computation.

• dtype (np.dtype, default=complex128) – Data type for computations.

Returns:

New Connectivity instance.

Return type:

Connectivity

generalized_partial_directed_coherence() → ndarray[tuple[int, ...], dtype[floating]]

Return 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 – Shape (…, n_fft_samples, n_signals, n_signals). Generalized partial directed coherence values.

Return type:

array

Notes

Range: [0, 1]. Normalized, scaled by noise variance.

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: int = 1) → tuple[ndarray[tuple[int, ...], dtype[floating]], ndarray[tuple[int, ...], dtype[complexfloating]]]

Find linear combinations that capture the most coherent power.

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, default=1) – 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.

Notes

Range: [0, ∞). Global coherence values are non-negative with no finite upper bound (squared singular values).

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: ndarray[tuple[int, ...], dtype[floating]] | None = None, frequency_resolution: float | None = None, significance_threshold: float = 0.05) → tuple[ndarray[tuple[int, ...], dtype[floating]], ndarray[tuple[int, ...], dtype[floating]], ndarray[tuple[int, ...], dtype[floating]]]

Return the average time-delay of a broadband signal.

Parameters:

• frequencies_of_interest (array-like, shape (2,), optional) – Frequency band of interest.

• frequency_resolution (float, optional) – Frequency resolution for independent samples.

• significance_threshold (float, default=0.05) – P-value threshold for significance.

Returns:

• delay (array, shape (…, n_signals, n_signals)) – Time delays between signal pairs.

• slope (array, shape (…, n_signals, n_signals)) – Slope of phase vs frequency.

• r_value (array, shape (…, n_signals, n_signals)) – Correlation coefficient of linear fit.

Notes

Range: (−∞, ∞). Time delays can be positive or negative.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return 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 π (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 – Shape (…, n_fft_samples, n_signals, n_signals). Imaginary coherence magnitudes.

Return type:

array

Notes

Range: [0, 1]. Magnitude version of imaginary part of coherency. Raw imaginary component ranges in [-1, 1].

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: int

Return number of observations.

Returns:

Effective number of independent observations after averaging.

Return type:

int

pairwise_phase_consistency() → ndarray[tuple[int, ...], dtype[floating]]

Return square of phase locking value corrected for bias.

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 – Pairwise phase consistency values.

Return type:

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

Notes

Range: [0, 1]. Unbiased phase consistency measure.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return amount of power at a node explained by other nodes.

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.

Returns:

Spectral Granger prediction values.

Return type:

array

Notes

Range: [0, ∞). Non-negative values with no finite upper bound. Output [i,j] corresponds to causal influence j → i.

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: bool = False) → ndarray[tuple[int, ...], dtype[floating]]

Return transfer function coupling strength normalized by outflow.

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.

Parameters:

keep_cupy (bool, default=False) – Whether to keep arrays as CuPy arrays.

Returns:

partial_directed_coherence – Shape (…, n_fft_samples, n_signals, n_signals). Partial directed coherence values.

Return type:

array

Notes

Range: [0, 1]. Normalized direct coupling measure.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return non-parametric synchrony measure mitigating power differences.

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 – Phase lag index values for all signal pairs.

Return type:

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

Notes

Range: [-1, 1] (signed version). For unsigned version (as in [1]), take absolute value to get range [0, 1].

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() → ndarray[tuple[int, ...], dtype[floating]]

Return the cross-spectrum with power scaled to magnitude 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 – Phase locking values between all signal pairs.

Return type:

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

Notes

Range: [0, 1]. 0 indicates random phases; 1 indicates constant phase difference.

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: ndarray[tuple[int, ...], dtype[floating]] | None = None, frequency_resolution: float | None = None) → ndarray[tuple[int, ...], dtype[floating]]

Return weighted average of slopes projected onto 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,), optional) – Frequency band of interest.

• frequency_resolution (float, optional) – Frequency resolution for independent samples.

Returns:

phase_slope_index – Phase slope index values.

Return type:

array, shape (…, n_signals, n_signals)

Notes

Range: (−∞, ∞). Signed directional measure with no bounds.

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() → ndarray[tuple[int, ...], dtype[floating]]

Return power of the signal.

Only returns the non-negative frequencies.

Returns:

Power spectral density for non-negative frequencies.

Return type:

NDArray[floating]

Notes

Range: [0, ∞). Power spectral density is always non-negative with no finite upper bound.

subset_pairwise_spectral_granger_prediction(pairs: list | ndarray[tuple[int, ...], dtype[integer]]) → ndarray[tuple[int, ...], dtype[floating]]

Return predictive power for a subset of signal pairs.

Parameters:

pairs (array_like) – Pairs of signal indices.

Returns:

Spectral Granger prediction for specified pairs.

Return type:

array

weighted_phase_lag_index() → ndarray[tuple[int, ...], dtype[floating]]

Return weighted average of phase lag index using imaginary coherency magnitudes.

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

Returns:

weighted_phase_lag_index – Shape (…, n_fft_samples, n_signals, n_signals). Weighted phase lag index values.

Return type:

array

Notes

Range: [0, 1]. Weighted by imaginary coherency magnitude.

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.