Initial commit: mPCG Wav2Vec heart-sound classification and synthetic augmentation

Code for "Scaling to Multimodal and Multichannel Heart Sound Classification with Synthetic and
Augmented Biosignals" (Marocchi et al. 2025, arXiv:2509.11606): augmentation-supported
fine-tuning of a pre-trained Wav2Vec 2.0 encoder across single-channel PCG, synchronised
PCG+ECG, and multichannel vest settings. The augmentation and generative synthetic-signal
approach (WaveGrad, DiffWave) is inspired by Abbott et al. 2025 (arXiv:2410.10125).

Includes NumPy and batched GPU-capable tensor signal processing/augmentation, DiffWave and
WaveGrad generators, classification and ablation runners (single-PCG, PCG+ECG two-branch,
vest, synthetic-schedule, leave-source-DB-out), split-CSV generation, results aggregation,
a CLI, reproduction docs, and tests.

Author: MilanMarocchi

.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Torch / experiment artefacts
+*.pt
+*.ckpt
+runs/
+modelout/
+logs/
+generated_data/
+lightning_logs/
+splits/
+results/
+tables/
+generated/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the papers below."
+title: >-
+  Scaling to Multimodal and Multichannel Heart Sound Classification with Synthetic and
+  Augmented Biosignals
+authors:
+  - family-names: Marocchi
+    given-names: Milan
+  - family-names: Fynn
+    given-names: Matthew
+  - family-names: Mandana
+    given-names: Kayapanda
+  - family-names: Rong
+    given-names: Yue
+year: 2025
+identifiers:
+  - type: other
+    value: "arXiv:2509.11606"
+url: "https://arxiv.org/abs/2509.11606"
+references:
+  - type: article
+    title: >-
+      Generative Deep Learning and Signal Processing for Data Augmentation of Cardiac
+      Auscultation Signals: Improving Model Robustness Using Synthetic Audio
+    authors:
+      - family-names: Abbott
+        given-names: Leigh
+      - family-names: Marocchi
+        given-names: Milan
+      - family-names: Fynn
+        given-names: Matthew
+      - family-names: Rong
+        given-names: Yue
+      - family-names: Nordholm
+        given-names: Sven
+    year: 2025
+    identifiers:
+      - type: other
+        value: "arXiv:2410.10125"
+    url: "https://arxiv.org/abs/2410.10125"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Milan Marocchi and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,116 @@
+# mPCG Wav2Vec
+
+Code for augmentation-supported fine-tuning of a pre-trained Wav2Vec 2.0 encoder for abnormal
+heart-sound classification, with synthetic data generated by denoising-diffusion models
+(WaveGrad and DiffWave). This is the code for:
+
+> M. Marocchi, M. Fynn, K. Mandana, Y. Rong. *Scaling to Multimodal and Multichannel Heart Sound
+> Classification with Synthetic and Augmented Biosignals.* arXiv:2509.11606, 2025.
+> https://arxiv.org/abs/2509.11606
+
+The augmentation and generative synthetic-signal approach builds on and is inspired by:
+
+> L. Abbott, M. Marocchi, M. Fynn, Y. Rong, S. Nordholm. *Generative Deep Learning and Signal
+> Processing for Data Augmentation of Cardiac Auscultation Signals: Improving Model Robustness
+> Using Synthetic Audio.* arXiv:2410.10125, 2025. https://arxiv.org/abs/2410.10125
+
+## Overview
+
+The pipeline covers three classification settings and one synthetic-generation stage:
+
+| Setting | Data | Model |
+|---|---|---|
+| Single-channel PCG | CinC 2016 (16 kHz) | Wav2Vec 2.0 + MLP head |
+| PCG + ECG | Training-A (4.125 kHz) | two-branch fusion (`big_rnn:2:wav2vec`) |
+| Multichannel PCG | wearable vest (4.125 kHz) | Wav2Vec 2.0 + time-varying sinc beamformer, optional LoRA |
+| Synthetic generation | CinC / vest | DiffWave and WaveGrad (mel- and label-conditioned) |
+
+Signal processing, augmentation and preprocessing are available in both a NumPy form and a
+batched, GPU-capable tensor form (`mpcg_wav2vec.signalproc.torchproc`,
+`mpcg_wav2vec.augment.torchaug`) that operate on whole batches at once.
+
+## Layout
+
+```
+src/mpcg_wav2vec/
+  signalproc/   filtering, normalisation, Schmidt despiking, resampling, mel-spectrograms,
+                segmentation; batched tensor equivalents in torchproc.py
+  augment/      HPSS, noise, time/amplitude warp, parametric EQ, baseline wander (+ real-noise
+                sources); batched tensor augmentation in torchaug.py
+  datasets/     CinC / vest / generative / generated loaders, label vocabularies, schedules
+  generative/   DiffWave, WaveGrad, diffusion schedules, samplers, trainer, generation
+  classify/     Wav2Vec classifier, two-branch fusion, beamformer, metrics, trainer, evaluation, SVM
+  experiments/  runners for the three settings + synthetic-schedule and leave-source-DB-out
+  cli.py        command-line entry point
+tests/          unit, smoke and numerical-equivalence tests
+docs/           REPRODUCE.md (all experiments/ablations) and DATA.md (data acquisition)
+scripts/        run_generators.sh, run_ablations.sh
+```
+
+## Install
+
+```bash
+uv venv && uv sync            # or: pip install -e .
+```
+
+The Wav2Vec 2.0 encoder (`facebook/wav2vec2-base-960h`) is downloaded from Hugging Face on first
+use; set `HF_HUB_OFFLINE=1` once it is cached.
+
+## Quick start
+
+```bash
+# Generate a patient-level, label-stratified split CSV from CinC REFERENCE.csv labels
+mpcg-wav2vec make-splits --data-dir <cinc>/training-a --out splits/training-a.csv --folds 5
+
+# Train a generator, then synthesise an augmentation dataset
+mpcg-wav2vec gen-train  --model diffwave --data-dir <cinc> --csv <ref.csv> --output-dir modelout/diffwave
+mpcg-wav2vec gen-sample --model diffwave --weights modelout/diffwave/weights.pt \
+                        --data-dir <cinc> --csv <ref.csv> --output-dir generated/diffwave --per-item 3
+
+# Classification
+mpcg-wav2vec classify-cinc --data-dir <cinc>   --csv <ref.csv> --mode pcg      --fs 16000
+mpcg-wav2vec classify-cinc --data-dir <traina> --csv <ref.csv> --mode pcg_ecg  --fs 4125
+mpcg-wav2vec classify-vest --data-dir <vest>   --csv <ref.csv> --channels 1,2,3,4,5,6 --lora
+```
+
+Every command accepts `--max-batches` (classification) / `--max-train-batches` (generation) for
+quick smoke runs. See **[docs/REPRODUCE.md](docs/REPRODUCE.md)** for the full experiment and
+ablation matrix, and **[docs/DATA.md](docs/DATA.md)** for data acquisition and the expected
+on-disk layout.
+
+**Monitoring & options.** Pass `--logdir runs/<name>` to any train/classify command to log
+metrics (and, for generators, periodic generated audio + mel images) to TensorBoard
+(`tensorboard --logdir runs`). Classification uses cross-entropy by default; the vest command
+also accepts `--loss contrastive-focal` (supervised-contrastive + cross-entropy + center loss).
+Generator training rearranges heart cycles by default when `--segment-dir` is given
+(`--no-rearrange` to disable); generation never rearranges.
+
+## Data layout
+
+* Records readable by `wfdb` at `<data-dir>/<patient>` (CinC/Training-A: channel 0 = PCG,
+  channel 1 = ECG; vest: one channel per microphone).
+* A reference CSV with a `patient` column, a binary label column (`abnormality`/`label`), and
+  per-fold split columns (`split`, `split2`, …) valued `train`/`valid`/`test`.
+
+## Preprocessing
+
+Following the paper, PCG is resampled, Schmidt spike-removed, band-limited (25–450 Hz) and
+abs-max normalised; ECG is resampled, band-limited (2–40 Hz) and abs-max normalised. Recordings
+are segmented into overlapping windows (4 s for CinC/Training-A, 2 s for vest; 0.25 s overlap;
+first 0.3 s discarded). Classification runs at 16 kHz for CinC and 4.125 kHz for Training-A and
+the vest data.
+
+## Tests
+
+```bash
+uv run --with pytest pytest
+```
+
+The suite covers the signal processing, augmentation, generators, datasets/schedules and
+classifier, and checks that the NumPy and batched tensor preprocessing paths agree.
+
+## Citation
+
+If you use this code, please cite the Marocchi et al. 2025 paper (this work), and the
+Abbott et al. 2025 paper for the augmentation and synthetic-signal methods it builds on. See
+[CITATION.cff](CITATION.cff) for both entries.