cogpy.spectral.bivariate

Bivariate spectral measures: cross-spectrum, coherence, PLV.

Status

STATUS: ACTIVE Reason: Multitaper cross-spectral measures for iEEG connectivity analysis. Superseded by: n/a Safe to remove: no

Design

All functions operate on pre-computed tapered FFTs (mtfft) rather than raw signals. The caller computes mtfft once via multitaper_fft() and passes it to whichever measures are needed — avoiding redundant FFT computation when multiple measures are derived from the same data.

Tapered FFT convention (from multitaper_fft):

mtfft : (…, taper, freq) complex128

Connectivity functions take two mtfft arrays (x and y) with matching shapes except possibly in leading batch dims. All measures average across the taper axis (-2) to produce estimates with K degrees of freedom, where K = number of tapers.

Output shapes:

cross_spectrum : (…, freq) complex coherence : (…, freq) real [0, 1] plv : (…, freq) real [0, 1] mtm_fstat : (…,) real (scalar per channel)

Functions

coherence(mtfft_x, mtfft_y)

Multitaper magnitude squared coherence (MSC).

coherence_matrix(X, fs, nperseg, *[, NW, ...])

Pairwise magnitude-squared coherence across channels (fast multitaper).

coherency(mtfft_x, mtfft_y)

Complex multitaper coherency (keeps the phase).

coherency_matrix(X, fs, nperseg, *[, NW, ...])

Pairwise complex coherency across channels — keeps the phase.

cross_corr_lag(x, y, *[, axis, fs])

Lag at peak cross-correlation between signals x and y.

cross_corr_peak(x, y, *[, axis, normalize])

Peak cross-correlation between signals x and y.

cross_spectral_matrix(X, fs, nperseg, *[, ...])

Multitaper cross-spectral (covariance) matrix across channels.

cross_spectrum(mtfft_x, mtfft_y)

Multitaper cross-spectral density estimate.

ged_spatial_filter(s_signal, s_reference, *)

Generalized-eigendecomposition spatial filter from a signal/reference contrast.

leading_eigenfraction(S)

Dominant spatial-mode fraction per frequency of a cross-spectral matrix.

leading_eigenfraction_null(n_ch, n_eff)

Marchenko-Pastur upper-edge null for leading_eigenfraction().

mtm_fstat(mtfft, fs, N, *, f0)

Multitaper F-statistic test for a sinusoidal component at f0.

pac_modulation_index(pha, amp, *[, n_bins])

Phase-Amplitude Coupling (PAC) via Modulation Index (Tort et al. 2010).

plv(mtfft_x, mtfft_y)

Phase Locking Value (PLV) via multitaper estimates.

spectral_granger(x, y, fs, *[, axis, direction])

Spectral Granger causality between signals x and y.