median_frequency

function of dascore.transform.spectral_descriptors

median_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 median frequency of a Fourier-domain patch.

This measure divides a signal’s power spectrum into two regions of equal total power. The input patch must already be transformed with Patch.dft or Patch.stft.

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

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 median-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")
med = spec.median_frequency(fmin=50, fmax=300)
ax = med.viz.waterfall(cmap='turbo', ax=axs[1], scale=[0,1])