phonometry 3.0.0__py3-none-any.whl

phonometry/frequencies.py

@@ -0,0 +1,186 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Frequency calculation logic according to ANSI/IEC standards.
+"""
+
+from __future__ import annotations
+
+import warnings
+from functools import lru_cache
+from typing import List, Tuple
+
+import numpy as np
+
+
+def getansifrequencies(
+    fraction: float,
+    limits: List[float] | None = None,
+) -> Tuple[List[float], List[float], List[float], List[str]]:
+    """
+    Calculate frequencies according to ANSI/IEC standards.
+
+    :param fraction: Bandwidth fraction (e.g., 1, 3).
+    :param limits: [f_min, f_max] limits.
+    :return: Tuple of (center_freqs, lower_edges, upper_edges, nominal_labels).
+    """
+    if limits is None:
+        limits = [12, 20000]
+
+    g = 10 ** (3 / 10)
+    fr = 1000
+
+    x = _initindex(limits[0], fr, g, fraction)
+    freq_list = [_ratio(g, x, fraction) * fr]
+
+    while freq_list[-1] * _bandedge(g, fraction) < limits[1]:
+        x += 1
+        freq_list.append(_ratio(g, x, fraction) * fr)
+    freq = np.array(freq_list)
+
+    freq_d = freq / _bandedge(g, fraction)
+    freq_u = freq * _bandedge(g, fraction)
+
+    labels = [_format_nominal_freq(_nominal_freq_for_band(f, fraction)) for f in freq.tolist()]
+    return freq.tolist(), freq_d.tolist(), freq_u.tolist(), labels
+
+
+def _initindex(f: float, fr: float, g: float, b: float) -> int:
+    """
+    Calculate starting index for band generation.
+
+    :param f: Frequency.
+    :param fr: Reference frequency.
+    :param g: Base ratio.
+    :param b: Bandwidth fraction.
+    :return: Index integer.
+    """
+    if round(b) % 2:
+        return int(np.round((b * np.log(f / fr) + 30 * np.log(g)) / np.log(g)))
+    return int(np.round((2 * b * np.log(f / fr) + 59 * np.log(g)) / (2 * np.log(g))))
+
+
+def _ratio(g: float, x: int, b: float) -> float:
+    """
+    Calculate ratio for center frequency.
+
+    :param g: Base ratio.
+    :param x: Index.
+    :param b: Bandwidth fraction.
+    :return: Frequency ratio.
+    """
+    if round(b) % 2:
+        return float(g ** ((x - 30) / b))
+    return float(g ** ((2 * x - 59) / (2 * b)))
+
+
+def _bandedge(g: float, b: float) -> float:
+    """
+    Calculate band-edge ratio.
+
+    :param g: Base ratio.
+    :param b: Bandwidth fraction.
+    :return: Edge ratio.
+    """
+    return float(g ** (1 / (2 * b)))
+
+
+def _deleteouters(
+    freq: List[float], freq_d: List[float], freq_u: List[float], fs: int
+) -> Tuple[List[float], List[float], List[float]]:
+    """
+    Remove bands exceeding the Nyquist frequency.
+
+    :param freq: Center frequencies.
+    :param freq_d: Lower edges.
+    :param freq_u: Upper edges.
+    :param fs: Sample rate.
+    :return: Filtered (center, lower, upper) frequencies.
+    """
+    freq_arr = np.array(freq)
+    freq_d_arr = np.array(freq_d)
+    freq_u_arr = np.array(freq_u)
+
+    idx = np.nonzero(freq_u_arr > fs / 2)[0]
+    if len(idx) > 0:
+        warnings.warn("Low sampling rate: frequencies above fs/2 removed", stacklevel=3)
+        freq_arr = np.delete(freq_arr, idx)
+        freq_d_arr = np.delete(freq_d_arr, idx)
+        freq_u_arr = np.delete(freq_u_arr, idx)
+
+    return freq_arr.tolist(), freq_d_arr.tolist(), freq_u_arr.tolist()
+
+
+def _genfreqs(
+    limits: List[float], fraction: float, fs: int
+) -> Tuple[List[float], List[float], List[float], List[str]]:
+    """
+    Determine band frequencies within limits.
+
+    :param limits: [f_min, f_max].
+    :param fraction: Bandwidth fraction.
+    :param fs: Sample rate.
+    :return: Tuple of center, lower, upper frequencies, and nominal labels.
+    """
+    freq, freq_d, freq_u, labels = getansifrequencies(fraction, limits)
+    freq, freq_d, freq_u = _deleteouters(freq, freq_d, freq_u, fs)
+    # _deleteouters only removes trailing bands above Nyquist, so slice labels
+    labels = labels[: len(freq)]
+    return freq, freq_d, freq_u, labels
+
+
+def _iec_e3_round(f: float) -> float:
+    """IEC 61260-1 Annex E.3: 3 sig figs if MSD 1–4, 2 sig figs if MSD 5–9."""
+    if f <= 0:
+        return f
+    exponent = int(np.floor(np.log10(f)))
+    msd = f / (10.0 ** exponent)
+    step = 10.0 ** (exponent - 2) if msd < 5.0 else 10.0 ** (exponent - 1)
+    return round(f / step) * step
+
+
+@lru_cache(maxsize=4)
+def _extended_preferred(frac: int) -> List[float]:
+    """Cached expansion of the IEC preferred frequency table across decades."""
+    base = normalizedfreq(frac)
+    return [f * (10 ** d) for d in range(-3, 4) for f in base]
+
+
+def _nominal_freq_for_band(exact_freq: float, fraction: float) -> float:
+    """Return IEC 61260-1 nominal frequency (float) for an exact mid-band frequency.
+
+    For standard fractions (1, 3), snaps to the IEC preferred table via
+    ``normalizedfreq``.  For non-standard fractions, falls back to Annex E.3
+    significant-figure rounding (``_iec_e3_round``).
+    """
+    frac = round(fraction)
+    if np.isclose(fraction, frac) and frac in (1, 3):
+        extended = _extended_preferred(frac)
+        return min(extended, key=lambda f: abs(np.log(f / exact_freq)))
+    return _iec_e3_round(exact_freq)
+
+
+def _format_nominal_freq(f: float) -> str:
+    """Format a nominal frequency as a human-readable label string."""
+    if f >= 1000:
+        return f"{f / 1000:g}k"
+    return f"{f:g}"
+
+
+def normalizedfreq(fraction: int) -> List[float]:
+    """
+    Get standardized IEC center frequencies.
+
+    :param fraction: 1 or 3 (Octave or 1/3 Octave).
+    :return: List of standard frequencies.
+    """
+    predefined = {
+        1: [16, 31.5, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000],
+        3: [
+            12.5, 16, 20, 25, 31.5, 40, 50, 63, 80, 100, 125, 160, 200, 250, 315, 400, 500,
+            630, 800, 1000, 1250, 1600, 2000, 2500, 3150, 4000, 5000, 6300, 8000, 10000,
+            12500, 16000, 20000,
+        ],
+    }
+    if fraction not in predefined:
+        raise ValueError("Normalized frequencies only available for fraction=1 or 3")
+    return predefined[fraction]

phonometry/levels.py

@@ -0,0 +1,243 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Integrated and statistical sound levels (Leq, LAeq, LN percentiles).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Sequence
+
+import numpy as np
+
+from .parametric_filters import time_weighting, weighting_filter
+from .utils import _typesignal
+
+_REF_PRESSURE = 2e-5
+
+
+def _level_db(mean_square: np.ndarray, calibration_factor: float, dbfs: bool) -> np.ndarray:
+    """Convert mean-square values to dB SPL (re 20 uPa) or dBFS."""
+    eps = np.finfo(float).eps
+    rms = np.sqrt(np.maximum(mean_square, eps))
+    if dbfs:
+        # dBFS is relative to digital full scale: calibration does not apply
+        # (consistent with OctaveFilterBank's dbfs mode).
+        return np.asarray(20 * np.log10(np.maximum(rms, eps)))
+    rms = rms * calibration_factor
+    return np.asarray(20 * np.log10(np.maximum(rms, eps) / _REF_PRESSURE))
+
+
+def _validate_level_input(x_proc: np.ndarray, calibration_factor: float) -> None:
+    """Shared validation for the public level functions."""
+    if x_proc.shape[-1] == 0:
+        raise ValueError("Input signal 'x' cannot be empty.")
+    if calibration_factor <= 0:
+        raise ValueError("'calibration_factor' must be positive.")
+
+
+def leq(
+    x: List[float] | np.ndarray,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+) -> float | np.ndarray:
+    """
+    Equivalent continuous sound level (Leq) over the whole signal.
+
+    :param x: Input signal (1D or 2D [channels, samples]), raw pressure units.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :param dbfs: If True, return dBFS (0 dB = RMS 1.0) instead of dB SPL.
+    :return: Scalar for 1D input, array of shape (channels,) for 2D input.
+    """
+    x_proc = _typesignal(x)
+    _validate_level_input(x_proc, calibration_factor)
+    ms = np.mean(x_proc**2, axis=-1)
+    out = _level_db(np.asarray(ms), calibration_factor, dbfs)
+    return float(out) if out.ndim == 0 else out
+
+
+def laeq(
+    x: List[float] | np.ndarray,
+    fs: int,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+) -> float | np.ndarray:
+    """
+    A-weighted equivalent continuous sound level (LAeq).
+
+    :param x: Input signal (1D or 2D [channels, samples]), raw pressure units.
+    :param fs: Sample rate in Hz.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :param dbfs: If True, return dBFS instead of dB SPL.
+    :return: Scalar for 1D input, array of shape (channels,) for 2D input.
+    """
+    return leq(weighting_filter(x, fs, "A"), calibration_factor, dbfs)
+
+
+def ln_levels(
+    x: List[float] | np.ndarray,
+    fs: int,
+    n: Sequence[int] = (10, 50, 90),
+    mode: str = "fast",
+    weighting: str | None = None,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+) -> Dict[int, float | np.ndarray]:
+    """
+    Statistical percentile levels (LN) from the time-weighted level envelope.
+
+    L10 is the level exceeded 10% of the time (90th percentile of the level
+    distribution), L90 the level exceeded 90% of the time, etc.
+
+    :param x: Input signal (1D or 2D [channels, samples]), raw pressure units.
+    :param fs: Sample rate in Hz.
+    :param n: Percentile exceedance values, e.g. (10, 50, 90).
+    :param mode: Time weighting for the envelope: 'fast', 'slow' or 'impulse'.
+    :param weighting: Optional frequency weighting: 'A', 'C', 'Z' or None.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :param dbfs: If True, return dBFS instead of dB SPL.
+    :return: Dict mapping each N to its level (scalar for 1D input,
+        array (channels,) for 2D input).
+    """
+    x_proc = _typesignal(x)
+    _validate_level_input(x_proc, calibration_factor)
+    for value in n:
+        if not 0 < value < 100:
+            raise ValueError("Percentile values in 'n' must be between 0 and 100.")
+    if weighting is not None and weighting.upper() != "Z":
+        x_proc = weighting_filter(x_proc, fs, weighting)
+
+    envelope = time_weighting(x_proc, fs, mode=mode)
+    # Discard the attack transient of the exponential integrator (~2*tau)
+    tau = {"fast": 0.125, "slow": 1.0, "impulse": 0.035}[mode.lower()]
+    skip = min(int(2 * tau * fs), envelope.shape[-1] // 2)
+    levels_db = _level_db(envelope[..., skip:], calibration_factor, dbfs)
+
+    result: Dict[int, float | np.ndarray] = {}
+    for value in n:
+        p = np.percentile(levels_db, 100 - value, axis=-1)
+        result[value] = float(p) if np.ndim(p) == 0 else np.asarray(p)
+    return result
+
+
+def lc_peak(
+    x: List[float] | np.ndarray,
+    fs: int,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+) -> float | np.ndarray:
+    """
+    C-weighted peak sound level, LCpeak (IEC 61672-1:2013, subclause 5.13).
+
+    The absolute maximum of the C-weighted signal, expressed in dB. This is
+    the quantity used by occupational-noise regulations (e.g. 135/137/140
+    dB(C) action limits). Verified against the reference one-cycle and
+    half-cycle responses of BS EN 61672-1:2013 Table 5 in the test suite.
+
+    :param x: Input signal (1D or 2D [channels, samples]), raw pressure units.
+    :param fs: Sample rate in Hz.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :param dbfs: If True, return dBFS (0 dB = peak 1.0) instead of dB SPL.
+    :return: Scalar for 1D input, array of shape (channels,) for 2D input.
+    """
+    x_proc = _typesignal(x)
+    _validate_level_input(x_proc, calibration_factor)
+    weighted = weighting_filter(x_proc, fs, "C")
+    peak = np.max(np.abs(weighted), axis=-1)
+    out = _level_db(np.asarray(peak) ** 2, calibration_factor, dbfs)
+    return float(out) if out.ndim == 0 else out
+
+
+def sel(
+    x: List[float] | np.ndarray,
+    fs: int,
+    weighting: str | None = None,
+    calibration_factor: float = 1.0,
+    dbfs: bool = False,
+) -> float | np.ndarray:
+    """
+    Sound exposure level (SEL / LAE): the event level normalized to 1 second.
+
+    ``SEL = Leq,T + 10*log10(T / 1 s)`` — the standard single-event metric
+    (aircraft flyovers, train passes). With ``weighting="A"`` this is LAE as
+    defined by IEC 61672-1:2013 (verified against the Table 4 toneburst
+    reference responses, Equation 8, in the test suite).
+
+    :param x: Input signal covering the whole event (1D or 2D).
+    :param fs: Sample rate in Hz.
+    :param weighting: Optional frequency weighting: 'A', 'C', 'Z' or None.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :param dbfs: If True, reference digital full scale instead of 20 uPa.
+    :return: Scalar for 1D input, array of shape (channels,) for 2D input.
+    """
+    x_proc = _typesignal(x)
+    _validate_level_input(x_proc, calibration_factor)
+    if fs <= 0:
+        raise ValueError("Sample rate 'fs' must be positive.")
+    if weighting is not None and weighting.upper() != "Z":
+        x_proc = weighting_filter(x_proc, fs, weighting)
+    duration_s = x_proc.shape[-1] / fs
+    base = leq(x_proc, calibration_factor, dbfs)
+    out = np.asarray(base) + 10 * np.log10(duration_s)
+    return float(out) if out.ndim == 0 else out
+
+
+def sound_exposure(
+    x: List[float] | np.ndarray,
+    fs: int,
+    duration_hours: float | None = None,
+    calibration_factor: float = 1.0,
+) -> float | np.ndarray:
+    """
+    A-weighted sound exposure E in pascal-squared hours (IEC 61252, 3.1).
+
+    The time integral of the squared A-weighted sound pressure. By default
+    the input is the whole event (E integrates over ``len(x)/fs``); pass
+    ``duration_hours`` to treat the input as a representative sample of a
+    longer exposure period (E = mean-square * duration). Anchors from
+    BS EN 61252:1995 (3.3 NOTE 4): 3.2 Pa²h <-> LEX,8h of exactly 90 dB.
+
+    :param x: Input signal in raw pressure units (1D or 2D).
+    :param fs: Sample rate in Hz.
+    :param duration_hours: Exposure period the input represents, in hours.
+        Default: the recording duration itself.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :return: Exposure in Pa²·h (scalar or per-channel array).
+    """
+    x_proc = _typesignal(x)
+    _validate_level_input(x_proc, calibration_factor)
+    if duration_hours is not None and duration_hours <= 0:
+        raise ValueError("'duration_hours' must be positive.")
+    p_a = weighting_filter(x_proc, fs, "A") * calibration_factor
+    mean_square = np.mean(p_a ** 2, axis=-1)
+    hours = duration_hours if duration_hours is not None else x_proc.shape[-1] / fs / 3600.0
+    out = np.asarray(mean_square * hours)
+    return float(out) if out.ndim == 0 else out
+
+
+def lex_8h(
+    x: List[float] | np.ndarray,
+    fs: int,
+    duration_hours: float | None = None,
+    calibration_factor: float = 1.0,
+) -> float | np.ndarray:
+    """
+    Normalized 8-h average sound level, LEX,8h (IEC 61252, 3.3).
+
+    The daily personal noise exposure level: the steady level that, sustained
+    over a nominal 8 h working day, carries the same A-weighted sound
+    exposure as the measured event. Identical to LEP,d (Directive 86/188/EEC)
+    and LEX,8h of ISO 1999 (BS EN 61252:1995, 3.3 NOTES 5-6).
+
+    :param x: Input signal in raw pressure units (1D or 2D).
+    :param fs: Sample rate in Hz.
+    :param duration_hours: Exposure period the input represents, in hours.
+        Default: the recording duration itself.
+    :param calibration_factor: Multiplier converting digital units to Pascals.
+    :return: LEX,8h in dB (scalar or per-channel array).
+    """
+    exposure = np.asarray(
+        sound_exposure(x, fs, duration_hours=duration_hours, calibration_factor=calibration_factor)
+    )
+    eps = np.finfo(float).eps
+    out = 10 * np.log10(np.maximum(exposure, eps) / (8.0 * _REF_PRESSURE ** 2))
+    return float(out) if out.ndim == 0 else out