python-peass 2.0.1__py3-none-any.whl → 2.0.1.2__py3-none-any.whl

peass/__init__.py

@@ -1,18 +1,30 @@
 """
 python-peass: Perceptual Evaluation methods for Audio Source Separation
-A modern, Pythonic port of the PEASS v2.0.1 toolkit [1].
+A modern, Pythonic port of the PEASS v2.0.1 toolkit.
 """
 
-__version__ = "2.0.1"
+__version__ = "2.0.1.2"  # matches peass version, with one more segment for me to edit
 
-from .decomposition import extract_distortion_components
-from .metrics import audio_quality_features
-from .metrics import calculate_energy_ratios
-from .predictor import predict_peass_scores
+from .config import DecomposedFilePaths
+from .config import DecomposedWaveforms
+from .config import DecompositionConfiguration
+from .config import DecompositionResult
+from .config import ModulationProcessingType
+from .config import PerceptualSeparationScores
+from .decomposition import decompose_distortion_components
+from .metrics import calculate_auditory_quality_features
+from .metrics import calculate_bss_eval_energy_ratios
+from .predictor import predict_perceptual_evaluation_scores
 
 __all__ = [
-    "predict_peass_scores",
-    "extract_distortion_components",
-    "calculate_energy_ratios",
-    "audio_quality_features",
+    "DecomposedFilePaths",
+    "DecomposedWaveforms",
+    "DecompositionConfiguration",
+    "DecompositionResult",
+    "ModulationProcessingType",
+    "PerceptualSeparationScores",
+    "predict_perceptual_evaluation_scores",
+    "decompose_distortion_components",
+    "calculate_bss_eval_energy_ratios",
+    "calculate_auditory_quality_features",
 ]

peass/auditory_model.py

@@ -1,158 +1,364 @@
 """
-PEASS Auditory Package - Dau 1996/1997 Psychoacoustic Ear Model [1, 2]
+PEASS Auditory Package - Dau 1996/1997 Psychoacoustic Ear Model
 
-This module ports the legacy C/MEX elements (haircell.c, adapt.c) into pure,
-performant Python [1, 3]. It simulates the transduction process of the inner hair cells
-and the temporal adaptation (forward masking) of the auditory nerve.
+Simulates the transduction process of the inner hair cells and the temporal
+adaptation (forward masking) of the auditory nerve. Uses Numba if available,
+and fails over gracefully to a SciPy/NumPy native vectorization.
 """
 
+import math
 from typing import Tuple
 
 import numpy as np
 import scipy.signal as signal
 
+from .config import ModulationProcessingType
 from .gammatone import GammatoneAnalyzer
+from .gammatone import fast_resample_poly
 
-# Check for Numba availability
+# -----------------------------------------------------------------------------
+# NUMBA JIT COMPILATION (WITH SAFE IMPORT FALLBACK)
+# -----------------------------------------------------------------------------
 try:
     import numba
 
     _HAS_NUMBA = True
+
+
+    @numba.njit(cache=True)
+    def _numba_fused_auditory_kernel(
+            subband_signals: np.ndarray,
+            sampling_frequency_hz: float,
+            haircell_filter_gain: float,
+            adaptation_bandwidths: np.ndarray,
+            absolute_hearing_threshold: float
+    ) -> np.ndarray:
+        """
+        Fused JIT kernel: Half-wave rectification, haircell lowpass,
+        and 5-stage non-linear adaptation executing natively in a single pass.
+        """
+        num_bands, num_samples = subband_signals.shape
+        output_signals = np.empty_like(subband_signals)
+
+        stage_thresholds = np.empty(5, dtype=np.float64)
+        stage_gains = np.empty(5, dtype=np.float64)
+
+        current_threshold = absolute_hearing_threshold
+        for stage_idx in range(5):
+            current_threshold = math.sqrt(current_threshold)
+            stage_thresholds[stage_idx] = current_threshold
+            stage_gains[stage_idx] = math.exp(-math.pi * adaptation_bandwidths[stage_idx] / sampling_frequency_hz)
+
+        haircell_factor = 1.0 - haircell_filter_gain
+
+        adaptation_factors = np.empty_like(stage_thresholds)
+        for band_idx in range(num_bands):
+            last_haircell_state = 0.0
+            for stage_idx in range(5):
+                adaptation_factors[stage_idx] = stage_thresholds[stage_idx]
+            for sample_idx in range(num_samples):
+                # 1. Half-wave rectification
+                current_value = subband_signals[band_idx, sample_idx]
+                if current_value < 0.0:
+                    current_value = 0.0
+
+                # 2. 1 kHz first-order lowpass filter (haircell transduction)
+                current_value = haircell_filter_gain * last_haircell_state + haircell_factor * current_value
+                last_haircell_state = current_value
+
+                # Minimum hearing threshold floor
+                if current_value < absolute_hearing_threshold:
+                    current_value = absolute_hearing_threshold
+
+                # 3. Unrolled 5-stage non-linear adaptation loops
+                for stage_idx in range(5):
+                    gain_value = stage_gains[stage_idx]
+                    threshold_value = stage_thresholds[stage_idx]
+                    active_factor = adaptation_factors[stage_idx]
+
+                    compressed_value = current_value / active_factor
+
+                    adaptation_factors[stage_idx] = max(
+                        (1.0 - gain_value) * compressed_value + gain_value * active_factor,
+                        threshold_value
+                    )
+                    current_value = compressed_value
+
+                output_signals[band_idx, sample_idx] = current_value
+
+        return output_signals
+
+
+    @numba.njit(cache=True)
+    def _numba_haircell_transduction_kernel(
+            subband_signals: np.ndarray,
+            sampling_frequency_hz: float
+    ) -> np.ndarray:
+        """
+        Dedicated JIT-compiled kernel for standalone haircell transduction.
+        """
+        num_bands, num_samples = subband_signals.shape
+        output_signals = np.empty_like(subband_signals)
+        haircell_filter_gain = math.exp(-math.pi * 2000.0 / sampling_frequency_hz)
+        haircell_factor = 1.0 - haircell_filter_gain
+
+        for band_idx in range(num_bands):
+            last_haircell_state = 0.0
+            for sample_idx in range(num_samples):
+                current_value = subband_signals[band_idx, sample_idx]
+                if current_value < 0.0:
+                    current_value = 0.0
+                current_value = haircell_filter_gain * last_haircell_state + haircell_factor * current_value
+                last_haircell_state = current_value
+                output_signals[band_idx, sample_idx] = current_value
+        return output_signals
+
+
+    @numba.njit(cache=True)
+    def _numba_adaptation_loops_kernel(
+            subband_signals: np.ndarray,
+            sampling_frequency_hz: float,
+            adaptation_bandwidths: np.ndarray,
+            absolute_hearing_threshold: float
+    ) -> np.ndarray:
+        """
+        Dedicated JIT-compiled kernel for standalone adaptation loops.
+        """
+        num_bands, num_samples = subband_signals.shape
+        output_signals = np.empty_like(subband_signals)
+
+        stage_thresholds = np.empty(5, dtype=np.float64)
+        stage_gains = np.empty(5, dtype=np.float64)
+
+        current_threshold = absolute_hearing_threshold
+        for stage_idx in range(5):
+            current_threshold = math.sqrt(current_threshold)
+            stage_thresholds[stage_idx] = current_threshold
+            stage_gains[stage_idx] = math.exp(-math.pi * adaptation_bandwidths[stage_idx] / sampling_frequency_hz)
+
+        adaptation_factors = np.empty_like(stage_thresholds)
+        for band_idx in range(num_bands):
+            for stage_idx in range(5):
+                adaptation_factors[stage_idx] = stage_thresholds[stage_idx]
+            for sample_idx in range(num_samples):
+                current_value = subband_signals[band_idx, sample_idx]
+                if current_value < absolute_hearing_threshold:
+                    current_value = absolute_hearing_threshold
+
+                for stage_idx in range(5):
+                    gain_value = stage_gains[stage_idx]
+                    threshold_value = stage_thresholds[stage_idx]
+                    active_factor = adaptation_factors[stage_idx]
+                    compressed_value = current_value / active_factor
+
+                    adaptation_factors[stage_idx] = max(
+                        (1.0 - gain_value) * compressed_value + gain_value * active_factor,
+                        threshold_value
+                    )
+                    current_value = compressed_value
+
+                output_signals[band_idx, sample_idx] = current_value
+
+        return output_signals
+
 except ImportError:
     _HAS_NUMBA = False
 
-if _HAS_NUMBA:
-    @numba.jit(nopython=True, cache=True)
-    def _numba_adaptation_loop(rx: np.ndarray, gain_val: float, sthresh: float, factor: np.ndarray) -> np.ndarray:
-        num_bands, num_samples = rx.shape
+
+# -----------------------------------------------------------------------------
+# PURE PYTHON/SCIPY FALLBACKS
+# -----------------------------------------------------------------------------
+def _fallback_adaptation_loops(
+        subband_signals: np.ndarray,
+        sampling_frequency_hz: float,
+        adaptation_bandwidths: np.ndarray,
+        absolute_hearing_threshold: float
+) -> np.ndarray:
+    """
+    Pure NumPy fallback for the nonlinear adaptation loops.
+    Vectorizes across the frequency bands to mitigate Python loop overhead.
+    """
+    num_samples = subband_signals.shape[1]
+    adapted_signals = np.maximum(subband_signals, absolute_hearing_threshold)
+    stage_threshold = absolute_hearing_threshold
+
+    for stage_idx in range(5):
+        adaptation_gain = math.exp(-math.pi * adaptation_bandwidths[stage_idx] / sampling_frequency_hz)
+        stage_threshold = math.sqrt(stage_threshold)
+        divisor_factors = np.full(subband_signals.shape[0], stage_threshold, dtype=np.float64)
+
         for sample_idx in range(num_samples):
-            for band_idx in range(num_bands):
-                val = rx[band_idx, sample_idx] / factor[band_idx]
-                rx[band_idx, sample_idx] = val
-                factor[band_idx] = max((1.0 - gain_val) * val + gain_val * factor[band_idx], sthresh)
-        return rx
+            current_values = adapted_signals[:, sample_idx] / divisor_factors
+            adapted_signals[:, sample_idx] = current_values
 
+            divisor_factors = np.maximum(
+                (1.0 - adaptation_gain) * current_values + adaptation_gain * divisor_factors,
+                stage_threshold
+            )
 
-def haircell_transduction(subband_signals: np.ndarray, sampling_frequency: float) -> np.ndarray:
-    """
-    Models the nonlinear mechanical-to-neural transduction of the inner hair cells.
-    Replaces haircell.c MEX script [2, 3].
+    return adapted_signals
 
-    Stages:
-      1. Half-wave rectification (simulates unidirectional shearing of hair bundle)
-      2. 1 kHz first-order lowpass filter (simulates inner hair cell membrane limits)
-    """
-    # % gain=exp(-pi*2000/fs);
-    # % rx=filter(1-gain,[1 -gain],max(rx,0),[],2);
-    gain_haircell = np.exp(-np.pi * 2000.0 / sampling_frequency)
-    b_hc = np.array([1.0 - gain_haircell])
-    a_hc = np.array([1.0, -gain_haircell])
 
-    # Process rectified signals over the sample dimension (axis 1)
+def _fallback_fused_auditory_kernel(
+        subband_signals: np.ndarray,
+        sampling_frequency_hz: float,
+        haircell_filter_gain: float,
+        adaptation_bandwidths: np.ndarray,
+        absolute_hearing_threshold: float
+) -> np.ndarray:
+    """
+    Pure SciPy/NumPy fallback executing identical math utilizing C-backends.
+    """
+    # 1. Half-wave rectification
     rectified_signals = np.maximum(subband_signals, 0.0)
-    return signal.lfilter(b_hc, a_hc, rectified_signals, axis=1)
 
+    # 2. Haircell 1 kHz first-order lowpass filter
+    numerator_coefficients = np.array([1.0 - haircell_filter_gain])
+    denominator_coefficients = np.array([1.0, -haircell_filter_gain])
+    transduced_signals = signal.lfilter(numerator_coefficients, denominator_coefficients, rectified_signals, axis=-1)
 
-def adaptation_loops(subband_signals: np.ndarray, sampling_frequency: float) -> np.ndarray:
-    """
-    Simulates the physiological adaptive properties of the auditory nerve.
-    Replaces adapt.c MEX script [2].
+    return _fallback_adaptation_loops(
+        transduced_signals, sampling_frequency_hz, adaptation_bandwidths, absolute_hearing_threshold
+    )
 
-    Runs 5 consecutive non-linear feedback loops modeling forward masking,
-    vectorized across all bands for optimal execution in Python.
-    """
-    dbrange = 100.0
-    thresh = 10.0 ** (-dbrange / 20.0)
-    bw_loop = 1.0 / (np.pi * np.array([0.005, 0.05, 0.129, 0.253, 0.5]))
 
-    # % rx=max(single(rx),thresh);
-    rx = np.maximum(subband_signals.astype(np.float32), thresh)
-    num_bands, num_samples = rx.shape
+# -----------------------------------------------------------------------------
+# EXPOSED API (STRICT PEP-484 TYPING)
+# -----------------------------------------------------------------------------
+def simulate_inner_haircell_transduction(
+        subband_signals: np.ndarray,
+        sampling_frequency_hz: float
+) -> np.ndarray:
+    """Models the nonlinear mechanical-to-neural transduction of the inner hair cells."""
+    if _HAS_NUMBA:
+        return _numba_haircell_transduction_kernel(subband_signals, sampling_frequency_hz)
+    else:
+        rectified_signals = np.maximum(subband_signals, 0.0)
+        haircell_filter_gain = math.exp(-math.pi * 2000.0 / sampling_frequency_hz)
+        numerator_coefficients = np.array([1.0 - haircell_filter_gain])
+        denominator_coefficients = np.array([1.0, -haircell_filter_gain])
+        return signal.lfilter(numerator_coefficients, denominator_coefficients, rectified_signals, axis=-1)
 
-    # Process each of the 5 adaptive stages
-    sthresh = thresh
-    for stage_idx in range(5):
-        gain_val = np.exp(-np.pi * bw_loop[stage_idx] / sampling_frequency)
-        sthresh = np.sqrt(sthresh)
-        factor = np.full(num_bands, sthresh, dtype=np.float32)  # divisor factor for each band
-
-        if _HAS_NUMBA:
-            # Compiled loop executing at native C speeds
-            rx = _numba_adaptation_loop(rx, float(gain_val), float(sthresh), factor)
-        else:
-            # Fallback pure-Python loop
-            for sample_idx in range(num_samples):
-                # Divide current sample by current divisor factor
-                val = rx[:, sample_idx] / factor
-                rx[:, sample_idx] = val
-                # Update divisor filter state
-                factor = np.maximum((1.0 - gain_val) * val + gain_val * factor, sthresh)
 
-    # % rx=double(dbrange/(1-sthresh))*(double(rx)-double(sthresh));
-    return (dbrange / (1.0 - sthresh)) * (rx - sthresh)
+def simulate_auditory_nerve_adaptation(
+        subband_signals: np.ndarray,
+        sampling_frequency_hz: float
+) -> np.ndarray:
+    """Simulates the physiological adaptive properties of the auditory nerve."""
+    decibel_range = 100.0
+    absolute_hearing_threshold = 10.0 ** (-decibel_range / 20.0)
+    adaptation_loop_bandwidths = 1.0 / (np.pi * np.array([0.005, 0.05, 0.129, 0.253, 0.5]))
+
+    if _HAS_NUMBA:
+        adapted_signals = _numba_adaptation_loops_kernel(
+            subband_signals, sampling_frequency_hz, adaptation_loop_bandwidths, absolute_hearing_threshold
+        )
+    else:
+        adapted_signals = _fallback_adaptation_loops(
+            subband_signals, sampling_frequency_hz, adaptation_loop_bandwidths, absolute_hearing_threshold
+        )
+
+    final_threshold = absolute_hearing_threshold
+    for _ in range(5):
+        final_threshold = math.sqrt(final_threshold)
+
+    return (decibel_range / (1.0 - final_threshold)) * (adapted_signals - final_threshold)
 
 
-def generate_internal_representation(
+def generate_auditory_internal_representation(
         signal_data: np.ndarray,
-        sampling_frequency: float,
-        modulation_processing_type: str = 'lp'
+        sampling_frequency_hz: float,
+        modulation_processing_type: ModulationProcessingType = ModulationProcessingType.LOWPASS
 ) -> Tuple[np.ndarray, float]:
-    """
-    Generates the 3D internal auditory representation of a signal.
-    Equivalent of pemo_internal.m [1].
-    """
+    """Generates the 3D internal auditory representation of a signal."""
     if len(signal_data.shape) > 1:
         if signal_data.shape[0] < signal_data.shape[1]:
             signal_data = signal_data.T
         signal_data = signal_data.ravel()
 
     # Model input scaling (1.0 becomes 100 dB SPL)
-    signal_data = 10.0 * signal_data
-
-    # Frequency analysis boundaries
-    fmin = 235.0
-    fmax = min(0.5 * sampling_frequency, 14500.0)
-    if sampling_frequency < 3.0 * fmax:
-        new_fs = int(round(1.5 * sampling_frequency))
-        signal_data = signal_data.astype(float)
-        signal_data = signal.resample(signal_data, int(round(len(signal_data) * new_fs / sampling_frequency)))
-        sampling_frequency = float(new_fs)
-
-    analyzer = GammatoneAnalyzer(sampling_frequency, fmin, 1000.0, fmax, 1.0)
-    num_bands = len(analyzer.filters)
-
-    # Subband analysis
-    subbands = np.real(analyzer.process(signal_data))
-
-    # Transduction and Adaptation stages
-    transduced = haircell_transduction(subbands, sampling_frequency)
-    adapted = adaptation_loops(transduced, sampling_frequency)
-
-    # Modulation Filtering & Downsampling
-    if modulation_processing_type == 'fb':
-        adapted = signal.resample(adapted, int(round(adapted.shape[1] * 800.0 / sampling_frequency)), axis=1)
-        sampling_frequency = 800.0
-        center_frequencies_mod = np.concatenate(([0.0, 5.0], 10.0 * (5.0 / 3.0) ** np.arange(6)))
-        bandwidth_mod = np.concatenate(([5.0, 5.0], 5.0 * (5.0 / 3.0) ** np.arange(6)))
+    scaled_signal_data = 10.0 * signal_data
+
+    minimum_frequency = 235.0
+    maximum_frequency = min(0.5 * sampling_frequency_hz, 14500.0)
+
+    # Decimate using polyphase FIR (avoids global FFT memory spikes)
+    if sampling_frequency_hz < 3.0 * maximum_frequency:
+        new_sampling_frequency = int(round(1.5 * sampling_frequency_hz))
+        # scaled_signal_data = signal.resample_poly(scaled_signal_data, new_sampling_frequency, int(sampling_frequency_hz))
+        scaled_signal_data = fast_resample_poly(
+            scaled_signal_data, new_sampling_frequency, int(sampling_frequency_hz)
+        )
+        sampling_frequency_hz = float(new_sampling_frequency)
+
+    # 1. Gammatone Analysis Filterbank
+    analyzer = GammatoneAnalyzer(sampling_frequency_hz, minimum_frequency, 1000.0, maximum_frequency, 1.0)
+    subbands = np.real(analyzer.process(scaled_signal_data))
+
+    # 2 & 3. Fused IHC Transduction and Nerve Adaptation
+    haircell_filter_gain = math.exp(-math.pi * 2000.0 / sampling_frequency_hz)
+    decibel_range = 100.0
+    absolute_hearing_threshold = 10.0 ** (-decibel_range / 20.0)
+    adaptation_loop_bandwidths = 1.0 / (np.pi * np.array([0.005, 0.05, 0.129, 0.253, 0.5]))
+
+    if _HAS_NUMBA:
+        adapted_signals = _numba_fused_auditory_kernel(
+            subbands, sampling_frequency_hz, haircell_filter_gain,
+            adaptation_loop_bandwidths, absolute_hearing_threshold
+        )
     else:
-        adapted = signal.resample(adapted, int(round(adapted.shape[1] * 100.0 / sampling_frequency)), axis=1)
-        sampling_frequency = 100.0
-        center_frequencies_mod = np.array([0.0])
-        bandwidth_mod = np.array([15.92])
+        adapted_signals = _fallback_fused_auditory_kernel(
+            subbands, sampling_frequency_hz, haircell_filter_gain,
+            adaptation_loop_bandwidths, absolute_hearing_threshold
+        )
+
+    # Global dB offset scaling
+    final_threshold = absolute_hearing_threshold
+    for _ in range(5):
+        final_threshold = math.sqrt(final_threshold)
+
+    adapted_signals = (decibel_range / (1.0 - final_threshold)) * (adapted_signals - final_threshold)
+
+    # 4. Modulation Filtering & Polyphase Decimation
+    if modulation_processing_type == ModulationProcessingType.FILTERBANK:
+        # downsampled_adapted = signal.resample_poly(adapted_signals, 800, int(sampling_frequency_hz), axis=-1)
+        downsampled_adapted = fast_resample_poly(adapted_signals, 800, int(sampling_frequency_hz), axis=-1)
+        sampling_frequency_hz = 800.0
+        modulation_center_frequencies = np.concatenate(([0.0, 5.0], 10.0 * (5.0 / 3.0) ** np.arange(6)))
+        modulation_bandwidths = np.concatenate(([5.0, 5.0], 5.0 * (5.0 / 3.0) ** np.arange(6)))
+    else:
+        # downsampled_adapted = signal.resample_poly(adapted_signals, 100, int(sampling_frequency_hz), axis=-1)
+        downsampled_adapted = fast_resample_poly(adapted_signals, 100, int(sampling_frequency_hz), axis=-1)
+        sampling_frequency_hz = 100.0
+        modulation_center_frequencies = np.array([0.0])
+        modulation_bandwidths = np.array([15.92])
+
+    num_bands = adapted_signals.shape[0]
+    num_modulations = len(modulation_center_frequencies)
+    num_samples = downsampled_adapted.shape[1]
 
-    num_modulations = len(center_frequencies_mod)
-    num_samples = adapted.shape[1]
     internal_representation = np.zeros((num_bands, num_samples, num_modulations), dtype=complex)
 
-    for m in range(num_modulations):
-        gain_val = np.exp(-np.pi * bandwidth_mod[m] / sampling_frequency)
-        b_mod = np.array([1.0 - gain_val])
-        a_mod = np.array([1.0, -gain_val * np.exp(2j * np.pi * center_frequencies_mod[m] / sampling_frequency)])
-        internal_representation[:, :, m] = signal.lfilter(b_mod, a_mod, adapted, axis=1)
+    for mod_idx in range(num_modulations):
+        filter_gain = math.exp(-math.pi * modulation_bandwidths[mod_idx] / sampling_frequency_hz)
+        numerator_coeffs = np.array([1.0 - filter_gain])
+        denominator_coeffs = np.array([
+            1.0,
+            -filter_gain * np.exp(2j * np.pi * modulation_center_frequencies[mod_idx] / sampling_frequency_hz)
+        ])
+
+        # Offloaded to SciPy C-backend
+        internal_representation[:, :, mod_idx] = signal.lfilter(
+            numerator_coeffs, denominator_coeffs, downsampled_adapted, axis=-1
+        )
 
-    # Hilbert envelope extraction above 10 Hz
-    above_10_hz = (center_frequencies_mod > 10.0)
-    internal_representation[:, :, ~above_10_hz] = np.real(internal_representation[:, :, ~above_10_hz])
-    internal_representation[:, :, above_10_hz] = np.abs(internal_representation[:, :, above_10_hz])
+    channels_above_10_hz = (modulation_center_frequencies > 10.0)
+    internal_representation[:, :, ~channels_above_10_hz] = np.real(
+        internal_representation[:, :, ~channels_above_10_hz]
+    )
+    internal_representation[:, :, channels_above_10_hz] = np.abs(
+        internal_representation[:, :, channels_above_10_hz]
+    )
 
-    return internal_representation, sampling_frequency
+    # Cast to real float64 since all imaginary parts have been discarded
+    return np.real(internal_representation), sampling_frequency_hz

peass/config.py

@@ -0,0 +1,73 @@
+"""
+PEASS Configuration and Data Structures
+"""
+
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from enum import auto
+from typing import Optional
+
+import numpy as np
+
+# Dynamically enable slots only on Python 3.10+
+# TODO: drop py3.9 support and just always include slots
+_DATACLASS_KWARGS = {"slots": True} if sys.version_info >= (3, 10) else {}
+
+
+class ModulationProcessingType(Enum):
+    """Defines the type of modulation processing used in the auditory model."""
+    LOWPASS = auto()
+    FILTERBANK = auto()
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class DecomposedWaveforms:
+    """Holds the in-memory NumPy arrays for the decomposed physical components."""
+    true_target: np.ndarray
+    target_distortion: np.ndarray
+    interference: np.ndarray
+    artifacts: np.ndarray
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class DecomposedFilePaths:
+    """Holds the absolute file paths to the generated WAV files on disk."""
+    true_target: str
+    target_distortion: str
+    interference: str
+    artifacts: str
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class DecompositionResult:
+    """Wrapper holding both the arrays and optional file paths of a decomposition."""
+    waveforms: DecomposedWaveforms
+    file_paths: Optional[DecomposedFilePaths] = None
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class DecompositionConfiguration:
+    """Structural configurations for the subband least-squares windowing."""
+    destination_directory: str = "./"
+    use_two_stage_projection: bool = False
+    frame_length_seconds: float = 0.5
+    filter_length_seconds: float = 0.04
+    shade_in_milliseconds: float = 10.0
+    shade_out_milliseconds: float = 10.0
+    segmentation_factor: int = 1
+
+
+@dataclass(**_DATACLASS_KWARGS)
+class PerceptualSeparationScores:
+    """Final assessment metrics representing the predicted subjective evaluation."""
+    overall_perceptual_score: float
+    target_perceptual_score: float
+    interference_perceptual_score: float
+    artifact_perceptual_score: float
+    source_to_distortion_ratio: float
+    source_to_spatial_distortion_ratio: float
+    source_to_interference_ratio: float
+    source_to_artifacts_ratio: float
+    decomposition_waveforms: Optional[DecomposedWaveforms] = None
+    decomposition_files: Optional[DecomposedFilePaths] = None