pyhctsa.operations.spectral.specparam

pyhctsa.operations.spectral.specparam(y, aperiodic_mode='fixed', max_n_peaks=4, peak_threshold=1.0, peak_width_limits=(0.02, 0.5), seg_length=None, max_segments=inf)

Separates the power spectrum into aperiodic (1/f) and periodic (oscillatory) components.

Parameterizes the power spectrum as a smooth aperiodic ‘1/f’ background plus a small number of Gaussian peaks sitting on top of it, in the spirit of the FOOOF/specparam algorithm [1].

References

Parameters:
y : array-like

The input time series.

aperiodic_mode : {'fixed', 'knee'}, optional

The form of the aperiodic component:

  • ’fixed’: b - chi*log10(f), a straight line in log-log, i.e. pure power-law.

  • ’knee’: b - log10(k + f**chi), which additionally allows the spectrum to flatten off below a ‘knee’ frequency, as real spectra commonly do. Note the knee model is not identifiable when the data has no actual knee (k -> 0), so it falls back to the ‘fixed’ fit if the optimization fails or returns a degenerate knee.

Default is 'fixed'.

max_n_peaks : int, optional

The maximum number of Gaussian peaks to extract. Default is 4.

peak_threshold : float, optional

How far above the noise a candidate peak must stand to be accepted (default 1). This is expressed as a multiple of the largest deviation that noise alone would be expected to produce.

peak_width_limits : array-like, optional

Two-element [min, max] on Gaussian peak standard deviation, in log10-frequency units (default (0.02, 0.5)).

seg_length : int, optional

Length of the Welch segments. None (default) adapts to the series length, as max(round(N/8), 32), so that longer series buy both finer frequency resolution and more segments to average over.

max_segments : float, optional

Maximum number of Welch segments to use. np.inf (default) uses all the available data.

Returns:

The aperiodic parameters (apExponent, apOffset, and for ‘knee’ mode apKnee); the number of peaks found above threshold (numPeaks) and the centre frequency, height and bandwidth of the largest (maxPeakFreq, maxPeakPower, maxPeakBW); the total power in the periodic component (totalPeakPower) and periodicFraction, the sum of squares of the fitted periodic component divided by the sum of squared deviations of the log10 spectrum from its mean (a ratio that is not bounded above by 1, not a fraction of spectral power); and the quality of the combined fit (modelR2 and modelMAE).

Return type:

dict