spectral_peak_frequency

function of dascore.transform.spectral_descriptors

spectral_peak_frequency(
    patch: Patch ,
    dim: str | None[str, None] = None,
    fmin: float | None[float, None] = None,
    fmax: float | None[float, None] = None,
    spectral_format: Literal[‘auto’, ‘fft’, ‘amplitude’, ‘power’, ‘density’] = auto,
    negative_frequencies: Literal[‘auto’, ‘drop’, ‘raise’, ‘keep’] = auto,
)-> ‘PatchType’

Compute the peak frequency of a Fourier-domain patch.

The peak frequency is the frequency bin with maximum spectral power within the selected frequency range. This is the global maximum, not a search for multiple local peaks. Ties select the first bin in coordinate order. The input patch must already be transformed with Patch.dft or Patch.stft.

Parameters

Parameter	Description
patch	Fourier-domain DASCore patch from `dft` or `stft`.

dim	Frequency dimension over which to compute the descriptor. This can be either the original dimension name, such as `"time"`, or the Fourier dimension name, such as `"ft_time"`. If omitted, a single Fourier dimension is inferred.
fmin	Optional lower frequency bound.
fmax	Optional upper frequency bound.
spectral_format	Representation of the spectral data. `"auto"` uses DASCore DFT/STFT metadata when available. Other options are `"fft"` for complex Fourier coefficients, `"amplitude"` for amplitude spectra, `"power"` for power spectra, and `"density"` for power spectral densities.
negative_frequencies	How to handle negative frequency bins. `"auto"` drops negative bins only when power is symmetric, `"drop"` always uses non-negative frequencies, `"raise"` rejects spectra with negative bins, and `"keep"` includes them in the calculation.

Returns

PatchType Patch containing the frequency corresponding to the maximum spectral power.