spectral_flatness

function of dascore.transform.spectral_descriptors

spectral_flatness(
    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 spectral flatness from a Fourier-domain patch.

Spectral flatness is the ratio between the geometric mean and arithmetic mean of the power spectrum. It is invariant to positive scaling of the power and lies in [0, 1] for finite, nonzero spectra. A zero-power bin gives flatness 0; an entirely zero spectrum gives NaN.

Values near 1 indicate white-noise-like spectra. Values near 0 indicate tonal or peaked spectra. 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 when power is symmetric and raises otherwise, folding a verified negative Nyquist bin to positive frequency without changing its power. `"drop"` always uses non-negative frequencies, `"raise"` rejects spectra with negative bins, and `"keep"` includes them in the calculation.

Returns

PatchType Patch containing spectral flatness.