pyhctsa.operations.spectral.cross_frequency_coupling

pyhctsa.operations.spectral.cross_frequency_coupling(y, n_bands=5, max_n='full', n_phase_bins=18, max_lag_frac=0.1)

Cross-frequency coupling between equal-width frequency bands: phase-amplitude and amplitude-amplitude.

Cross-frequency coupling is an interaction between the activity in two frequency bands [1], [2]. This operation measures its two most common kinds, from the same band decomposition:

  • Phase-amplitude coupling: the amplitude of a faster band depends on the phase of a slower one. It is measured by Tort et al.’s modulation index [3]: the normalized divergence from uniform of the faster band’s mean amplitude across bins of the slower band’s phase.

  • Amplitude-amplitude coupling: co-modulation of the amplitude envelopes of two bands. Its standard estimator is the amplitude envelope correlation (AEC) [4]: the correlation between the two bands’ Hilbert envelopes. Envelopes can also be coupled with a delay, the slower band’s loudness leading the faster’s, or vice versa, so the envelope cross-correlation is also read over a range of lags, taking its peak [5], [6].

The spectrum is split into n_bands contiguous bands of equal width (DC and Nyquist excluded), and each band’s analytic signal is computed in one step by the FFT-domain Hilbert transform. Every pair of bands, adjacent bands included, is scanned.

For amplitude-amplitude coupling, 5% of samples are trimmed from each end of the envelopes (the FFT band filter is circular), each envelope is z-scored, and the envelope cross-correlation r(k) = mean_t A_i(t) A_j(t+k) is computed at lags |k| <= K = max_lag_frac * N. The peak of r(k) over many lags and pairs grows with the number of lags scanned even with no coupling, so zAEC scores it against a null of independent envelopes. Bartlett’s formula [7] gives the variance of a cross-correlation between two independent autocorrelated series, var r = (1/m) sum_j rho_i(j) rho_j(j) (each envelope’s autocorrelation rho truncated at its first non-positive value), and the number of effectively independent lags in the scan is (2K + 1) / w, with w = T_i T_j / B the correlation length of r(k) over lags (T = integrated autocorrelation time, B = Bartlett’s sum). A Sidak correction for the maximum over these effective lags, and then over band pairs, maps the peak z back to a standard-normal score.

For a stationary linear Gaussian process, the envelopes of disjoint bands are asymptotically independent, so the amplitude-amplitude outputs measure a fourth-order nonlinearity. They respond to any co-modulation of band envelopes, including broadband transients and static nonlinear transforms of a linear process, not only to coupling between distinct rhythms [8].

References

Parameters:
y : array-like

The input time series.

n_bands : int, optional

The number of equal-width frequency bands to split the spectrum into (default: 5, matching spectral_summaries()’ 5-band split). All comb(n_bands, 2) band pairs are scanned; for phase-amplitude coupling, phase is taken from the slower band of each pair and amplitude from the faster.

max_n : int or str, optional

The maximum number of samples to consider; longer series are cropped to their first max_n points. Can be 'full' to disable cropping (default).

n_phase_bins : int, optional

The number of phase bins used to estimate each band pair’s modulation index (default: 18, i.e. 20-degree bins, the standard choice from Tort et al. 2010).

max_lag_frac : float, optional

The largest envelope lag scanned for amplitude-amplitude coupling, as a fraction of the series length (default: 0.1). It is capped at a quarter of the trimmed length.

Returns:

Phase-amplitude coupling:

  • maxMI: the maximum modulation index across all band pairs – the comodulogram peak, i.e. whether any band pair shows real coupling.

  • entropyMI: the normalized Shannon entropy of the MI values across pairs (0 = coupling concentrated in a single band pair, 1 = uniformly diffuse across all pairs).

Amplitude-amplitude coupling:

  • maxAEC0: the largest absolute zero-lag envelope correlation over band pairs (the classical AEC).

  • maxAEC: the largest envelope cross-correlation over band pairs and lags (the effect size).

  • zAEC: the peak’s standard-normal score against independent envelopes, corrected for the number of effective lags and of band pairs (about 1-1.5 for a linear Gaussian process at any length).

Returns NaN if the time series is constant or too short for the requested number of bands.

Return type:

dict