pyhctsa.operations.spectral.bicoherence¶

pyhctsa.operations.spectral.bicoherence(y, seg_length=64, max_n='full', num_surr=100)¶

Quadratic phase coupling between frequencies, from the squared bicoherence.

Estimates the bicoherence, a normalized bispectrum, by segment averaging: the series is split into overlapping segments (50% overlap, as many as fit), each segment is demeaned, Hamming-windowed and Fourier transformed, and the per-segment Fourier coefficients are combined into the bispectrum estimate B(f1,f2) = <X(f1) X(f2) X*(f1+f2)>, averaged over segments. The squared bicoherence is bic2(f1,f2) = |B(f1,f2)|^2 / (<|X(f1)X(f2)|^2> <|X(f1+f2)|^2>), bounded in [0, 1] by the Cauchy-Schwarz inequality.

Time-domain nonlinearity statistics (e.g., tc3, the ramping-window asymmetry of ramping_windows) collapse all frequency structure into a single number per lag, so nonlinear coupling localized to a specific pair of frequency bands can average out to near zero. The bicoherence resolves quadratic phase coupling per frequency pair, directly detecting whether energy at f1 and f2 is phase-coupled to energy at f1+f2 (the frequency-domain signature of a quadratic nonlinearity).

Parameters:¶

y : array-like¶

The input time series.

seg_length : int, optional¶

The length (in samples) of each FFT segment (at least 16). Segments overlap by 50% and as many as fit are averaged; the number of segments K sets the variance of the bicoherence estimate. Fewer than 8 segments gives NaN. Default is 64.

max_n : int or 'full', optional¶

The maximum number of samples to consider: longer series are cropped to their first max_n points. 'full' disables cropping. Default is 'full'.

num_surr : int, optional¶

The number of random-phase surrogates (which preserve the power spectrum but destroy phase coupling) used to calibrate the significance threshold empirically, in place of its asymptotic approximation. The threshold is the 95% quantile of squared bicoherence values pooled across all frequency pairs and all surrogates (the threshold of a few tens of surrogates depends on which were drawn). Default is 100.

Returns:¶

• meanBic, maxBic, stdBic, skewBic: mean, maximum, standard deviation and skewness of the squared bicoherence over the non-redundant principal domain of frequency pairs (0 < f1 <= f2, f1 + f2 <= Nyquist).

• entropy: the Shannon entropy of the bicoherence surface, normalized to [0, 1] by the uniform-distribution entropy: whether coupling is concentrated in a few frequency pairs or diffuse across many.

• meanBicDiag: the mean squared bicoherence on the self-coupling diagonal f1 = f2 (quadratic harmonic distortion).

• propSig: the proportion of frequency pairs exceeding the surrogate-calibrated 95% significance threshold.

• threshRatio: the ratio of that empirical threshold to the standard analytic large-K approximation (K * bic2 ~ Exp(1) under the null of a linear, ~Gaussian process, giving threshold -log(0.05)/K). A ratio far from 1 flags that the asymptotic approximation is untrustworthy for this series (e.g., because of non-stationarity).

NaN is returned if the series is too short for 8 segments.

Return type:¶

dict or float

Notes

The random-phase surrogates are generated with hctsa’s portable generator (pyhctsa.robust.bf_random()) at seed 0, as in hctsa’s SD_MakeSurrogates ('RP'), so the output is reproducible.