pyhctsa.operations.spectral.spectral_time_freq

pyhctsa.operations.spectral.spectral_time_freq(y, num_windows=20)

Time-varying spectral statistics from a spectrogram.

spectral_summaries computes statistics from a single, static spectral estimate of the whole time series. This function instead divides the series into overlapping windows and tracks how the spectral content changes across them:

  • The spectral kurtosis (Antoni 2006) is the kurtosis, across windows, of the power in each frequency bin. High values flag a frequency band whose energy is concentrated in occasional bursts rather than spread evenly over time (e.g., a transient, impulsive fault).

  • The spectral entropy of the power spectrum is computed separately in each window, giving one entropy value per window. Variation in this sequence flags a time series whose spectral character is not stationary.

Each window is a Hamming window of max(8, round(N/num_windows)) samples with 50% overlap, so about 2*num_windows - 1 windows result.

Parameters:
y : array-like

The input time series.

num_windows : int, optional

Sets the window length to N/num_windows samples (at least 8), with 50% overlap. If fewer than 4 windows fit, the output is NaN. Default is 20.

Returns:

  • sk_max, sk_mean, sk_std, sk_range: maximum, mean, standard deviation and range, over frequencies, of the spectral kurtosis.

  • sk_fracAboveThresh: the fraction of frequencies whose spectral kurtosis exceeds the 95% Gaussian-null threshold (non-Gaussian, bursty behavior).

  • sk_freqAtMax: the angular frequency, in radians per sample (2*pi times the frequency in cycles per sample, from 0 to pi, matching spectral_summaries), at which the spectral kurtosis is largest.

  • sk_relSpread: the relative spread of power across windows: the mean over frequencies of the standard deviation across windows of the power in each frequency bin, divided by the mean over frequencies of the mean power across windows. A dimensionless coefficient of variation of the power, independent of the variance of the series and of the window length (about 1 for white noise).

  • se_mean, se_std, se_max, se_min, se_range: mean, standard deviation, maximum, minimum and range, over windows, of the spectral entropy of each window’s power spectrum: the Shannon entropy (base 2) of the one-sided relative power across frequency bins, divided by its maximum, log2 of the number of bins, so each window’s value lies in [0, 1]: 1 for a flat (white) spectrum, near 0 for a spectrum concentrated in a single frequency bin.

Return type:

dict or float

Notes

Everything is computed from a one-sided power spectrogram of the series.