python-peass 2.0.1.1__tar.gz → 2.0.1.2__tar.gz

python_peass-2.0.1.2/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: python-peass
+Version: 2.0.1.2
+Summary: python-peass: Perceptual Evaluation methods for Audio Source Separation
+Author-email: Avery Khoo <avery.khoo@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+License-File: LICENSE
+Requires-Dist: numpy >= 1.19.0
+Requires-Dist: scipy >= 1.6.0
+Requires-Dist: soundfile >= 0.10.0
+Requires-Dist: numba >= 0.56.0 ; extra == "numba"
+Project-URL: Homepage, https://github.com/averykhoo/python-peass
+Project-URL: Source, https://github.com/averykhoo/python-peass
+Project-URL: Tracker, https://github.com/averykhoo/python-peass/issues
+Provides-Extra: numba
+
+# python-peass
+
+[![Test Suite](https://github.com/averykhoo/python-peass/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/averykhoo/python-peass/actions)
+[![PyPI version](https://img.shields.io/pypi/v/python-peass.svg)](https://pypi.org/project/python-peass/)
+
+> This project was ported by Gemini 3.5 Flash from
+> https://gitlab.inria.fr/bass-db/peass/-/tree/22c7fc4ef670f8bb6eea9ab4abea98323006b769/v2.0.1
+
+A Python port of the **PEASS v2.0.1** (Perceptual Evaluation methods for Audio Source Separation) toolkit [1].
+
+This package replaces traditional energy ratio metrics (SDR, SIR, SAR) with perceptually motivated objective scores—
+**OPS, TPS, IPS, and APS**—which align closely with subjective human listening evaluations [1].
+
+## Scientific Highlights
+
+Traditional evaluation metrics rely purely on linear energy ratios [1].
+However, human hearing relies on non-linear auditory transduction, temporal masking, and cognitive thresholds [2].
+`python-peass` executes a multi-stage cognitive simulation pipeline to assess separation quality:
+
+1. **Subband Least-Squares Decomposition:**
+   Signals are divided into subbands using a complex-valued Hohmann Gammatone Filterbank [1, 3].
+   Overlapping temporal frames are projected onto estimated subspaces to isolate physical target distortion,
+   interference, and artifact components [1].
+2. **Inner Hair Cell Transduction:**
+   Approximates the shearing limits of physical hair bundles via half-wave rectification and first-order 1 kHz
+   membrane-limit lowpass filters [1, 2].
+3. **Auditory Nerve Adaptation:**
+   Models physiological forward masking and metabolic neural depletion via five cascaded stages of non-linear feedback
+   loops [2].
+4. **Perceptual Assimilation:**
+   Models cognitive threshold masking where noise below a target reference threshold is partially assimilated or
+   masked [2].
+5. **Score Prediction:**
+   Feeds weighted similarity percentiles into a multi-criteria trained sigmoidal neural network to output scores scaled
+   from `0` to `100` [1].
+
+## Installation
+
+For standard execution, you can install the package directly:
+
+```bash
+pip install "python-peass[numba]"
+```
+
+If you require high-speed execution (using optimized vector libraries like Intel MKL or Apple Accelerate), it is recommended to install NumPy and SciPy via Conda first, and then install the package:
+
+```bash
+conda install --update numpy scipy
+pip install "python-peass[numba]"
+```
+
+## Quick Start Examples
+
+### 1. Perceptual Quality Score Evaluation
+
+Evaluate estimated audio files saved on disk:
+
+```python
+from peass import predict_perceptual_evaluation_scores
+
+original_files = [
+    "audio/target_source.wav",
+    "audio/interference_1.wav",
+    "audio/interference_2.wav"
+]
+estimate_file = "audio/estimated_target.wav"
+
+scores = predict_perceptual_evaluation_scores(original_files, estimate_file)
+
+print(f"Overall Perceptual Score (OPS): {scores.overall_perceptual_score:.1f}/100")
+print(f"Target Preservation Score (TPS): {scores.target_perceptual_score:.1f}/100")
+print(f"Interference Rejection (IPS):   {scores.interference_perceptual_score:.1f}/100")
+print(f"Artifact-free Score (APS):      {scores.artifact_perceptual_score:.1f}/100")
+```
+
+### 2. Score Evaluation with Waveform and File Expositions
+
+To run the full perceptual scoring pipeline and simultaneously output the physically separated WAV files (True target,
+Target distortion, Interference, and Artifacts) to a specific output folder:
+
+```python
+from peass import predict_perceptual_evaluation_scores, DecompositionConfiguration
+
+original_files = [
+    "audio/target_source.wav",
+    "audio/interferer.wav"
+]
+estimate_file = "audio/estimated_target.wav"
+
+# 1. Configure the output directory for file-writing
+config = DecompositionConfiguration(destination_directory="./output_directory/")
+
+# 2. Set return_decomposition=True to expose the physical waveforms and file paths
+scores = predict_perceptual_evaluation_scores(
+    original_files,
+    estimate_file,
+    configuration=config,
+    return_decomposition=True
+)
+
+# 3. Print overall scores
+print(f"Overall Perceptual Score (OPS): {scores.overall_perceptual_score:.1f}/100")
+
+# 4. Access the file paths of the generated WAV files on disk
+print(f"True target file saved at:      {scores.decomposition_files.true_target}")
+print(f"Interference file saved at:     {scores.decomposition_files.interference}")
+print(f"Artifacts file saved at:        {scores.decomposition_files.artifacts}")
+
+# 5. Read the raw NumPy arrays directly from memory
+target_distortion_array = scores.decomposition_waveforms.target_distortion
+```
+
+### 3. Independent Subband Least-Squares Decomposition
+
+You can run the auditory Gammatone/least-squares decomposition engine independently to obtain the isolated physical
+sub-components:
+
+```python
+import numpy as np
+from peass import decompose_distortion_components
+
+# In-memory arrays
+target_array = np.random.randn(16000, 1)
+noise_array = np.random.randn(16000, 1)
+estimate_array = target_array + 0.05 * noise_array
+
+# Run subband least-squares decomposer
+result = decompose_distortion_components(
+    source_files=[target_array, noise_array],
+    estimate_file=estimate_array,
+    sampling_frequency_hz=16000.0
+)
+
+waveforms = result.waveforms
+true_target, target_distortion, interference, artifacts = (
+    waveforms.true_target,
+    waveforms.target_distortion,
+    waveforms.interference,
+    waveforms.artifacts
+)
+```
+
+---
+
+## Test Suite & CI/CD
+
+The validation suite implements rigorous numerical, physical, and integration checks.
+You will need to `pip install -r requirements.txt` to set up.
+
+### Regression Verification
+
+We test our output waveforms directly against the original `.wav` reference waveforms generated by the official MATLAB
+PEASS toolbox (located in `references/peass_master_22c7fc4e/v2.0.1/example/`).
+Python's outputs must achieve a cross-correlation coefficient exceeding $0.95$ with the MATLAB reference to pass.
+
+### Parallel Execution
+
+To run the test suite across multiple CPU cores using `pytest-xdist`, execute:
+
+```bash
+pytest -n auto
+```
+
+---
+
+## References
+
+1. **V. Emiya, E. Vincent, N. Harlander, and V. Hohmann**,
+   *"Subjective and objective quality assessment of audio source separation"*,
+   IEEE Transactions on Audio, Speech, and Language Processing, 19(7):2046–2057, 2011.
+2. **R. Huber and B. Kollmeier**,
+   *"PEMO-Q — A New Method for Objective Audio Quality Assessment Using a Model of Auditory Perception"*,
+   IEEE Transactions on Audio, Speech, and Language Processing, 14(6):1902–1911, 2006.
+3. **V. Hohmann**,
+   *"Frequency analysis and synthesis using a Gammatone filterbank"*,
+   Acustica/Acta Acustica, 88(3):433–442, 2002.
+

python_peass-2.0.1.2/README.md

@@ -0,0 +1,176 @@
+# python-peass
+
+[![Test Suite](https://github.com/averykhoo/python-peass/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/averykhoo/python-peass/actions)
+[![PyPI version](https://img.shields.io/pypi/v/python-peass.svg)](https://pypi.org/project/python-peass/)
+
+> This project was ported by Gemini 3.5 Flash from
+> https://gitlab.inria.fr/bass-db/peass/-/tree/22c7fc4ef670f8bb6eea9ab4abea98323006b769/v2.0.1
+
+A Python port of the **PEASS v2.0.1** (Perceptual Evaluation methods for Audio Source Separation) toolkit [1].
+
+This package replaces traditional energy ratio metrics (SDR, SIR, SAR) with perceptually motivated objective scores—
+**OPS, TPS, IPS, and APS**—which align closely with subjective human listening evaluations [1].
+
+## Scientific Highlights
+
+Traditional evaluation metrics rely purely on linear energy ratios [1].
+However, human hearing relies on non-linear auditory transduction, temporal masking, and cognitive thresholds [2].
+`python-peass` executes a multi-stage cognitive simulation pipeline to assess separation quality:
+
+1. **Subband Least-Squares Decomposition:**
+   Signals are divided into subbands using a complex-valued Hohmann Gammatone Filterbank [1, 3].
+   Overlapping temporal frames are projected onto estimated subspaces to isolate physical target distortion,
+   interference, and artifact components [1].
+2. **Inner Hair Cell Transduction:**
+   Approximates the shearing limits of physical hair bundles via half-wave rectification and first-order 1 kHz
+   membrane-limit lowpass filters [1, 2].
+3. **Auditory Nerve Adaptation:**
+   Models physiological forward masking and metabolic neural depletion via five cascaded stages of non-linear feedback
+   loops [2].
+4. **Perceptual Assimilation:**
+   Models cognitive threshold masking where noise below a target reference threshold is partially assimilated or
+   masked [2].
+5. **Score Prediction:**
+   Feeds weighted similarity percentiles into a multi-criteria trained sigmoidal neural network to output scores scaled
+   from `0` to `100` [1].
+
+## Installation
+
+For standard execution, you can install the package directly:
+
+```bash
+pip install "python-peass[numba]"
+```
+
+If you require high-speed execution (using optimized vector libraries like Intel MKL or Apple Accelerate), it is recommended to install NumPy and SciPy via Conda first, and then install the package:
+
+```bash
+conda install --update numpy scipy
+pip install "python-peass[numba]"
+```
+
+## Quick Start Examples
+
+### 1. Perceptual Quality Score Evaluation
+
+Evaluate estimated audio files saved on disk:
+
+```python
+from peass import predict_perceptual_evaluation_scores
+
+original_files = [
+    "audio/target_source.wav",
+    "audio/interference_1.wav",
+    "audio/interference_2.wav"
+]
+estimate_file = "audio/estimated_target.wav"
+
+scores = predict_perceptual_evaluation_scores(original_files, estimate_file)
+
+print(f"Overall Perceptual Score (OPS): {scores.overall_perceptual_score:.1f}/100")
+print(f"Target Preservation Score (TPS): {scores.target_perceptual_score:.1f}/100")
+print(f"Interference Rejection (IPS):   {scores.interference_perceptual_score:.1f}/100")
+print(f"Artifact-free Score (APS):      {scores.artifact_perceptual_score:.1f}/100")
+```
+
+### 2. Score Evaluation with Waveform and File Expositions
+
+To run the full perceptual scoring pipeline and simultaneously output the physically separated WAV files (True target,
+Target distortion, Interference, and Artifacts) to a specific output folder:
+
+```python
+from peass import predict_perceptual_evaluation_scores, DecompositionConfiguration
+
+original_files = [
+    "audio/target_source.wav",
+    "audio/interferer.wav"
+]
+estimate_file = "audio/estimated_target.wav"
+
+# 1. Configure the output directory for file-writing
+config = DecompositionConfiguration(destination_directory="./output_directory/")
+
+# 2. Set return_decomposition=True to expose the physical waveforms and file paths
+scores = predict_perceptual_evaluation_scores(
+    original_files,
+    estimate_file,
+    configuration=config,
+    return_decomposition=True
+)
+
+# 3. Print overall scores
+print(f"Overall Perceptual Score (OPS): {scores.overall_perceptual_score:.1f}/100")
+
+# 4. Access the file paths of the generated WAV files on disk
+print(f"True target file saved at:      {scores.decomposition_files.true_target}")
+print(f"Interference file saved at:     {scores.decomposition_files.interference}")
+print(f"Artifacts file saved at:        {scores.decomposition_files.artifacts}")
+
+# 5. Read the raw NumPy arrays directly from memory
+target_distortion_array = scores.decomposition_waveforms.target_distortion
+```
+
+### 3. Independent Subband Least-Squares Decomposition
+
+You can run the auditory Gammatone/least-squares decomposition engine independently to obtain the isolated physical
+sub-components:
+
+```python
+import numpy as np
+from peass import decompose_distortion_components
+
+# In-memory arrays
+target_array = np.random.randn(16000, 1)
+noise_array = np.random.randn(16000, 1)
+estimate_array = target_array + 0.05 * noise_array
+
+# Run subband least-squares decomposer
+result = decompose_distortion_components(
+    source_files=[target_array, noise_array],
+    estimate_file=estimate_array,
+    sampling_frequency_hz=16000.0
+)
+
+waveforms = result.waveforms
+true_target, target_distortion, interference, artifacts = (
+    waveforms.true_target,
+    waveforms.target_distortion,
+    waveforms.interference,
+    waveforms.artifacts
+)
+```
+
+---
+
+## Test Suite & CI/CD
+
+The validation suite implements rigorous numerical, physical, and integration checks.
+You will need to `pip install -r requirements.txt` to set up.
+
+### Regression Verification
+
+We test our output waveforms directly against the original `.wav` reference waveforms generated by the official MATLAB
+PEASS toolbox (located in `references/peass_master_22c7fc4e/v2.0.1/example/`).
+Python's outputs must achieve a cross-correlation coefficient exceeding $0.95$ with the MATLAB reference to pass.
+
+### Parallel Execution
+
+To run the test suite across multiple CPU cores using `pytest-xdist`, execute:
+
+```bash
+pytest -n auto
+```
+
+---
+
+## References
+
+1. **V. Emiya, E. Vincent, N. Harlander, and V. Hohmann**,
+   *"Subjective and objective quality assessment of audio source separation"*,
+   IEEE Transactions on Audio, Speech, and Language Processing, 19(7):2046–2057, 2011.
+2. **R. Huber and B. Kollmeier**,
+   *"PEMO-Q — A New Method for Objective Audio Quality Assessment Using a Model of Auditory Perception"*,
+   IEEE Transactions on Audio, Speech, and Language Processing, 14(6):1902–1911, 2006.
+3. **V. Hohmann**,
+   *"Frequency analysis and synthesis using a Gammatone filterbank"*,
+   Acustica/Acta Acustica, 88(3):433–442, 2002.

python_peass-2.0.1.2/peass/__init__.py

@@ -0,0 +1,30 @@
+"""
+python-peass: Perceptual Evaluation methods for Audio Source Separation
+A modern, Pythonic port of the PEASS v2.0.1 toolkit.
+"""
+
+__version__ = "2.0.1.2"  # matches peass version, with one more segment for me to edit
+
+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__ = [
+    "DecomposedFilePaths",
+    "DecomposedWaveforms",
+    "DecompositionConfiguration",
+    "DecompositionResult",
+    "ModulationProcessingType",
+    "PerceptualSeparationScores",
+    "predict_perceptual_evaluation_scores",
+    "decompose_distortion_components",
+    "calculate_bss_eval_energy_ratios",
+    "calculate_auditory_quality_features",
+]