pyrasa.utils.peak_utils.get_peak_params_sprint#

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

Extracts peak parameters from a periodic spectrogram obtained via IRASA.

This function processes a time-resolved periodic spectrum to identify and extract peak parameters such as center frequency (cf), bandwidth (bw), and peak height (pw) for each time point. It applies smoothing, peak detection, and thresholding according to user-defined parameters (see get_peak_params for additional Information).

Parameters:

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

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

  • times (np.ndarray) – 1D array containing time points corresponding to the periodic spectrogram.

  • ch_names (Iterable or None, optional) – List of channel names corresponding to the periodic spectrogram. 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 2 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, the full frequency range is used. Default is (1, 40).

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

  • 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 data. 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).

Returns:

A DataFrame containing the detected peak parameters for each channel and time point. 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) - ‘time’: Corresponding time point for the peak

Return type:

pd.DataFrame

Notes

This function iteratively processes each time point in the spectrogram, applying the get_peak_params function to extract peak parameters at each time point. The resulting peak parameters are combined into a single DataFrame.

The function is particularly useful for analyzing time-varying spectral features, such as in dynamic or non-stationary M/EEG data, where peaks may shift in frequency, bandwidth, or amplitude over time.

On this page