Ir al contenido

signals.windows

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

Figures of merit of a spectral-analysis taper (Harris 1978).

The window is the one choice every Fourier estimator forces and the one the estimators of phonometry.signals.spectra leave open in their window parameter. Harris (1978, On the use of windows for harmonic analysis with the discrete Fourier transform) turned that choice into a table of numbers: equivalent noise bandwidth, coherent gain, scalloping loss, worst-case processing loss, highest sidelobe level and the -3 dB main-lobe width: the trade-off between resolution, leakage and amplitude accuracy, read rather than guessed.

window_metrics computes those figures for any taper scipy.signal.get_window accepts, sampling it DFT-even (periodic) exactly as the Welch estimators of phonometry.signals.spectra and the multitaper estimator of phonometry.signals.multitaper apply it, so the numbers describe the window as this library actually uses it.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

window_metrics(
window: str | tuple[str | NumericArrayLike, ...],
n: int | np.integer[Any] = 1024,
) -> WindowMetricsResult

Figures of merit of a spectral-analysis taper (Harris 1978).

Computes the numbers behind the window trade-off for any taper the window parameter of the phonometry.signals.spectra estimators accepts: the equivalent noise bandwidth and coherent gain (closed forms of the samples, machine-exact), and the scalloping loss, worst-case processing loss, highest sidelobe level and -3 dB main-lobe width (measured on the spectrum of the sampled window, oversampled by zero-padding). The window is sampled DFT-even (periodic), exactly as the Welch estimators apply it.

Parameters

Name Description
window Window name or (name, param) tuple, anything scipy.signal.get_window accepts (e.g. 'hann', ('kaiser', 8.6), ('tukey', 0.5)).
n Window length, in samples (at least 16).

Returns: A WindowMetricsResult.

Raises

Exception When
TypeError If n is not a whole number’s type (a bool, a text, an array), or window is a specification of a type scipy.signal.get_window does not take.
ValueError If n is not whole or is below 16, the window name is unknown, or the window is degenerate.
WindowMetricsResult(
window: str | tuple[str | NumericArrayLike, ...],
n: int,
taps: NDArray[np.float64],
coherent_gain: float,
enbw_bins: float,
scalloping_loss: float,
worst_case_processing_loss: float,
highest_sidelobe_level: float,
mainlobe_width_3db_bins: float,
)

Figures of merit of a taper (Harris 1978), DFT-even sampling.

Losses are positive dB (how much is lost), sidelobe levels negative dB (relative to the main lobe), bandwidths in DFT bins (multiply by fs/n for Hz), matching the conventions of Harris’ Table 1. The window is sampled DFT-even (periodic), exactly as scipy.signal.welch and the estimators of phonometry.signals.spectra use it.

Attributes

Name Description
window The window specification as given (any name or (name, param) tuple scipy.signal.get_window accepts), with an array parameter kept as a read-only copy of its own and a list parameter as a tuple of the same numbers.
n Window length, in samples.
taps The window samples w[m] (DFT-even).
coherent_gain Normalized DC gain (1 for rectangular); the amplitude a bin-centered tone is scaled by before correction.
enbw_bins Equivalent noise bandwidth , in bins: the width of the ideal rectangular filter that would pass the same white-noise power (1 rectangular, 1.5 Hann, 1987/1458 Hamming).
scalloping_loss Attenuation of a tone midway between two bins, , in dB (positive).
worst_case_processing_loss Scalloping loss plus the ENBW processing loss , in dB: the worst-case reduction in output signal-to-noise ratio for a tone in white noise.
highest_sidelobe_level Level of the highest sidelobe relative to the main lobe, in dB (negative; -13.3 rectangular, -31.5 Hann).
mainlobe_width_3db_bins Two-sided -3 dB width of the main lobe, in bins.
WindowMetricsResult.enbw_hz(fs: float) -> float

Equivalent noise bandwidth in Hz for a sample rate fs.

Parameters

Name Description
fs Sample rate, in Hz.

Returns: enbw_bins·fs/n, in Hz.

WindowMetricsResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
WindowMetricsResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the window shape and its spectrum with the metrics marked.

Parameters

Name Description
language Label language, "en" (default) or "es".