phonometry 3.0.0__py3-none-any.whl

phonometry/__init__.py

@@ -0,0 +1,248 @@
+#  Copyright (c) 2020. Jose M. Requena-Plens
+"""
+Octave-Band and Fractional Octave-Band filter for signals in the time domain.
+Implementation according to ANSI s1.11-2004 and IEC 61260-1-2014.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import List, Tuple, overload, Literal
+
+import numpy as np
+
+from .calibration import CalibrationWarning, calculate_sensitivity
+from .compliance import verify_filter_class
+from .core import OctaveFilterBank
+from .frequencies import getansifrequencies, normalizedfreq
+from .levels import laeq, lc_peak, leq, lex_8h, ln_levels, sel, sound_exposure
+from .parametric_filters import (
+    TimeWeighting,
+    WeightingFilter,
+    linkwitz_riley,
+    time_weighting,
+    weighting_filter,
+)
+from ._version import __version__
+
+# Public methods
+__all__ = [
+    "__version__",
+    "octavefilter",
+    "getansifrequencies",
+    "normalizedfreq",
+    "OctaveFilterBank",
+    "WeightingFilter",
+    "weighting_filter",
+    "time_weighting",
+    "TimeWeighting",
+    "linkwitz_riley",
+    "calculate_sensitivity",
+    "leq",
+    "laeq",
+    "ln_levels",
+    "lc_peak",
+    "sel",
+    "sound_exposure",
+    "lex_8h",
+    "CalibrationWarning",
+    "verify_filter_class",
+]
+
+
+@lru_cache(maxsize=32)
+def _cached_filter_bank(
+    fs: int,
+    fraction: float,
+    order: int,
+    limits: Tuple[float, ...] | None,
+    filter_type: str,
+    ripple: float,
+    attenuation: float,
+    calibration_factor: float,
+    dbfs: bool,
+) -> OctaveFilterBank:
+    """Design (or reuse) a stateless filter bank for octavefilter()."""
+    return OctaveFilterBank(
+        fs=fs,
+        fraction=fraction,
+        order=order,
+        limits=list(limits) if limits is not None else None,
+        filter_type=filter_type,
+        ripple=ripple,
+        attenuation=attenuation,
+        calibration_factor=calibration_factor,
+        dbfs=dbfs,
+    )
+
+
+@overload
+def octavefilter(
+    x: List[float] | np.ndarray,  # NOSONAR - public API
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: Literal[False] = False,
+    plot_file: str | None = None,
+    detrend: bool = True,
+    filter_type: str = "butter",
+    ripple: float = 0.1,
+    attenuation: float = 60.0,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+    mode: str = "rms",
+    nominal: Literal[False] = False,
+) -> Tuple[np.ndarray, List[float]]: ...
+
+
+@overload
+def octavefilter(
+    x: List[float] | np.ndarray,  # NOSONAR - public API
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: Literal[True] = True,
+    plot_file: str | None = None,
+    detrend: bool = True,
+    filter_type: str = "butter",
+    ripple: float = 0.1,
+    attenuation: float = 60.0,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+    mode: str = "rms",
+    nominal: Literal[False] = False,
+) -> Tuple[np.ndarray, List[float], List[np.ndarray]]: ...
+
+
+@overload
+def octavefilter(
+    x: List[float] | np.ndarray,  # NOSONAR - public API
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: Literal[False] = False,
+    plot_file: str | None = None,
+    detrend: bool = True,
+    filter_type: str = "butter",
+    ripple: float = 0.1,
+    attenuation: float = 60.0,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+    mode: str = "rms",
+    nominal: Literal[True] = ...,
+) -> Tuple[np.ndarray, List[str]]: ...
+
+
+@overload
+def octavefilter(
+    x: List[float] | np.ndarray,  # NOSONAR - public API
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: Literal[True] = True,
+    plot_file: str | None = None,
+    detrend: bool = True,
+    filter_type: str = "butter",
+    ripple: float = 0.1,
+    attenuation: float = 60.0,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+    mode: str = "rms",
+    nominal: Literal[True] = ...,
+) -> Tuple[np.ndarray, List[str], List[np.ndarray]]: ...
+
+
+def octavefilter(
+    x: List[float] | np.ndarray,  # NOSONAR - public API
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: bool = False,
+    plot_file: str | None = None,
+    detrend: bool = True,
+    filter_type: str = "butter",
+    ripple: float = 0.1,
+    attenuation: float = 60.0,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+    mode: str = "rms",
+    nominal: bool = False,
+) -> Tuple[np.ndarray, List[float]] | Tuple[np.ndarray, List[str]] | Tuple[np.ndarray, List[float], List[np.ndarray]] | Tuple[np.ndarray, List[str], List[np.ndarray]]:
+    """
+    Filter 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.
+
+    :param x: Input signal (1D array or 2D array [channels, samples]).
+    :type x: Union[List[float], np.ndarray]
+    :param fs: Sample rate in Hz.
+    :type fs: int
+    :param fraction: Bandwidth 'b'. Examples: 1/3-octave b=3, 1-octave b=1, 2/3-octave b=1.5. Default: 1.
+    :type fraction: float
+    :param order: Order of the filter. Default: 6.
+    :type order: int
+    :param limits: Minimum and maximum limit frequencies [f_min, f_max]. Default [12, 20000].
+    :type limits: Optional[List[float]]
+    :param show: If True, plot and show the filter response.
+    :type show: bool
+    :param sigbands: If True, also return the signal in the time domain divided into bands.
+    :type sigbands: bool
+    :param plot_file: Path to save the filter response plot.
+    :type plot_file: Optional[str]
+    :param detrend: If True, remove DC offset before filtering. Default: True.
+    :type detrend: bool
+    :param filter_type: Type of filter ('butter', 'cheby1', 'cheby2', 'ellip', 'bessel'). Default: 'butter'.
+    :param ripple: Passband ripple in dB (for cheby1, ellip). Default: 0.1.
+    :param attenuation: Stopband attenuation in dB (for cheby2, ellip). Default: 60.0.
+    :param calibration_factor: Calibration factor for SPL calculation. Default: 1.0.
+    :param dbfs: If True, return results in dBFS. Default: False.
+    :param mode: 'rms' or 'peak'. Default: 'rms'.
+    :param nominal: If True, return IEC 61260-1 nominal frequency labels (List[str]) instead of exact floats.
+    :return: A tuple containing (SPL_array, Frequencies_list) or (SPL_array, Frequencies_list, signals).
+        When *nominal=True*, the frequency list contains ``List[str]`` labels instead of floats.
+    :rtype: Union[Tuple[np.ndarray, List[float]], Tuple[np.ndarray, List[str]],
+        Tuple[np.ndarray, List[float], List[np.ndarray]],
+        Tuple[np.ndarray, List[str], List[np.ndarray]]]
+    """
+    
+    if show or plot_file:
+        # Plotting has side effects: bypass the cache.
+        filter_bank = OctaveFilterBank(
+            fs=fs,
+            fraction=fraction,
+            order=order,
+            limits=limits,
+            filter_type=filter_type,
+            ripple=ripple,
+            attenuation=attenuation,
+            show=show,
+            plot_file=plot_file,
+            calibration_factor=calibration_factor,
+            dbfs=dbfs,
+        )
+    else:
+        # The bank is immutable in non-stateful mode: reuse the design.
+        # Pass limits through as-is (tuple for hashability); the bank
+        # constructor is the single place that validates them and owns
+        # the default when None.
+        limits_key = tuple(map(float, limits)) if limits is not None else None
+        filter_bank = _cached_filter_bank(
+            fs, fraction, order, limits_key, filter_type,
+            ripple, attenuation, calibration_factor, dbfs,
+        )
+
+    return filter_bank.filter(x, sigbands=sigbands, mode=mode, detrend=detrend, nominal=nominal)  # type: ignore[call-overload,no-any-return]

phonometry/_version.py

@@ -0,0 +1,17 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""Package version.
+
+The canonical version lives in the repository-root ``VERSION`` file (the
+build backend reads it via ``[tool.setuptools.dynamic]``). Installed
+packages resolve it from their metadata; running from a source tree falls
+back to reading the file directly.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("phonometry")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    from pathlib import Path
+
+    __version__ = (Path(__file__).resolve().parents[2] / "VERSION").read_text().strip()

phonometry/calibration.py

@@ -0,0 +1,98 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Calibration utilities for mapping digital signals to physical SPL levels.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import List
+
+import numpy as np
+
+
+class CalibrationWarning(UserWarning):
+    """The calibration reference recording looks unreliable."""
+
+
+def calculate_sensitivity(
+    ref_signal: List[float] | np.ndarray,
+    target_spl: float = 94.0,
+    ref_pressure: float = 2e-5,
+    fs: int | None = None,
+    validate: bool = True,
+    max_fluctuation_db: float = 0.10,
+) -> float:
+    """
+    Calculate the calibration factor (multiplier) to convert digital units
+    to Pascals based on a reference recording (e.g., 1kHz @ 94dB).
+
+    When ``fs`` is provided (and ``validate`` is True), the recording's
+    stability is checked the way IEC 60942 specifies for the calibrator
+    itself: the short-term level fluctuation — one-half of the difference
+    between the maximum and minimum F-time-weighted levels (BS EN 60942:2003,
+    5.2.3) — must not exceed ``max_fluctuation_db`` (Table 1: 0.10 dB for a
+    class 1 calibrator between 160 Hz and 1.25 kHz). A larger fluctuation
+    usually means a badly coupled microphone or handling noise in the
+    recording, which would silently corrupt every calibrated level; a
+    :class:`CalibrationWarning` is emitted.
+
+    :param ref_signal: Recording of the calibration tone.
+    :param target_spl: The known SPL level of the calibrator (default 94 dB).
+    :param ref_pressure: Reference pressure (default 20 microPascals).
+    :param fs: Sample rate of the recording in Hz. Required for the
+        stability validation; without it the check is skipped.
+    :param validate: If True (default) and ``fs`` is given, warn when the
+        recording's short-term level fluctuation exceeds the limit.
+    :param max_fluctuation_db: Fluctuation limit in dB (default 0.10, the
+        IEC 60942 class 1 tolerance).
+    :return: Calibration factor (sensitivity multiplier).
+    """
+    signal_arr = np.asarray(ref_signal, dtype=np.float64)
+    if signal_arr.size == 0:
+        raise ValueError("Reference signal is empty, cannot calibrate.")
+    rms_ref = np.sqrt(np.mean(signal_arr ** 2))
+    if rms_ref == 0:
+        raise ValueError("Reference signal is silent, cannot calibrate.")
+
+    if validate and fs is not None:
+        _validate_reference_stability(signal_arr, fs, max_fluctuation_db)
+
+    factor = (ref_pressure * 10 ** (target_spl / 20)) / rms_ref
+    return float(factor)
+
+
+def _validate_reference_stability(
+    signal_arr: np.ndarray, fs: int, max_fluctuation_db: float
+) -> None:
+    """Warn if the F-weighted level of the recording fluctuates too much."""
+    from .parametric_filters import time_weighting
+
+    # The integrator attack lasts ~8*tau (1 s for F); we need at least
+    # another second of settled envelope to assess the fluctuation.
+    if signal_arr.shape[-1] < 2 * fs:
+        warnings.warn(
+            "Calibration tone is shorter than 2 s: too short to validate its "
+            "stability (IEC 60942 measures the generated level over 20 s). "
+            "Record a longer, steady tone.",
+            CalibrationWarning,
+            stacklevel=3,
+        )
+        return
+    envelope = time_weighting(signal_arr, fs, mode="fast")
+    skip = int(1.0 * fs)
+    steady = np.maximum(envelope[..., skip:], np.finfo(float).eps)
+    levels_db = 10 * np.log10(steady)
+    # Per-channel spread: channels may sit at different (individually
+    # stable) levels, which must not read as fluctuation.
+    spread = np.max(levels_db, axis=-1) - np.min(levels_db, axis=-1)
+    fluctuation = float(np.max(spread)) / 2.0
+    if fluctuation > max_fluctuation_db:
+        warnings.warn(
+            f"Calibration tone level fluctuation is {fluctuation:.2f} dB "
+            f"(limit {max_fluctuation_db:.2f} dB per IEC 60942 Table 1). "
+            "Check the microphone coupling and trim handling noise before "
+            "trusting the resulting sensitivity.",
+            CalibrationWarning,
+            stacklevel=3,
+        )

phonometry/compliance.py

@@ -0,0 +1,203 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+IEC 61260-1:2014 filter class verification.
+
+Acceptance limits on relative attenuation transcribed from the official text
+(BS EN 61260-1:2014, **Table 1**, standard pages 15-16): octave-band
+breakpoint frequencies with class 1 and class 2 minimum/maximum limits.
+Fractional-octave-band breakpoints are derived with Formulas (9) and (10)
+(subclauses 5.10.3-5.10.4) and limits between breakpoints are interpolated
+linearly in lg(Omega) per Formula (11) (subclause 5.10.6).
+
+Relative attenuation is ``deltaA(Omega) = A(Omega) - Aref`` (Formula 8) with
+``A = Lin - Lout`` (Formula 7); here ``Aref`` is the attenuation at the exact
+mid-band frequency (subclause 5.9: the pass-band reference attenuation).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+import numpy as np
+from scipy import signal
+
+from .core import OctaveFilterBank
+
+_G = 10 ** (3 / 10)
+
+# BS EN 61260-1:2014 Table 1, high side (Omega >= 1), as exponents x of the
+# octave-band normalized frequency G**x with (min, max) limits per class.
+# The low side mirrors these at 1/Omega (Formula 10). The band-edge rows
+# G**(1/2 -+ epsilon) encode the discontinuity at the edge: the pass-band
+# segment carries the max limits, the stop-band segment the min limits.
+#
+# Pass-band max limits (min is constant -0.4 dB class 1 / -0.6 dB class 2):
+_PASSBAND_MAX: List[Tuple[float, float, float]] = [
+    # (exponent, class 1 max, class 2 max)
+    (0.0, 0.4, 0.6),      # Omega = 1
+    (1 / 8, 0.5, 0.7),
+    (1 / 4, 0.7, 0.9),
+    (3 / 8, 1.4, 1.7),
+    (1 / 2, 5.3, 5.8),    # G**(1/2) - epsilon
+]
+_PASSBAND_MIN = {1: -0.4, 2: -0.6}
+
+# Stop-band min limits (max is +inf):
+_STOPBAND_MIN: List[Tuple[float, float, float]] = [
+    # (exponent, class 1 min, class 2 min)
+    (1 / 2, 1.2, 0.8),    # G**(1/2) + epsilon
+    (1.0, 16.6, 15.6),
+    (2.0, 40.5, 39.5),
+    (3.0, 60.0, 54.0),
+    (4.0, 70.0, 60.0),    # and >= G**4: constant
+]
+
+
+def _map_breakpoint(exponent: float, fraction: float) -> float:
+    """
+    Map an octave-band breakpoint G**x to a fractional-octave-band one.
+
+    BS EN 61260-1:2014 Formula (9): the high-frequency breakpoint for
+    bandwidth designator 1/b is
+    ``1 + (G**(1/(2b)) - 1) / (G**(1/2) - 1) * (Omega_h(1/1) - 1)``.
+    """
+    omega_octave = _G ** exponent
+    scale = (_G ** (1 / (2 * fraction)) - 1) / (_G ** 0.5 - 1)
+    return float(1 + scale * (omega_octave - 1))
+
+
+def class_limits(
+    fraction: float, filter_class: int, omega: np.ndarray
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Acceptance limits on relative attenuation at normalized frequencies.
+
+    :param fraction: Bandwidth designator denominator b (1 for octave,
+        3 for one-third octave, ...).
+    :param filter_class: 1 or 2 (IEC 61260-1:2014 performance class).
+    :param omega: Normalized frequencies f/fm (> 0).
+    :return: Tuple (minimum, maximum) relative attenuation in dB per point;
+        the maximum is ``+inf`` outside the pass-band.
+    """
+    if filter_class not in (1, 2):
+        raise ValueError("filter_class must be 1 or 2.")
+    if fraction <= 0:
+        raise ValueError("'fraction' must be positive.")
+    col = 1 if filter_class == 1 else 2
+
+    omega_arr = np.asarray(omega, dtype=np.float64)
+    if np.any(omega_arr <= 0):
+        raise ValueError("Normalized frequencies must be positive.")
+    # Formula (10): low side mirrors the high side.
+    omega_h = np.where(omega_arr < 1.0, 1.0 / omega_arr, omega_arr)
+
+    pass_x = np.array([_map_breakpoint(x, fraction) for x, _, _ in _PASSBAND_MAX])
+    pass_y = np.array([row[col] for row in _PASSBAND_MAX])
+    stop_x = np.array([_map_breakpoint(x, fraction) for x, _, _ in _STOPBAND_MIN])
+    stop_y = np.array([row[col] for row in _STOPBAND_MIN])
+
+    edge = pass_x[-1]  # mapped G**(1/2): the band-edge frequency ratio
+    in_pass = omega_h <= edge
+
+    minimum = np.empty_like(omega_h)
+    maximum = np.empty_like(omega_h)
+
+    # Pass-band: constant min, interpolated max (linear in lg(Omega), Formula 11).
+    minimum[in_pass] = _PASSBAND_MIN[filter_class]
+    maximum[in_pass] = np.interp(np.log10(omega_h[in_pass]), np.log10(pass_x), pass_y)
+
+    # Stop-band: interpolated min (constant beyond the last breakpoint), max +inf.
+    lg = np.log10(omega_h[~in_pass])
+    minimum[~in_pass] = np.interp(lg, np.log10(stop_x), stop_y)
+    maximum[~in_pass] = np.inf
+
+    return minimum, maximum
+
+
+def verify_filter_class(bank: OctaveFilterBank, num_points: int = 2 ** 15) -> Dict[str, Any]:
+    """
+    Verify a filter bank against the IEC 61260-1:2014 class limits.
+
+    Each band's relative attenuation (referenced to the attenuation at its
+    exact mid-band frequency) is checked against the class 1 and class 2
+    acceptance limits of Table 1, evaluated on a dense frequency grid up to
+    the band's processing Nyquist. The Table 1 breakpoint frequencies inside
+    that range are always included in the evaluation, so the pass-band
+    constraints are checked even if the grid were coarse. Frequencies beyond
+    the processing Nyquist cannot carry signal energy at the band's decimated
+    rate (the multirate anti-aliasing filter removes them), so they are
+    treated as compliant.
+
+    :param bank: The filter bank to verify (its designed SOS are analyzed;
+        works for stateful and stateless banks alike).
+    :param num_points: Number of frequency grid points per band (>= 16).
+    :return: Dict with ``overall_class`` (1, 2 or None) and ``bands``: a list
+        of ``{"freq", "class", "margin_class1_db", "margin_class2_db"}``
+        where a positive margin means the limits are met with that much room.
+    """
+    if num_points < 16:
+        raise ValueError("'num_points' must be at least 16.")
+
+    bands: List[Dict[str, Any]] = []
+
+    # Table 1 breakpoints (both sides) that must always be evaluated.
+    breakpoint_omegas = np.array(
+        [_map_breakpoint(x, bank.fraction) for x, _, _ in _PASSBAND_MAX + _STOPBAND_MIN]
+    )
+    breakpoint_omegas = np.concatenate([1.0 / breakpoint_omegas, breakpoint_omegas])
+
+    for idx in range(bank.num_bands):
+        fm = float(bank.freq[idx])
+        fsd = bank.fs / float(bank.factor[idx])
+        w, h = signal.sosfreqz(bank.sos[idx], worN=num_points, fs=fsd)
+
+        # Attenuation relative to the mid-band attenuation (Formulas 7-8).
+        attenuation = -20.0 * np.log10(np.abs(h) + np.finfo(float).eps)
+        a_ref = float(np.interp(fm, w, attenuation))
+        delta_all = attenuation - a_ref
+
+        omega = w / fm
+        valid = omega > 0
+        omega, delta_a = omega[valid], delta_all[valid]
+
+        # Guarantee the Table 1 breakpoints (pass-band included) are evaluated.
+        omega_max = float(omega.max())
+        extra = breakpoint_omegas[(breakpoint_omegas > 0) & (breakpoint_omegas <= omega_max)]
+        if extra.size:
+            delta_extra = np.interp(extra * fm, w, delta_all)
+            omega = np.concatenate([omega, extra])
+            delta_a = np.concatenate([delta_a, delta_extra])
+
+        margins: Dict[int, float] = {}
+        for cls in (1, 2):
+            minimum, maximum = class_limits(bank.fraction, cls, omega)
+            low_margin = float(np.min(delta_a - minimum))
+            finite = np.isfinite(maximum)
+            high_margin = (
+                float(np.min(maximum[finite] - delta_a[finite])) if np.any(finite) else np.inf
+            )
+            margins[cls] = min(low_margin, high_margin)
+
+        band_class = 1 if margins[1] >= 0 else (2 if margins[2] >= 0 else None)
+        bands.append(
+            {
+                "freq": fm,
+                "class": band_class,
+                "margin_class1_db": margins[1],
+                "margin_class2_db": margins[2],
+            }
+        )
+
+    if not bands:
+        # No bands to verify: never report compliance vacuously.
+        return {"overall_class": None, "bands": []}
+
+    classes = [band["class"] for band in bands]
+    if all(c == 1 for c in classes):
+        overall: int | None = 1
+    elif all(c in (1, 2) for c in classes):
+        overall = 2
+    else:
+        overall = None
+
+    return {"overall_class": overall, "bands": bands}