filters.core
Core processing logic and FilterBank class for phonometry.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
BlockProcessing
Section titled “BlockProcessing”BlockProcessing(*, stateful: bool = False, steady_ic: bool = False)How the bank carries its filter state from one block to the next.
Attributes
| Name | Description |
|---|---|
stateful |
If True, carry filter state between calls. Useful for block processing (default False). |
steady_ic |
If True, calculate steady state initial conditions for filter (default False). |
FilterBankWarning
Section titled “FilterBankWarning”A fractional-octave filter bank asked for something it cannot honour.
Emitted when limits the caller gave hold a band above the Nyquist frequency of the sample rate, which is dropped from the bank, and when a stateful bank is asked to detrend its blocks, which introduces a step between them.
FilterDesign
Section titled “FilterDesign”FilterDesign( *, filter_type: Literal['butter', 'cheby1', 'cheby2', 'ellip', 'bessel'] = 'butter', ripple: float = 0.1, attenuation: float = 72.0, resample: bool = True,)How the band-pass filters of a bank are designed.
The defaults are the design used everywhere in the library: Butterworth sections, evaluated band by band on a decimated sample rate.
Attributes
| Name | Description |
|---|---|
filter_type |
Type of filter (‘butter’, ‘cheby1’, ‘cheby2’, ‘ellip’, ‘bessel’). Only butter meets the class 1 mask of IEC 61260-1:2014 Table 1 with the default parameters (cheby2 also does once attenuation >= 70 dB, see below); cheby1/ellip/bessel fail on passband ripple or roll-off regardless of parameters (default ‘butter’). On the whole of that edition, as verify_filter_class grades it, see resample. |
ripple |
Passband ripple in dB, for cheby1 and ellip (default 0.1). |
attenuation |
Stopband attenuation in dB (default 72.0). For the cheby2 filter scipy pins the equiripple deep-stopband floor at exactly this value, so it must be >= 70 dB for the bank to meet the IEC 61260-1:2014 class 1 deep-stopband limit (Omega >= G^4). The 72 dB default clears class 1 with the same +0.400 dB passband margin as butter. |
resample |
If True, resampling is performed: each band is filtered on a decimated sample rate whose Nyquist frequency is at least sixteen times its upper band edge (default True). The order 6 butter octave and one-third-octave banks are class 1 on every requirement either way, decimated or at the full rate (False); the decimation moves the summation of adjacent outputs by at most 0.005 dB. A decimated band runs its input through a linear-phase anti-aliasing filter sized for a 120 dB stopband, which keeps every alias image the decimation folds onto the band more than 125 dB below it, and verify_filter_class grades those images. |
LevelCalibration
Section titled “LevelCalibration”LevelCalibration(*, factor: float = 1.0, dbfs: bool = False)How the energy in a band becomes a level reading.
Attributes
| Name | Description |
|---|---|
factor |
Calibration factor for SPL calculation: multiplies the digital amplitude to obtain pascals (default 1.0). |
dbfs |
If True, calculate SPL in dBFS, where 0 dB is a full-scale RMS of 1.0, instead of dB SPL re 20 uPa; factor is then not applied (default False). |
octave_filter
Section titled “octave_filter”octave_filter( x: Signal | NumericArrayLike, fs: float | None = None, fraction: float | np.integer[Any] = 1, order: int | np.integer[Any] = 6, limits: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]] | None = None, *, sigbands: bool = False, detrend: bool = True, mode: Literal['rms', 'peak'] = 'rms', nominal: bool = False, design: FilterDesign = ..., calibration: LevelCalibration = ..., response_plot: ResponsePlot = ...,) -> OctaveFilterResultFilter a signal with octave or fractional octave filter bank.
This method uses a filter bank with Second-Order Sections (SOS) coefficients. To obtain the correct coefficients, automatic subsampling is applied to the signal in each filtered band.
Multichannel support: If x is 2D (channels, samples), each channel is filtered.
Parameters
| Name | Description |
|---|---|
x |
Input signal (1D array or 2D array [channels, samples]), or a phonometry.io.Signal read from a measurement file. |
fs |
Sample rate in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
fraction |
Bandwidth ‘b’. Examples: 1/3-octave b=3, 1-octave b=1, 2/3-octave b=1.5. Default: 1. |
order |
Order of the filter. Default: 6. |
limits |
Minimum and maximum limit frequencies [f_min, f_max], a sequence or an array of the two. Default [12, 20000], trimmed to the bands fs holds: at 44.1 kHz the third octaves stop at 16 kHz. |
sigbands |
If True, also return the signal in the time domain divided into bands. |
detrend |
If True, remove DC offset before filtering. Default: True. |
mode |
‘rms’ or ‘peak’. Default: ‘rms’. |
nominal |
If True, return IEC 61260-1 nominal frequency labels (List[str]) instead of exact floats. |
design |
How the band filters are designed: family, ripple, stopband attenuation and multirate decimation (FilterDesign). The default ‘butter’ family is the only one that meets the class 1 mask of IEC 61260-1 Table 1 with the default parameters; for cheby2 scipy pins the deep-stopband floor at exactly attenuation, so it must be >= 70 dB to clear the class 1 limit (matches OctaveFilterBank, which also says how the decimated banks grade on the summation of outputs). |
calibration |
How band energy becomes a level: calibration factor and dBFS switch (LevelCalibration). This is the explicit knob: when its factor is left at 1.0, a calibrated Signal supplies its own and the band levels come out in dB SPL; when it carries a factor, the object’s is not applied on top (that would square it). dbfs=True ignores both the object and the factor, being referenced to digital full scale. |
response_plot |
Whether to show or save the filter response plot (ResponsePlot). Plotting bypasses the design cache. |
Returns: An OctaveFilterResult carrying the band levels, their frequencies and, when sigbands asked for them, the per-band bands. With nominal=True the frequencies are IEC 61260-1 labels instead of floats.
Raises
| Exception | When |
|---|---|
| TypeError | if fraction or fs is not a single number, order is a flag, a text or an array where a count goes, limits is not a pair of numbers, or mode is not a text. |
| ValueError | for a bare array with no fs, a sample rate or a bandwidth that is not positive, an order that is not a whole number from 1, frequency limits or a design the bank cannot be built with, or a sample rate that holds no band of the span, the default one or limits: the upper edge of the lowest band above fs/2. |
Warns
| Warning | When |
|---|---|
| FilterBankWarning | when limits asks for a band whose upper edge lies above fs/2, naming the bands left out, at every call; the default span is trimmed without one. |
OctaveFilterBank
Section titled “OctaveFilterBank”OctaveFilterBank( fs: float, fraction: float | np.integer[Any] = 1, order: int | np.integer[Any] = 6, limits: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]] | None = None, *, design: FilterDesign = ..., calibration: LevelCalibration = ..., block_processing: BlockProcessing = ..., response_plot: ResponsePlot = ...,)A class-based representation of an Octave Filter Bank. Allows for pre-calculating and reusing filter coefficients.
Initialize the Octave Filter Bank.
Parameters
| Name | Description |
|---|---|
fs |
Sample rate in Hz. |
fraction |
Bandwidth fraction (e.g., 1 for octave, 3 for 1/3 octave). |
order |
Filter order. |
limits |
Frequency limits [f_min, f_max], a sequence or an array of the two. |
design |
How the band filters are designed: family, ripple, stopband attenuation and multirate decimation (FilterDesign). Only butter meets the class 1 mask of IEC 61260-1:2014 Table 1 with the default parameters (cheby2 also does once attenuation >= 70 dB); cheby1/ellip/bessel fail on passband ripple or roll-off regardless of parameters. The octave and one-third-octave banks are class 1 on every requirement, decimated or filtered at the full rate (FilterDesign(resample=False)). |
calibration |
How band energy becomes a level: calibration factor and dBFS switch (LevelCalibration). |
block_processing |
Whether the bank carries its filter state between calls, and how that state starts (BlockProcessing). |
response_plot |
Whether to show or save the filter response plot drawn while designing the bank (ResponsePlot). |
Raises
| Exception | When |
|---|---|
| ValueError | for a sample rate or a bandwidth that is not positive, an order that is not a whole number from 1, frequency limits or a design the bank cannot be built with, or a sample rate that holds no band of the span, the default one or limits: the upper edge of the lowest band above fs/2. |
| TypeError | if fraction or fs is not a single number, or order is a flag, a text or an array where a count goes. An element of limits is refused the same way when it is not one real number. |
Warns
| Warning | When |
|---|---|
| FilterBankWarning | when limits asks for a band whose upper edge lies above fs/2, naming the bands left out. The default span, 12 Hz to 20 kHz, is trimmed to the bands fs holds without a warning: at 44.1 kHz the 20 kHz third octave, whose upper edge is 22.4 kHz, is left out. |
OctaveFilterBank.filter()
Section titled “OctaveFilterBank.filter()”OctaveFilterBank.filter( x: Signal | NumericArrayLike, *, sigbands: bool = False, mode: Literal['rms', 'peak'] = 'rms', detrend: bool = True, calculate_level: bool = True, nominal: bool = False, zero_phase: bool = False,) -> OctaveFilterResultApply the pre-designed filter bank to a signal.
Parameters
| Name | Description |
|---|---|
x |
Input signal (1D array or 2D array [channels, samples]), or a phonometry.io.Signal. A Signal recorded at another rate than the one this bank was designed for is refused rather than filtered; a calibrated one is filtered in pascals unless the bank carries a calibration factor of its own, or reads in dBFS. |
sigbands |
If True, also return the signal in the time domain divided into bands. |
mode |
‘rms’ for energy-based level, ‘peak’ for peak-holding level. Note: ‘peak’ includes the filter’s onset transient; a tone that starts abruptly can overshoot by ~1 dB. For steady signals, discard the first ~5/f_low seconds or use longer signals. |
detrend |
If True, remove DC offset from signal before filtering (Default: True). |
calculate_level |
If True, calculate SPL. |
nominal |
If True, return IEC 61260-1 nominal frequency labels (List[str]) instead of exact floats. |
zero_phase |
If True, filter with sosfiltfilt (forward-backward): no group delay, but the effective stopband attenuation doubles and the effective passband narrows. The narrowing lowers the measured broadband band level by about 0.2 to 0.3 dB per band relative to forward filtering (a pure in-band tone is unaffected, since it sits where both passes are ~0 dB). Prefer forward filtering when the absolute band SPL must match single-pass conventions; use zero-phase when preserving the temporal envelope matters (e.g. reverberation decay, ISO 3382-2 Clause 7.3). Offline analysis only; incompatible with stateful mode. |
Returns: An OctaveFilterResult carrying the band levels, their frequencies and, when sigbands asked for them, the per-band bands.
Raises
| Exception | When |
|---|---|
| TypeError | if mode is not a text. |
OctaveFilterBank.frequencies
Section titled “OctaveFilterBank.frequencies”property
The exact mid-band frequency of each band, in hertz (read-only).
OctaveFilterBank.labels
Section titled “OctaveFilterBank.labels”property
The IEC 61260-1 nominal mid-band frequency of each band, as text.
OctaveFilterBank.lower_edges
Section titled “OctaveFilterBank.lower_edges”property
The lower band-edge frequency of each band, in hertz (read-only).
OctaveFilterBank.n_bands
Section titled “OctaveFilterBank.n_bands”property
How many bands the bank holds.
OctaveFilterBank.spectrogram()
Section titled “OctaveFilterBank.spectrogram()”OctaveFilterBank.spectrogram( x: Signal | NumericArrayLike, window_time: float = 0.125, overlap: float = 0.5, mode: Literal['rms', 'peak'] = 'rms', *, detrend: bool = True, zero_phase: bool = False,) -> OctaveSpectrogramResultShort-time fractional-octave analysis: level per band over time.
Parameters
| Name | Description |
|---|---|
x |
Input signal (1D array or 2D array [channels, samples]), or a phonometry.io.Signal. It follows the same rate and calibration rules as filter: a Signal at another rate is refused, and a calibrated one is analysed in pascals unless this bank carries a calibration factor of its own or reads in dBFS. The two methods must not report different levels for the same recording. |
window_time |
Analysis window length in seconds. |
overlap |
Window overlap fraction in [0, 1). |
mode |
‘rms’ or ‘peak’ (per window). |
detrend |
If True, remove DC offset before filtering. |
zero_phase |
If True, filter bands forward-backward so their group delays don’t skew the frames (offline analysis only). |
Returns: An OctaveSpectrogramResult. Its levels are shaped (bands, frames) for 1D input and (channels, bands, frames) for 2D input, frequencies holds the exact mid-band frequencies and times each window’s centre in seconds.
Raises
| Exception | When |
|---|---|
| TypeError | if overlap or window_time is not a single number, or mode is not a text. |
OctaveFilterBank.upper_edges
Section titled “OctaveFilterBank.upper_edges”property
The upper band-edge frequency of each band, in hertz (read-only).
OctaveFilterResult
Section titled “OctaveFilterResult”OctaveFilterResult( levels: NDArray[np.float64] | None, frequencies: tuple[float, ...] | tuple[str, ...], bands: tuple[Signal, ...] | tuple[NDArray[np.float64], ...] | None = None,)What a filter bank gives back for one signal.
Every other computation in this library hands back a named result, and
this one used to hand back a tuple whose length depended on a keyword: two
items normally, three when sigbands was set. A caller had to remember
which call it had written to know how to unpack it, and a reader of
_, _, bands = bank.filter(...) had to count commas to find out what the
first two were. They have names now.
Attributes
| Name | Description |
|---|---|
levels |
Band levels, in decibels, shaped (bands,) for a single-channel input and (channels, bands) for a multichannel one. None when the call asked for no level. |
frequencies |
One band centre per level: exact midband frequencies, or IEC 61260-1 nominal labels when the call asked for nominal. |
bands |
The input split into one waveform per band, in the same order, or None when the call did not ask for sigbands. They come back in the type they went in as: a Signal input gives Signals and a bare array gives arrays. What that Signal says about its units is a separate question, and it answers it itself: a calibrated input yields bands in pascals carrying calibration_factor=1.0, meaning the conversion is already done, and an uncalibrated one yields bands in digital units carrying None, because the object never invents a calibration. A bank filtering in dBFS, or one carrying a factor of its own, filtered digital units, so its bands are handed back as plain arrays rather than labelled pascals. |
The band centres and the waveforms are tuples, as every other frozen result holds a sequence: a list inside a frozen record is one a caller could still append to. A record built by hand with lists holds them as tuples.
OctaveFilterResult.plot()
Section titled “OctaveFilterResult.plot()”OctaveFilterResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the band levels against their band centres.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
Raises
| Exception | When |
|---|---|
| ValueError | when the call that made this result asked for no level, because there is then nothing to draw. |
OctaveFilterResult.require_bands()
Section titled “OctaveFilterResult.require_bands()”OctaveFilterResult.require_bands() -> tuple[Signal, ...] | tuple[NDArray[np.float64], ...]The per-band waveforms, or a clear error when none were kept.
Splitting a record into bands costs a copy per band, so it only
happens when sigbands asks for it. This is how code that needs
them says so.
Returns: One waveform per band, in band order.
Raises
| Exception | When |
|---|---|
| ValueError | when the call did not ask for sigbands. |
OctaveFilterResult.require_levels()
Section titled “OctaveFilterResult.require_levels()”OctaveFilterResult.require_levels() -> NDArray[np.float64]The band levels, or a clear error when the call asked for none.
levels is None for a call made with calculate_level=False,
and code that needs the levels would otherwise meet that None some
lines later, as an operation on it. This says what happened.
Returns: The band levels.
Raises
| Exception | When |
|---|---|
| ValueError | when the call asked for no level. |
OctaveSpectrogramResult
Section titled “OctaveSpectrogramResult”OctaveSpectrogramResult( levels: NDArray[np.float64], frequencies: NDArray[np.float64], times: NDArray[np.float64], lower_edges: NDArray[np.float64], upper_edges: NDArray[np.float64],)Band levels over time: what OctaveFilterBank.spectrogram returns.
A record with named fields rather than a (levels, frequencies, times)
tuple, so it cannot be unpacked by position: read .levels,
.frequencies and .times, or draw it with plot.
Attributes
| Name | Description |
|---|---|
levels |
The level of each band in each analysis window, in decibels: shaped (bands, frames) for a single-channel input and (channels, bands, frames) for a multichannel one. |
frequencies |
The exact mid-band frequency of each band, in hertz, as a read-only array. |
times |
The centre of each analysis window, in seconds. |
lower_edges |
The lower edge of each band, in hertz, as the bank designed it. |
upper_edges |
The upper edge of each band, in hertz. |
OctaveSpectrogramResult.plot()
Section titled “OctaveSpectrogramResult.plot()”OctaveSpectrogramResult.plot( ax: Axes | None = None, *, channel: int | np.integer[Any] | None = None, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw the levels as one raster over time and band centre, with a colour bar.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
channel |
Which channel of a multichannel result to draw, counted from 0. A multichannel result needs it; a single-channel one takes None or 0. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to imshow. |
Raises
| Exception | When |
|---|---|
| TypeError | for a channel that is not a number, or is a bool. |
| ValueError | for a multichannel result drawn without channel, a channel that is not a whole number, or one the result does not hold. |
ResponsePlot
Section titled “ResponsePlot”ResponsePlot(*, show: bool = False, file: str | None = None)The filter-response plot drawn while the bank is being designed.
Attributes
| Name | Description |
|---|---|
show |
If True, show the filter response plot (default False). |
file |
Path to save the filter response plot (default None). |