pyrasa.utils.peak_utils.get_peak_params#

pyrasa.utils.peak_utils.get_peak_params(periodic_spectrum: ndarray, freqs: ndarray, ch_names: Iterable | None = None, smooth: bool = True, smoothing_window: int | float = 1, polyorder: int = 1, cut_spectrum: tuple[float, float] | None = None, peak_threshold: float = 1.0, min_peak_height: float = 0.01, peak_width_limits: tuple[float, float] = (0.5, 12.0)) → DataFrame[source]#

Extracts peak parameters from the periodic spectrum obtained via IRASA.

This function identifies and extracts peak parameters such as center frequency (cf), bandwidth (bw), and peak height (pw) from a periodic spectrum using scipy’s find_peaks function. The spectrum can be optionally smoothed prior peak detection.

Parameters:

  • periodic_spectrum (np.ndarray) – 1D or 2D array containing power values of the periodic spectrum (shape: [Channels, Frequencies] or [Frequencies]).

  • freqs (np.ndarray) – 1D array containing frequency values corresponding to the periodic spectrum.

  • ch_names (Iterable or None, optional) – List of channel names corresponding to the periodic spectrum. If None, channels are labeled numerically. Default is None.

  • smooth (bool, optional) – Whether to smooth the spectrum before peak extraction. Smoothing can help in reducing noise and better identifying peaks. Default is True.

  • smoothing_window (int or float, optional) – The size of the smoothing window in Hz, passed to the Savitzky-Golay filter. Default is 1 Hz.

  • polyorder (int, optional) – The polynomial order for the Savitzky-Golay filter used in smoothing. The polynomial order must be less than the window length. Default is 1.

  • cut_spectrum (tuple of (float, float) or None, optional) – Tuple specifying the frequency range (lower_bound, upper_bound) to which the spectrum should be cut before peak extraction. If None, peaks are detected across the full frequency range. Default is None.

  • peak_threshold (float, optional) – Relative threshold for detecting peaks, defined as a multiple of the standard deviation of the filtered spectrum. Default is 1.0.

  • min_peak_height (float, optional) – The minimum peak height (in absolute units of the power spectrum) required for a peak to be recognized. This can be useful for filtering out noise or insignificant peaks, especially when a “knee” is present in the original data, which may persist in the periodic spectrum. Default is 0.01.

  • peak_width_limits (tuple of (float, float), optional) – The lower and upper bounds for peak widths, in Hz. This helps in constraining the peak detection to meaningful features. Default is (0.5, 12.0).

Returns:

A DataFrame containing the detected peak parameters for each channel. The DataFrame includes the following columns: - ‘ch_name’: Channel name - ‘cf’: Center frequency of the peak - ‘bw’: Bandwidth of the peak - ‘pw’: Peak height (power)

Return type:

pd.DataFrame

Notes

The function works by first optionally smoothing the periodic spectrum using a Savitzky-Golay filter. Then, it performs peak detection using the scipy.signal.find_peaks function, taking into account the specified peak thresholds and width limits. Peaks that do not meet the minimum height requirement are filtered out.

The cut_spectrum parameter can be used to focus peak detection on a specific frequency range, which is particularly useful when the region of interest is known in advance.

On this page