Add Python coda detector module (port of MATLAB Coda-detector)

[CivicDash]

Summary

• Adds a wham/detection/ module that ports the MATLAB Coda-detector to pure Python
• Enables end-to-end coda detection from raw audio recordings: raw audio → detected codas
• No new heavy dependencies (uses numpy and scipy, already in setup.py)

What it does

The detector implements the full pipeline from the original MATLAB code:

1. TKEO (Teager-Kaiser Energy Operator) — enhances impulsive transients (whale clicks) while suppressing background noise
2. SNR-based transient selection — filters candidates by signal-to-noise ratio
3. IPI estimation — extracts Inter-Pulse Interval from the multipulse structure of sperm whale clicks (characteristic of individual whales)
4. Waveform cross-correlation — builds a similarity matrix between detected clicks
5. Graph-based clustering — enumerates valid coda candidates satisfying ICI constraints, scores by similarity, greedy selection
6. Deduplication — removes overlapping codas with similar ICI patterns

Usage

from wham.detection import detect_codas, codas_to_dict

codas = detect_codas("recording.wav")
for coda in codas:
    print(f"{coda.n_clicks} clicks, ICIs: {coda.icis}")

# Export to JSON-serializable format
results = codas_to_dict(codas)

Or from the command line:

python -m wham.detection.coda_detector recording.wav

Why this is useful

WhAM currently works with pre-segmented codas from datasets like DSWP. This module closes the gap between raw field recordings and WhAM's embedding/generation pipeline, allowing users to go from raw audio → detected codas → WhAM embeddings in a single Python workflow.

Tests

20 unit tests covering all pipeline stages (TKEO, bandpass filter, resampling, click detection, cross-correlation, clustering, deduplication, end-to-end). All passing.

Related

• Original MATLAB code: https://github.com/Project-CETI/Coda-detector
• Discussion: Open-source interactive explorer built on WhAM: coda identification, vocal activity classification & more #2

Made with Cursor