python-peass 2.0.1__py3-none-any.whl

peass/gammatone.py

@@ -0,0 +1,267 @@
+"""
+PEASS Auditory Package - Hohmann 2002 Gammatone Filterbank [1, 3]
+
+This module implements the complex-valued Gammatone Filterbank as described in [3].
+It provides complete physical modeling of frequency analysis, delay/phase alignment,
+and synthesize capabilities to reconstruct fullband audio from subbands.
+"""
+
+from typing import List
+
+import numpy as np
+import scipy.signal as signal
+
+
+def calculate_erb_bandwidth(center_frequency: float) -> float:
+    """
+    Computes the Equivalent Rectangular Bandwidth of auditory filters.
+
+    Formula defined in Eq. (13) of [3]:
+    % bw = 24.7*(.00437*fc+1);
+    """
+    return 24.7 * (0.00437 * center_frequency + 1.0)
+
+
+def frequency_to_erb_scale(frequency_hz: float) -> float:
+    """
+    Converts frequency in Hz to Equivalent Rectangular Bandwidth (ERB) scale.
+
+    Formula defined in Eq. (16) of [3]:
+    % ERBscale = GFB_Q * log(1 + Hz / (GFB_L * GFB_Q));
+    """
+    return 9.265 * np.log(1.0 + frequency_hz / (24.7 * 9.265))
+
+
+def erb_scale_to_frequency(erb_scale: float) -> float:
+    """
+    Converts Equivalent Rectangular Bandwidth (ERB) scale value to frequency in Hz.
+
+    Formula defined in Eq. (17) of [3]:
+    % Hz = (exp(ERBscale / GFB_Q) - 1) * (GFB_L * GFB_Q);
+    """
+    return (np.exp(erb_scale / 9.265) - 1.0) * (24.7 * 9.265)
+
+
+def get_center_frequencies(
+        filters_per_erb: float,
+        lower_cutoff_hz: float,
+        specified_center_hz: float,
+        upper_cutoff_hz: float
+) -> np.ndarray:
+    """
+    Constructs a vector of center frequencies equidistant on the ERB scale.
+    Equivalent to Gfb_center_frequencies.m [3].
+    """
+    lower_erb = frequency_to_erb_scale(lower_cutoff_hz)
+    specified_erb = frequency_to_erb_scale(specified_center_hz)
+    upper_erb = frequency_to_erb_scale(upper_cutoff_hz)
+
+    erbs_below_base = specified_erb - lower_erb
+    num_filters_below = int(np.floor(erbs_below_base * filters_per_erb))
+
+    start_erb = specified_erb - (num_filters_below / filters_per_erb)
+    center_erbs = np.arange(start_erb, upper_erb + 1e-9, 1.0 / filters_per_erb)
+    return erb_scale_to_frequency(center_erbs)
+
+
+class GammatoneFilter:
+    """
+    Represents a single 4th-order complex-valued all-pole Gammatone filter.
+    Equivalent to Gfb_Filter class in MATLAB [3].
+    """
+
+    def __init__(
+            self,
+            sampling_frequency: float,
+            center_frequency: float,
+            gamma_order: int = 4,
+            bandwidth_factor: float = 1.0
+    ):
+        self.gamma_order: int = gamma_order
+        self.sampling_frequency: float = sampling_frequency
+        self.center_frequency: float = center_frequency
+
+        # Auditory bandwidth scaling (Eq. 14 of [3])
+        audiological_erb = calculate_erb_bandwidth(center_frequency) * bandwidth_factor
+        a_gamma = (np.pi * math_factorial(2 * gamma_order - 2) * (2.0 ** -(2 * gamma_order - 2)) /
+                   (math_factorial(gamma_order - 1) ** 2))
+        b = audiological_erb / a_gamma
+
+        self.lambda_val: float = np.exp(-2.0 * np.pi * b / sampling_frequency)
+        self.beta: float = 2.0 * np.pi * center_frequency / sampling_frequency
+
+        # Complex pole coefficient
+        self.coefficient: complex = self.lambda_val * np.exp(1j * self.beta)
+        self.normalization_factor: float = 2.0 * (1.0 - np.abs(self.coefficient)) ** gamma_order
+        self.state: np.ndarray = np.zeros(gamma_order, dtype=complex)
+
+    def process(self, input_signal: np.ndarray) -> np.ndarray:
+        factor = self.normalization_factor
+        coeff = self.coefficient
+        filter_state = self.state * coeff
+
+        y = input_signal.copy()
+        b_stage = np.array([factor], dtype=complex)
+        a_stage = np.array([1.0, -coeff], dtype=complex)
+
+        new_state = np.zeros(self.gamma_order, dtype=complex)
+        for i in range(self.gamma_order):
+            b_coef = b_stage if i == 0 else np.array([1.0], dtype=complex)
+            zi = np.array([filter_state[i]], dtype=complex)
+            y, zf = signal.lfilter(b_coef, a_stage, y, zi=zi)
+            new_state[i] = zf[0]
+
+        self.state = new_state / coeff
+        return y
+
+    def clear_state(self) -> None:
+        """Resets the internal filter state to zeros."""
+        self.state = np.zeros(self.gamma_order, dtype=complex)
+
+
+class GammatoneAnalyzer:
+    """
+    A collection of GammatoneFilters acting as an analysis filterbank.
+    Equivalent to Gfb_Analyzer class in MATLAB [3].
+    """
+
+    def __init__(
+            self,
+            sampling_frequency: float,
+            lower_cutoff_hz: float,
+            specified_center_hz: float,
+            upper_cutoff_hz: float,
+            filters_per_erb: float,
+            gamma_order: int = 4,
+            bandwidth_factor: float = 1.0
+    ):
+        self.sampling_frequency: float = sampling_frequency
+        self.center_frequencies: np.ndarray = get_center_frequencies(
+            filters_per_erb, lower_cutoff_hz, specified_center_hz, upper_cutoff_hz
+        )
+        self.filters: List[GammatoneFilter] = [
+            GammatoneFilter(sampling_frequency, cf, gamma_order, bandwidth_factor)
+            for cf in self.center_frequencies
+        ]
+        self.bandwidths: np.ndarray = calculate_erb_bandwidth(self.center_frequencies)
+
+    def process(self, input_signal: np.ndarray) -> np.ndarray:
+        num_bands = len(self.filters)
+        output = np.zeros((num_bands, input_signal.shape[0]), dtype=complex)
+        for band in range(num_bands):
+            output[band, :] = self.filters[band].process(input_signal)
+        return output
+
+    def get_z_response(self, z: np.ndarray) -> np.ndarray:
+        z_col = z[:, np.newaxis]
+        num_bands = len(self.filters)
+        response = np.ones((z_col.shape[0], num_bands), dtype=complex)
+        for band in range(num_bands):
+            coeff = self.filters[band].coefficient
+            norm = self.filters[band].normalization_factor
+            gamma = self.filters[band].gamma_order
+            response[:, band] = ((1.0 - coeff / z_col[:, 0]) ** -gamma) * norm
+        return response
+
+    def clear_state(self) -> None:
+        """Resets all filters' states to zeros."""
+        for filter_obj in self.filters:
+            filter_obj.clear_state()
+
+
+class GammatoneDelay:
+    """
+    Handles phase alignment and group delay estimation across subbands.
+    Equivalent to Gfb_Delay class in MATLAB [3].
+    """
+
+    def __init__(self, analyzer: GammatoneAnalyzer, delay_samples: int):
+        # Reset the analyzer states before analyzing the impulse response
+        analyzer.clear_state()
+
+        impulse = np.zeros(delay_samples + 2)
+        impulse[0] = 1.0
+
+        # Analyze impulse
+        impulse_response = analyzer.process(impulse)
+        num_bands = impulse_response.shape[0]
+
+        ir_slice = np.abs(impulse_response[:, :delay_samples + 1])
+        max_indices = np.argmax(ir_slice, axis=1)
+
+        self.delays_samples: np.ndarray = delay_samples - max_indices
+        slopes = np.zeros(num_bands, dtype=complex)
+        for band in range(num_bands):
+            idx = max_indices[band]
+            slopes[band] = impulse_response[band, idx + 1] - impulse_response[band, idx - 1]
+
+        slopes = slopes / np.abs(slopes)
+        self.phase_factors: np.ndarray = 1j / slopes
+        self.memory: np.ndarray = np.zeros((num_bands, int(np.max(self.delays_samples))), dtype=float)
+
+    def process(self, input_data: np.ndarray) -> np.ndarray:
+        num_bands, num_samples = input_data.shape
+        output = np.zeros((num_bands, num_samples))
+        for band in range(num_bands):
+            delay_val = int(self.delays_samples[band])
+            phase_corrected = np.real(input_data[band, :] * self.phase_factors[band])
+            if delay_val == 0:
+                output[band, :] = phase_corrected
+            else:
+                tmp_out = np.concatenate((self.memory[band, :delay_val], phase_corrected))
+                self.memory[band, :delay_val] = tmp_out[num_samples:]
+                output[band, :] = tmp_out[:num_samples]
+        return output
+
+
+class GammatoneMixer:
+    """
+    Optimizes subband synthesis gains to flat-response outputs.
+    Equivalent to Gfb_Mixer class in MATLAB [3].
+    """
+
+    def __init__(self, analyzer: GammatoneAnalyzer, delay: GammatoneDelay, iterations: int = 100):
+        center_frequencies = analyzer.center_frequencies
+        num_bands = len(center_frequencies)
+        fs = analyzer.sampling_frequency
+
+        z_c = np.exp(2j * np.pi * center_frequencies / fs)
+        self.gains: np.ndarray = np.ones(num_bands)
+
+        pos_response = analyzer.get_z_response(z_c)
+        neg_response = analyzer.get_z_response(np.conj(z_c))
+
+        for band in range(num_bands):
+            pos_response[:, band] = pos_response[:, band] * delay.phase_factors[band] * (
+                    z_c ** -delay.delays_samples[band])
+            neg_response[:, band] = neg_response[:, band] * delay.phase_factors[band] * (
+                    np.conj(z_c) ** -delay.delays_samples[band])
+
+        f_response = (pos_response + np.conj(neg_response)) / 2.0
+
+        for _ in range(iterations):
+            selected_spectrum = f_response @ self.gains
+            self.gains = self.gains / np.abs(selected_spectrum)
+
+    def process(self, input_data: np.ndarray) -> np.ndarray:
+        return self.gains @ input_data
+
+
+class GammatoneSynthesizer:
+    """
+    Synthesizes multiple subband signals back into a single fullband waveform.
+    Equivalent to Gfb_Synthesizer class in MATLAB [3].
+    """
+
+    def __init__(self, analyzer: GammatoneAnalyzer, desired_delay_seconds: float):
+        self.delay = GammatoneDelay(analyzer, int(round(desired_delay_seconds * analyzer.sampling_frequency)))
+        self.mixer = GammatoneMixer(analyzer, self.delay)
+
+    def process(self, input_data: np.ndarray) -> np.ndarray:
+        delayed = self.delay.process(input_data)
+        return self.mixer.process(delayed)
+
+
+def math_factorial(n: int) -> int:
+    """Standard integer factorial calculation."""
+    return 1 if n <= 1 else n * math_factorial(n - 1)

peass/metrics.py

@@ -0,0 +1,147 @@
+"""
+PEASS Metrics Package - Auditory Features & Similarity Metrics [1, 2]
+
+This module computes the perceptual features and linear/energy ratio calculations
+such as SDR, ISR, SIR, and SAR [1]. It houses the core PEMO-Q time-frequency
+cross-correlation engine.
+"""
+
+from typing import Tuple
+
+import numpy as np
+
+from .auditory_model import generate_internal_representation
+
+
+def calculate_energy_ratios(
+        s_true: np.ndarray,
+        e_target: np.ndarray,
+        e_interf: np.ndarray,
+        e_artif: np.ndarray
+) -> Tuple[float, float, float, float]:
+    """
+    Computes standard BSS Eval energy ratio metrics from physically decomposed components.
+    Replaces ISR_SIR_SAR_fromNewDecomposition.m [1].
+    """
+    sTrue_flat = s_true.ravel()
+    eTarget_flat = e_target.ravel()
+    eInterf_flat = e_interf.ravel()
+    eArtif_flat = e_artif.ravel()
+
+    # Eq. (11), (12), (13) of Emiya 2011 [4]:
+    ISR = 10.0 * np.log10(np.sum(sTrue_flat ** 2) / np.sum(eTarget_flat ** 2))
+    SIR = 10.0 * np.log10(np.sum((sTrue_flat + eTarget_flat) ** 2) / np.sum(eInterf_flat ** 2))
+    SAR = 10.0 * np.log10(np.sum((sTrue_flat + eTarget_flat + eInterf_flat) ** 2) / np.sum(eArtif_flat ** 2))
+    SDR = 10.0 * np.log10(np.sum(sTrue_flat ** 2) / np.sum((eTarget_flat + eInterf_flat + eArtif_flat) ** 2))
+
+    return ISR, SIR, SAR, SDR
+
+
+def pemo_similarity_metric(internal_reference: np.ndarray, internal_test: np.ndarray,
+                           sampling_frequency: float) -> float:
+    """
+    Compares two internal representations to produce an auditory similarity metric.
+    Replaces pemo_metric.m [1].
+
+    Performs assimilation of masked content, local framing, cross-correlation,
+    moving RMS weighting, and percentile assessment [2].
+    """
+    nband, nsampl, nmod = internal_reference.shape
+
+    # Assimilation (Eq. of PEMO-Q [2]):
+    assim = (np.abs(internal_test) < np.abs(internal_reference))
+    internal_test[assim] = 0.25 * internal_reference[assim] + 0.75 * internal_test[assim]
+
+    # Convert frame sizes
+    flen = int(min(nsampl, 0.1 * sampling_frequency))
+    nfram = int(np.floor(nsampl / flen))
+    nsampl = nfram * flen
+
+    internal_reference = internal_reference[:, :nsampl, :]
+    internal_test = internal_test[:, :nsampl, :]
+
+    PSMt = np.zeros(nfram)
+    lPSM = np.zeros(nmod)
+    lNMS = np.zeros(nmod)
+
+    for t in range(nfram):
+        for m in range(nmod):
+            lref = internal_reference[:, t * flen: (t + 1) * flen, m]
+            lref_flat = lref.ravel()
+            lref_flat = lref_flat - np.mean(lref_flat)
+
+            ltest = internal_test[:, t * flen: (t + 1) * flen, m]
+            ltest_flat_orig = ltest.ravel()
+            lNMS[m] = np.sum(ltest_flat_orig ** 2)
+
+            ltest_flat = ltest_flat_orig - np.mean(ltest_flat_orig)
+            denom = np.sqrt(np.sum(lref_flat ** 2) * np.sum(ltest_flat ** 2))
+            lPSM[m] = np.sum(lref_flat * ltest_flat) / denom if denom != 0 else 0.0
+
+        sum_lnms = np.sum(lNMS)
+        PSMt[t] = np.sum(lPSM * lNMS) / sum_lnms if sum_lnms != 0 else 0.0
+
+    # From local to global similarity
+    ilen = int(1 * sampling_frequency)
+    mtest_sq = np.sum(internal_test ** 2, axis=(0, 2))
+
+    RMS = np.zeros(nfram)
+    for t in range(nfram):
+        start_idx = int(max(0, (t + 0.5) * flen - 0.5 * ilen))
+        end_idx = int(min(nsampl, (t + 0.5) * flen + 0.5 * ilen))
+        ltest = mtest_sq[start_idx:end_idx]
+        RMS[t] = np.mean(ltest) if len(ltest) > 0 else 0.0
+
+    # Sorted weighted percentile extraction
+    ind = np.argsort(PSMt)
+    PSMt_sorted = PSMt[ind]
+    RMS_sorted = RMS[ind]
+    RMS_cum = np.cumsum(RMS_sorted)
+
+    cutoff = 0.5 * RMS_cum[-1]
+    match_indices = np.where(RMS_cum >= cutoff)[0]
+
+    return PSMt_sorted[match_indices[0]] if len(match_indices) > 0 else 0.0
+
+
+def audio_quality_features(decomposition_signals: list[np.ndarray], sampling_frequency: float = 16000.0) -> Tuple[
+    float, float, float, float]:
+    """
+    Computes quality features by sending decomposed signals through the internal auditory model.
+    Replaces audioQualityFeatures.m [1].
+    """
+    sTrue, eTarget, eInterf, eArtif = decomposition_signals
+
+    if len(sTrue.shape) == 1:
+        sTrue = sTrue[:, np.newaxis]
+        eTarget = eTarget[:, np.newaxis]
+        eInterf = eInterf[:, np.newaxis]
+        eArtif = eArtif[:, np.newaxis]
+
+    testAll = sTrue + eTarget + eInterf + eArtif
+    NChan = sTrue.shape[1]
+
+    qTarget = np.zeros(NChan)
+    qInterf = np.zeros(NChan)
+    qArtif = np.zeros(NChan)
+    qGlobal = np.zeros(NChan)
+
+    for kChan in range(NChan):
+        mtest, fr = generate_internal_representation(testAll[:, kChan], sampling_frequency)
+
+        mref_t, _ = generate_internal_representation(sTrue[:, kChan] + eInterf[:, kChan] + eArtif[:, kChan],
+                                                     sampling_frequency)
+        qTarget[kChan] = pemo_similarity_metric(mref_t, mtest, fr)
+
+        mref_i, _ = generate_internal_representation(sTrue[:, kChan] + eTarget[:, kChan] + eArtif[:, kChan],
+                                                     sampling_frequency)
+        qInterf[kChan] = pemo_similarity_metric(mref_i, mtest, fr)
+
+        mref_a, _ = generate_internal_representation(sTrue[:, kChan] + eTarget[:, kChan] + eInterf[:, kChan],
+                                                     sampling_frequency)
+        qArtif[kChan] = pemo_similarity_metric(mref_a, mtest, fr)
+
+        mref_g, _ = generate_internal_representation(sTrue[:, kChan], sampling_frequency)
+        qGlobal[kChan] = pemo_similarity_metric(mref_g, mtest, fr)
+
+    return np.min(qTarget), np.min(qInterf), np.min(qArtif), np.min(qGlobal)

peass/predictor.py

@@ -0,0 +1,131 @@
+"""
+PEASS Predictor Package - Multi-Criteria Neural Network Regressor [1]
+
+This module maps raw auditory similarity scores (qTarget, qInterf, qArtif, qGlobal)
+to Predicted Perceptual Scores (OPS, TPS, IPS, APS) on a scale from 0 to 100
+using modern .npz parameter loading [1].
+"""
+
+import os
+import pathlib
+from typing import Any
+from typing import Dict
+from typing import Union
+
+import numpy as np
+import soundfile as sf
+
+from .decomposition import extract_distortion_components
+from .metrics import audio_quality_features
+from .metrics import calculate_energy_ratios
+
+
+def my_mapping(features: np.ndarray, weights: np.ndarray, bias: np.ndarray, output_weights: np.ndarray,
+               output_bias: np.ndarray) -> float:
+    """
+    Evaluates forward propagation through the two-layer perceptron.
+    Replaces myMapping.m [1].
+    """
+    if len(features.shape) == 1:
+        features = features[:, np.newaxis]
+
+    # Hidden layer
+    s1 = weights @ features + bias
+    o1 = 1.0 / (1.0 + np.exp(-s1))
+
+    # Output layer
+    s2 = output_weights.T @ o1 + output_bias
+    y = 100.0 / (1.0 + np.exp(-s2))
+
+    return float(y[0, 0])
+
+
+def predict_peass_scores(
+        original_files: list[Union[str, np.ndarray]],
+        estimate_file: Union[str, np.ndarray],
+        options: dict = None,
+        sampling_frequency: float = None,
+        return_decomposition: bool = False
+) -> Dict[str, Any]:
+    """
+    Wrapper entry point. Performs least-squares decomposition, generates auditory features,
+    and predicts Perceptual Evaluation scores [1].
+
+    Replaces PEASS_ObjectiveMeasure.m and map2SubjScale.m [1].
+
+    Args:
+        original_files: List of file paths or NumPy arrays of reference sources.
+        estimate_file: File path or NumPy array of the separated estimate.
+        options: Algorithmic tuning parameters dictionary.
+        sampling_frequency: Rate in Hz (required for in-memory array arrays).
+        return_decomposition: If True, returns the calculated waveform arrays/saved filepaths.
+
+    Returns:
+        dict: Containing OPS, TPS, IPS, APS and decibel criteria.
+              If return_decomposition=True, includes "decomposition_arrays" (and
+              "decomposition_files" if inputting file paths).
+    """
+    # 1. Physical Decomposition
+    file_paths, decomposed_arrays = extract_distortion_components(original_files, estimate_file, options,
+                                                                  sampling_frequency)
+    s_true, e_target, e_interf, e_artif = decomposed_arrays
+
+    if sampling_frequency is None:
+        if isinstance(estimate_file, (str, pathlib.Path)):
+            _, sampling_frequency = sf.read(estimate_file)
+        else:
+            sampling_frequency = 16000.0
+
+    # 2. Traditional Energy Ratios
+    ISR, SIR, SAR, SDR = calculate_energy_ratios(s_true, e_target, e_interf, e_artif)
+
+    # 3. Auditory Feature Extraction
+    q_target, q_interf, q_artif, q_global = audio_quality_features(decomposed_arrays, sampling_frequency)
+
+    # 4. Neural Network Scoring Regressions
+    q_features = np.array([q_global, q_target, q_interf, q_artif])
+    q_mapped = np.clip(np.log((1.0 + q_features) / (1.0 - q_features)), -5.5, 5.5)
+
+    scores = np.zeros(4)
+    # Dynamically locate local parameters folder absolute path
+    pkg_dir = os.path.dirname(os.path.realpath(__file__))
+
+    for nTask in range(4):
+        npz_path = os.path.join(pkg_dir, "parameters", f"paramTask{nTask + 1}.npz")
+        mat_data = np.load(npz_path)
+
+        W = mat_data['W']
+        b = mat_data['b']
+        v = mat_data['v']
+        a = mat_data['a']
+        selec = mat_data['selec']
+
+        scores[nTask] = my_mapping(q_mapped[selec], W, b, v, a)
+
+    results = {
+        "OPS": float(scores[0]), # Overall Perceptual Score
+        "TPS": float(scores[1]), # Target-related Perceptual Score
+        "IPS": float(scores[2]), # Interference-related Perceptual Score
+        "APS": float(scores[3]), # Artifact-related Perceptual Score
+        "SDR": SDR,
+        "ISR": ISR,
+        "SIR": SIR,
+        "SAR": SAR
+    }
+
+    if return_decomposition:
+        results["decomposition_arrays"] = {
+            "true_target":       s_true,
+            "target_distortion": e_target,
+            "interference":      e_interf,
+            "artifacts":         e_artif
+        }
+        if file_paths:
+            results["decomposition_files"] = {
+                "true_target":       file_paths[0],
+                "target_distortion": file_paths[1],
+                "interference":      file_paths[2],
+                "artifacts":         file_paths[3]
+            }
+
+    return results