PyOctaveBand 1.0.1__py3-none-any.whl

pyoctaveband/__init__.py

@@ -0,0 +1,96 @@
+#  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 typing import List, Tuple, cast
+
+import matplotlib
+import numpy as np
+
+from .calibration import calculate_sensitivity
+from .core import OctaveFilterBank
+from .frequencies import getansifrequencies, normalizedfreq
+from .parametric_filters import linkwitz_riley, time_weighting, weighting_filter
+
+# Use non-interactive backend for plots
+matplotlib.use("Agg")
+
+# Public methods
+__all__ = [
+    "octavefilter",
+    "getansifrequencies",
+    "normalizedfreq",
+    "OctaveFilterBank",
+    "weighting_filter",
+    "time_weighting",
+    "linkwitz_riley",
+    "calculate_sensitivity",
+]
+
+
+def octavefilter(
+    x: List[float] | np.ndarray,
+    fs: int,
+    fraction: float = 1,
+    order: int = 6,
+    limits: List[float] | None = None,
+    show: bool = False,
+    sigbands: bool = False,
+    plot_file: str | None = None,
+    **kwargs: str | float | bool
+) -> Tuple[np.ndarray, List[float]] | Tuple[np.ndarray, List[float], 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 filter_type: (Optional) Type of filter ('butter', 'cheby1', 'cheby2', 'ellip', 'bessel'). Default: 'butter'.
+    :param ripple: (Optional) Passband ripple in dB (for cheby1, ellip). Default: 0.1.
+    :param attenuation: (Optional) Stopband attenuation in dB (for cheby2, ellip). Default: 60.0.
+    :param calibration_factor: (Optional) Sensitivity multiplier. Default: 1.0.
+    :param dbfs: (Optional) If True, return results in dBFS. Default: False.
+    :param mode: (Optional) 'rms' or 'peak'. Default: 'rms'.
+    :return: A tuple containing (SPL_array, Frequencies_list) or (SPL_array, Frequencies_list, signals).
+    :rtype: Union[Tuple[np.ndarray, List[float]], Tuple[np.ndarray, List[float], List[np.ndarray]]]
+    """
+    
+    # Use the class-based implementation
+    filter_bank = OctaveFilterBank(
+        fs=fs,
+        fraction=fraction,
+        order=order,
+        limits=limits,
+        filter_type=cast(str, kwargs.get("filter_type", "butter")),
+        ripple=cast(float, kwargs.get("ripple", 0.1)),
+        attenuation=cast(float, kwargs.get("attenuation", 60.0)),
+        show=show,
+        plot_file=plot_file,
+        calibration_factor=cast(float, kwargs.get("calibration_factor", 1.0)),
+        dbfs=cast(bool, kwargs.get("dbfs", False))
+    )
+    
+    return filter_bank.filter(x, sigbands=sigbands, mode=cast(str, kwargs.get("mode", "rms")))

pyoctaveband/calibration.py

@@ -0,0 +1,32 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Calibration utilities for mapping digital signals to physical SPL levels.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import numpy as np
+
+
+def calculate_sensitivity(
+    ref_signal: List[float] | np.ndarray, 
+    target_spl: float = 94.0, 
+    ref_pressure: float = 2e-5
+) -> float:
+    """
+    Calculate the calibration factor (multiplier) to convert digital units 
+    to Pascals based on a reference recording (e.g., 1kHz @ 94dB).
+    
+    :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).
+    :return: Calibration factor (sensitivity multiplier).
+    """
+    rms_ref = np.std(ref_signal)
+    if rms_ref == 0:
+        raise ValueError("Reference signal is silent, cannot calibrate.")
+        
+    factor = (ref_pressure * 10**(target_spl / 20)) / rms_ref
+    return float(factor)

pyoctaveband/core.py

@@ -0,0 +1,191 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Core processing logic and FilterBank class for pyoctaveband.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple, cast
+
+import numpy as np
+from scipy import signal
+
+from .filter_design import _design_sos_filter
+from .frequencies import _genfreqs
+from .utils import _downsamplingfactor, _resample_to_length, _typesignal
+
+
+class OctaveFilterBank:
+    """
+    A class-based representation of an Octave Filter Bank.
+    Allows for pre-calculating and reusing filter coefficients.
+    """
+    
+    def __init__(
+        self,
+        fs: int,
+        fraction: float = 1,
+        order: int = 6,
+        limits: List[float] | None = None,
+        filter_type: str = "butter",
+        ripple: float = 0.1,
+        attenuation: float = 60.0,
+        show: bool = False,
+        plot_file: str | None = None,
+        calibration_factor: float = 1.0,
+        dbfs: bool = False,
+    ) -> None:
+        """
+        Initialize the Octave Filter Bank.
+
+        :param fs: Sample rate in Hz.
+        :param fraction: Bandwidth fraction (e.g., 1 for octave, 3 for 1/3 octave).
+        :param order: Filter order.
+        :param limits: Frequency limits [f_min, f_max].
+        :param filter_type: Type of filter ('butter', 'cheby1', 'cheby2', 'ellip', 'bessel').
+        :param ripple: Passband ripple in dB.
+        :param attenuation: Stopband attenuation in dB.
+        :param show: If True, show the filter response plot.
+        :param plot_file: Path to save the filter response plot.
+        :param calibration_factor: Calibration factor for SPL calculation.
+        :param dbfs: If True, calculate SPL in dBFS.
+        """
+        if fs <= 0:
+            raise ValueError("Sample rate 'fs' must be positive.")
+        if fraction <= 0:
+            raise ValueError("Bandwidth 'fraction' must be positive.")
+        if order <= 0:
+            raise ValueError("Filter 'order' must be positive.")
+        if limits is None:
+            limits = [12, 20000]
+        if len(limits) != 2:
+            raise ValueError("Limits must be a list of two frequencies [f_min, f_max].")
+        if limits[0] <= 0 or limits[1] <= 0:
+            raise ValueError("Limit frequencies must be positive.")
+        if limits[0] >= limits[1]:
+            raise ValueError("The lower limit must be less than the upper limit.")
+            
+        valid_filters = ["butter", "cheby1", "cheby2", "ellip", "bessel"]
+        if filter_type not in valid_filters:
+            raise ValueError(f"Invalid filter_type. Must be one of {valid_filters}")
+
+        self.fs = fs
+        self.fraction = fraction
+        self.order = order
+        self.limits = limits
+        self.filter_type = filter_type
+        self.ripple = ripple
+        self.attenuation = attenuation
+        self.calibration_factor = calibration_factor
+        self.dbfs = dbfs
+
+        # Generate frequencies
+        self.freq, self.freq_d, self.freq_u = _genfreqs(limits, fraction, fs)
+        self.num_bands = len(self.freq)
+
+        # Calculate factors and design SOS
+        self.factor = _downsamplingfactor(self.freq_u, fs)
+        self.sos = _design_sos_filter(
+            self.freq, self.freq_d, self.freq_u, fs, order, self.factor, 
+            filter_type, ripple, attenuation, show, plot_file
+        )
+
+    def filter(
+        self, 
+        x: List[float] | np.ndarray, 
+        sigbands: bool = False,
+        mode: str = "rms"
+    ) -> Tuple[np.ndarray, List[float]] | Tuple[np.ndarray, List[float], List[np.ndarray]]:
+        """
+        Apply the pre-designed filter bank to a signal.
+
+        :param x: Input signal (1D array or 2D array [channels, samples]).
+        :param sigbands: If True, also return the signal in the time domain divided into bands.
+        :param mode: 'rms' for energy-based level, 'peak' for peak-holding level.
+        :return: A tuple containing (SPL_array, Frequencies_list) or (SPL_array, Frequencies_list, signals).
+        """
+        
+        # Convert input to numpy array
+        x_proc = _typesignal(x)
+
+        # Handle multichannel detection
+        is_multichannel = x_proc.ndim > 1
+        if not is_multichannel:
+            x_proc = x_proc[np.newaxis, :]  # Standardize to 2D
+
+        num_channels = x_proc.shape[0]
+
+        # Process signal across all bands and channels
+        spl, xb = self._process_bands(x_proc, num_channels, sigbands, mode=mode)
+
+        # Format output based on input dimensionality
+        if not is_multichannel:
+            spl = spl[0]
+            if sigbands and xb is not None:
+                xb = [band[0] for band in xb]
+
+        if sigbands and xb is not None:
+            return spl, self.freq, xb
+        else:
+            return spl, self.freq
+
+    def _process_bands(
+        self,
+        x_proc: np.ndarray,
+        num_channels: int,
+        sigbands: bool,
+        mode: str = "rms"
+    ) -> Tuple[np.ndarray, List[np.ndarray] | None]:
+        """
+        Process signal through each frequency band.
+
+        :param x_proc: Standardized 2D input signal [channels, samples].
+        :param num_channels: Number of channels.
+        :param sigbands: If True, return filtered bands.
+        :param mode: 'rms' or 'peak'.
+        :return: A tuple containing (SPL_array, Optional_List_of_filtered_signals).
+        """
+        spl = np.zeros([num_channels, self.num_bands])
+        xb: List[np.ndarray] | None = [np.array([]) for _ in range(self.num_bands)] if sigbands else None
+
+        for idx in range(self.num_bands):
+            for ch in range(num_channels):
+                # Core DSP logic extracted to reduce complexity
+                filtered_signal = self._filter_and_resample(x_proc[ch], idx)
+
+                # Sound Level Calculation
+                spl[ch, idx] = self._calculate_level(filtered_signal, mode)
+
+                if sigbands and xb is not None:
+                    # Restore original length
+                    y_resampled = _resample_to_length(filtered_signal, int(self.factor[idx]), x_proc.shape[1])
+                    if ch == 0:
+                        xb[idx] = np.zeros([num_channels, x_proc.shape[1]])
+                    xb[idx][ch] = y_resampled
+        return spl, xb
+
+    def _filter_and_resample(self, x_ch: np.ndarray, idx: int) -> np.ndarray:
+        """Resample and filter a single channel for a specific band."""
+        if self.factor[idx] > 1:
+            sd = signal.resample_poly(x_ch, 1, self.factor[idx])
+        else:
+            sd = x_ch
+        
+        return cast(np.ndarray, signal.sosfilt(self.sos[idx], sd))
+
+    def _calculate_level(self, y: np.ndarray, mode: str) -> float:
+        """Calculate the level (RMS or Peak) in dB."""
+        if mode.lower() == "rms":
+            val_linear = np.std(y)
+        elif mode.lower() == "peak":
+            val_linear = np.max(np.abs(y))
+        else:
+            raise ValueError("Invalid mode. Use 'rms' or 'peak'.")
+
+        if self.dbfs:
+            # dBFS: 0 dB is RMS = 1.0 or Peak = 1.0
+            return float(20 * np.log10(np.max([val_linear, np.finfo(float).eps])))
+        
+        # Physical SPL: apply sensitivity and use 20uPa reference
+        pressure_pa = val_linear * self.calibration_factor
+        return float(20 * np.log10(np.max([pressure_pa, np.finfo(float).eps]) / 2e-5))

pyoctaveband/filter_design.py

@@ -0,0 +1,118 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Filter design and visualization for pyoctaveband.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import matplotlib.pyplot as plt
+import numpy as np
+from scipy import signal
+
+
+def _design_sos_filter(
+    freq: List[float],
+    freq_d: List[float],
+    freq_u: List[float],
+    fs: int,
+    order: int,
+    factor: np.ndarray,
+    filter_type: str,
+    ripple: float,
+    attenuation: float,
+    show: bool = False,
+    plot_file: str | None = None,
+) -> List[np.ndarray]:
+    """
+    Generate SOS coefficients for the filter bank.
+
+    :param freq: Center frequencies.
+    :param freq_d: Lower edge frequencies.
+    :param freq_u: Upper edge frequencies.
+    :param fs: Original sample rate.
+    :param order: Filter order.
+    :param factor: Downsampling factors per band.
+    :param filter_type: Type of filter.
+    :param ripple: Passband ripple (dB).
+    :param attenuation: Stopband attenuation (dB).
+    :param show: If True, plot response.
+    :param plot_file: Path to save plot.
+    :return: List of SOS coefficient arrays.
+    """
+    sos = [np.array([]) for _ in range(len(freq))]
+
+    for idx, (lower, upper) in enumerate(zip(freq_d, freq_u)):
+        fsd = fs / factor[idx]
+        wn = np.array([lower, upper]) / (fsd / 2)
+        
+        if filter_type == "butter":
+            sos[idx] = signal.butter(N=order, Wn=wn, btype="bandpass", output="sos")
+        elif filter_type == "cheby1":
+            sos[idx] = signal.cheby1(N=order, rp=ripple, Wn=wn, btype="bandpass", output="sos")
+        elif filter_type == "cheby2":
+            sos[idx] = signal.cheby2(N=order, rs=attenuation, Wn=wn, btype="bandpass", output="sos")
+        elif filter_type == "ellip":
+            sos[idx] = signal.ellip(N=order, rp=ripple, rs=attenuation, Wn=wn, btype="bandpass", output="sos")
+        elif filter_type == "bessel":
+            sos[idx] = signal.bessel(N=order, Wn=wn, btype="bandpass", norm="phase", output="sos")
+
+    if show or plot_file:
+        _showfilter(sos, freq, freq_u, freq_d, fs, factor, show, plot_file)
+
+    return sos
+
+def _showfilter(
+    sos: List[np.ndarray],
+    freq: List[float],
+    freq_u: List[float],
+    freq_d: List[float],
+    fs: int,
+    factor: np.ndarray,
+    show: bool = False,
+    plot_file: str | None = None,
+) -> None:
+    """
+    Visualize filter bank frequency response.
+
+    :param sos: List of SOS coefficients.
+    :param freq: Center frequencies.
+    :param freq_u: Upper edges.
+    :param freq_d: Lower edges.
+    :param fs: Original sample rate.
+    :param factor: Downsampling factors.
+    :param show: If True, show the plot.
+    :param plot_file: Path to save the plot.
+    """
+    wn = 8192
+    w = np.zeros([wn, len(freq)])
+    h: np.ndarray = np.zeros([wn, len(freq)], dtype=np.complex128)
+
+    for idx in range(len(freq)):
+        fsd = fs / factor[idx]
+        w[:, idx], h[:, idx] = signal.sosfreqz(sos[idx], worN=wn, whole=False, fs=fsd)
+
+    fig, ax = plt.subplots(figsize=(10, 6))
+    ax.semilogx(w, 20 * np.log10(abs(h) + np.finfo(float).eps), color="#1f77b4", linewidth=1.2)
+    ax.axhline(-3, color="#d62728", linestyle="--", alpha=0.5, linewidth=1, label="-3 dB")
+
+    ax.set_title("Filter Bank Frequency Response", fontweight="bold", pad=15)
+    ax.set_xlabel("Frequency [Hz]")
+    ax.set_ylabel("Amplitude [dB]")
+    ax.grid(which="major", color="#e0e0e0", linestyle="-")
+    ax.grid(which="minor", color="#e0e0e0", linestyle=":", alpha=0.4)
+
+    plt.xlim(freq_d[0] * 0.8, freq_u[-1] * 1.2)
+    plt.ylim(-4, 1)
+
+    xticks = [16, 31.5, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000]
+    xticklabels = ["16", "31.5", "63", "125", "250", "500", "1k", "2k", "4k", "8k", "16k"]
+    ax.set_xticks(xticks)
+    ax.set_xticklabels(xticklabels)
+
+    if plot_file:
+        plt.savefig(plot_file, dpi=150, bbox_inches="tight")
+    if show:
+        plt.show()
+    plt.close(fig)

pyoctaveband/frequencies.py

@@ -0,0 +1,142 @@
+#  Copyright (c) 2026. Jose M. Requena-Plens
+"""
+Frequency calculation logic according to ANSI/IEC standards.
+"""
+
+from __future__ import annotations
+
+import warnings
+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]]:
+    """
+    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).
+    """
+    if limits is None:
+        limits = [12, 20000]
+
+    g = 10 ** (3 / 10)
+    fr = 1000
+
+    x = _initindex(limits[0], fr, g, fraction)
+    freq = np.array([_ratio(g, x, fraction) * fr])
+
+    freq_x = freq[0]
+    while freq_x * _bandedge(g, fraction) < limits[1]:
+        x += 1
+        freq_x = _ratio(g, x, fraction) * fr
+        freq = np.append(freq, freq_x)
+
+    freq_d = freq / _bandedge(g, fraction)
+    freq_u = freq * _bandedge(g, fraction)
+
+    return freq.tolist(), freq_d.tolist(), freq_u.tolist()
+
+
+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]]:
+    """
+    Determine band frequencies within limits.
+
+    :param limits: [f_min, f_max].
+    :param fraction: Bandwidth fraction.
+    :param fs: Sample rate.
+    :return: Tuple of center, lower, and upper frequencies.
+    """
+    freq, freq_d, freq_u = getansifrequencies(fraction, limits)
+    return _deleteouters(freq, freq_d, freq_u, fs)
+
+
+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]