Generalized Wavelet Learning (GWL) for Tiny-Footprint Keyword Spotting

End-to-end learnable wavelet bank for audio classification. Trains fast on CPU and shines when labeled data are scarce. Benchmarked on Speech Commands v0.02 (“yes” vs. negatives).

---

TL;DR

• What: Learn K short parametric wavelets and classify with their energies (no spectrogram needed).
• Why: With very small training sets (<200 samples), GWL reaches ~0.80 acc / ~0.75 AUC in ~1 s/epoch on CPU; CNNs lag at this scale.
  With more data (≥10–20%), CNNs win on accuracy but run ~5–15× slower/epoch even on CUDA.
• Where: Embedded/CPU targets, rapid iteration, interpretable front-ends.

---

Features

• Differentiable, parametric wavelet bank (Gaussian window × small sinusoid mixtures).
• Fast FFT energy path for training; conv1d energy path for inference.
• Robust losses: logistic margin, energy log-ratio, or a hybrid.
• Diversity regularization via Gram-matrix penalty.
• Memmapped dataset cache for quick experiments.
• Side-by-side CNN baseline (log-Mel + SpecAugment) for comparison.
• Fractional-data sweeps and wall-clock timing per epoch.

---

Install

python -m venv .venv
source .venv/bin/activate
pip install torch torchaudio numpy scikit-learn
# optional (for boosting ablation):
pip install lightgbm


# Data

- **Dataset:** Google Speech Commands v0.02 (Warden)
- Auto-downloaded via `torchaudio` on first run.
- Audio cached as normalized **1 s @ 8 kHz** waveforms.

**Folders created**
- `_data/speechcommands` — raw dataset
- `_cache/sc_bin_8k` — memmapped waveforms (fs=8k, L=8001)
- `checkpoints` — saved models

---

# Quick Start (GWL)

- Tweak `PipelineCfg` (K, kernel length, losses, etc.).
- Run the notebook; it builds the cache, trains, and prints metrics + timing.

**Outputs include**
- Validation-selected threshold and fixed-threshold accuracies for **train/val/test**.
- **Per-epoch wall-clock** time, total training time, and average epoch time.

---

# CNN Baseline

Compact log-Mel + CNN with SpecAugment, AMP on CUDA, early stopping, and **identical splits**—apples-to-apples with GWL.

---

# Fractional Training Sweeps

Train on a **fraction** of the training split (keep full validation/test). Helpers are provided for both GWL and CNN (5 epochs per fraction by default).

## GWL (illustrative CPU results)

| frac | train_N | val_acc   | val_auc   | test_acc | avg_epoch_s |
|-----:|--------:|:----------|:----------|:---------|------------:|
| 0.01 |     307 | 0.80–0.82 | 0.73–0.76 | 0.80–0.82 | ~0.7 |
| 0.10 |    3077 | 0.83–0.84 | 0.78–0.79 | 0.83–0.84 | ~0.9 |
| 0.40 |   12307 | ~0.83     | ~0.78     | ~0.83     | ~1.6–1.7 |
| 1.00 |   30769 | ~0.84     | ~0.79     | ~0.84     | ~3.1 |



# TODO

- Rewrite functionality with proper module structure and library interface
- Add unsupervised learning functionality.
- Proper statistical testing