spectral_centroid

function of dascore.transform.spectral_descriptors

spectral_centroid(
    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 spectral centroid of a Fourier-domain patch.

This represents the center of gravity of the signal’s power spectrum, and is sometimes called the mean frequency. The input patch must already be transformed with Patch.dft or Patch.stft. STFT inputs produce rolling descriptors; DFT inputs produce descriptors over the remaining non-frequency dimensions.

See for more detail: - (Phinyomark12?) - Online version of the Phinyomark publication - Matlab’s meanfreq

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

The Patch instance with the mean-frequency as data.

Example

import dascore as dc
import matplotlib.pyplot as plt

patch = dc.examples.get_example_patch('example_event_2')

fig, axs = plt.subplots(1,2, layout='constrained', figsize=(12,4))
ax = patch.viz.waterfall(cmap='seismic', ax=axs[0])

spec = patch.stft(time=.02, overlap=.019, taper_window="boxcar")
centroid = spec.spectral_centroid(fmin=50, fmax=300)
ax = centroid.viz.waterfall(cmap='turbo', ax=axs[1])