Audit: algorithmic/math correctness, prose accuracy, and student-facing comments (all lessons)

[jonfroehlich]

A deep, deliberate audit that goes beyond "does it run" (CI already covers execution) and beyond the Pass-3 readability review. For each lesson, double/triple-check three things:

1. Algorithmic & mathematical correctness — the code actually implements the technique correctly (edge cases, indexing, normalization, units), e.g.:
   • Quantization & Sampling: bit-depth/levels math, Nyquist, aliasing demo, the plot_audio vs plot_signal title bug (Quantization & Sampling notebook: plot_signal called with quantization_bits in the title slot (should be plot_audio) #10).
   • Comparing Signals: cross-correlation / dot-product alignment, Euclidean vs DTW (librosa.sequence.dtw).
   • Frequency Analysis: DFT/FFT scaling, half-spectrum, frequency-bin → Hz mapping, peak picking.
   • Step Tracker: smoothing → find_peaks → min-distance pairing logic.
   • Gesture (Shape/Feature): k-fold construction & leakage, feature definitions (mean/var/dominant freq), StandardScaler→SVM pipeline, confusion-matrix labels.
2. Prose accuracy — every explanatory claim matches the math and the code (no stale or hand-wavy statements; numbers/units in the text agree with what the cell computes).
3. Comment density for students — non-obvious steps carry a clear, correct comment; the why, not just the what. Add where thin; keep crisp (no bloat).

Also re-audit the helper packages (makelab/signal.py, makelab/audio.py, gesturerec/signalproc.py, data.py, experiments.py, vis.py) for the same three dimensions, since the notebooks delegate core math to them.

Checklist

• 1. Intro to Python
• 2. Intro to NumPy
• 3. Intro to Matplotlib
• 4. Quantization & Sampling
• 5. Comparing Signals
• 6. Frequency Analysis
• 7. Step Tracker (Exercises + WithExampleSolution)
• 8. Gesture Recognition: Shape-Based
• 9. Gesture Recognition: Feature-Based
• 10. Feature Selection & Hyperparameter Tuning
• helper packages (makelab, gesturerec)

File any concrete defects found as their own issues (e.g. #10) and check them off here.

Part of v2.0 textbook-integration readiness — see makeabilitylab/physcomp#116.

[jonfroehlich]

Audit pass complete (2026-06-24)

Audited all lessons + helper packages across the three dimensions (algorithmic/math correctness, prose accuracy, student-facing comments). Each claimed defect was independently verified against source (and several by running code) before filing. Concrete defects filed as discrete issues:

Issue	Type	Where
#17	BUG (high)	FeatureBased — train/test leakage in per-user leave-one-out CV (df.drop(test_index) drops by label, not position)
#18	BUG	FeatureBased — plot_feature_3d plots feature 2 on the z-axis; 2nd 3D plot has mismatched axis labels
#19	BUG	FeatureBased + Feature Selection — std feature mislabeled std(mag.max()) (computes std(mag))
#20	BUG	StepTracker (both) — top-2/3 frequencies duplicated; real-time peak slope wraps at buffer start
#21	BUG	gesturerec/data.py — get_gesture_names_filtered self-appends; get_random_gesture_set defined twice
#22	BUG	Feature Selection — manual grid-search uses stale filtered_df for X
#23	PROSE	Gesture ML — SelectKBest k=4 (text) vs k=6 (code); hard-coded 65.5% with unseeded split
#24	PROSE/COMMENT	Frequency Analysis — xcorr amplitude scaling, magnitude_spectrum(*2) comment, bin-spacing vs resolution caveat

(#10, the Quantization plot_signal/plot_audio title bug, was already filed and recurs across the bit-depth cells.)

Clean (verified — no defects)

• NB1 IntroToPython, NB2 IntroToNumPy, NB3 IntroToMatplotlib — algorithmic claims, comments, and prose all check out (intentional raises-exception cells honored).
• NB4 Quantization & Sampling — DSP math correct (only Quantization & Sampling notebook: plot_signal called with quantization_bits in the title slot (should be plot_audio) #10).
• NB5 Comparing Signals — Euclidean / cross-correlation / librosa.sequence.dtw all correct; prose matches.
• NB8 Shape-Based — k-fold construction, fold split, leakage guard correct; DTW prose correctly references librosa.
• Helpers signalproc.py, experiments.py, vis.py, utility.py — math/bookkeeping verified correct (the two data.py items above are the only helper defects).

The DSP signal-processing core is solid; the real correctness risk was concentrated in the gesture feature/ML pipeline (#17 most important — it inflates the published cross-user accuracy numbers) and the two latent StepTracker bugs.