pyhctsa.operations.spectral.envelope_stats

pyhctsa.operations.spectral.envelope_stats(y, power_frac=0.5, trim_frac=0.05)

Statistics of the amplitude envelope of the full series and of its dominant oscillation.

Computes the instantaneous amplitude envelope |z(t)| of the analytic signal z(t) = y(t) + i H[y](t) (H the Hilbert transform) for (a) the full series and (b) the dominant band: the narrowest frequency band centered on the largest periodogram peak (DC and Nyquist bins excluded) that holds a fraction power_frac of the total power, and at least 2 bins either side of the peak. Its width therefore adapts to the series: it is the width of the dominant peak for a narrowband oscillation, and a large part of the spectrum for broadband noise. Each analytic signal comes from the FFT, zeroing the bins outside the band.

The envelope summaries describe amplitude modulation: how variable the envelope is (coefficient of variation), how asymmetric and heavy-tailed its distribution is (kurtosis for the full series; skewness and kurtosis for the dominant band), and how long it takes to decorrelate (the 1/e timescale of its autocorrelation function). An unmodulated sinusoid has a constant envelope (CV near 0); bursting or amplitude-modulated signals have a large CV, and a high kurtosis for intermittent bursts.

Baseline for Gaussian noise: the analytic signal of a stationary Gaussian process is complex Gaussian, so its envelope is Rayleigh distributed: CV = sqrt(4/pi - 1) = 0.5227, skewness 0.6311, kurtosis 3.2451. Values of the CV below this indicate an envelope steadier than noise (e.g., a sinusoid in noise follows a Rice distribution), and above it an envelope more modulated than noise.

To limit edge effects (the FFT filter is circular, so the series ends wrap around), trim_frac of the samples are dropped from each end of the envelope and phase before any summary is computed. Timescales are in samples.

Parameters:
y : array-like

The input time series.

power_frac : float, optional

The fraction of the total (one-sided, DC and Nyquist excluded) spectral power that the dominant band, centered on the largest periodogram peak, must contain. Default is 0.5.

trim_frac : float, optional

The fraction of samples dropped from each end of the analytic signal before computing summaries. Default is 0.05.

Returns:

  • full_cv: the envelope’s coefficient of variation (standard deviation over mean), full series.

  • full_kurt: the envelope’s kurtosis, full series.

  • full_tau: the 1/e decay time (in samples) of the envelope’s autocorrelation function, full series.

  • dom_cv, dom_skew (the envelope’s skewness), dom_kurt, dom_tau: as above for the dominant band.

  • dom_ifspread: a robust spread of the dominant band’s instantaneous frequency (1.4826 times the median absolute deviation of the phase increments, in cycles per sample).

All fields are NaN for constant, non-finite, or very short (N < 50) series. A 1/e timescale is NaN when the autocorrelation never falls below 1/e within N/2 lags. For an essentially constant envelope (as for a sinusoid without noise) the skewness, kurtosis and timescale are an undefined 0/0; they are set by convention to skewness 0, kurtosis 3 (the Gaussian values) and a timescale of the largest lag searched, n // 2 for the n samples left after trimming, each shrunk toward that value with weight w = c^2 / (c^2 + 1e-20) where c is the envelope’s CV, so the reported values vary continuously with c.

Return type:

dict

References

B. Boashash, “Estimating and interpreting the instantaneous frequency of a signal. I. Fundamentals”, Proc. IEEE 80(4), 520-538 (1992).