v0.1.0 - spiking auditory encoder and vocal error network

First release of the spiking sparse auditory encoder and vocal error network (VEN) for the zebra finch song system — the spiking counterpart to the rate-based Wilson–Cowan model in pearsonlab/vocal-error-network (Duarte Ortiz et al. 2025, bioRxiv 2025.07.18.665446).

Extracted from the finchsim circuit model so it can be cited and reused on its own. finchsim now consumes it as a dependency.

What it does

Song audio → gammatone cochleagram → sparse-coded spike train → an excitatory/inhibitory network that learns to cancel the predictable auditory response to the bird's own song, leaving an error signal on novel or perturbed sound.

The result, from outputs/encoding_comparison_k4max.pdf: excitatory-population rates of ~7 Hz on the trained song versus ~18, ~21 and ~17 Hz on the time-reversed motif, white noise, and distorted auditory feedback.

Metrics (Mandelblat-Cerf et al. 2014, Fig. 7/8)

Metric	This release	Biological target
encoder forward/reversed correlation	0.0036	near zero
K1 — correct song + HVC	7.78 Hz	mean 7.7 Hz, SD 8.7
K2 — white noise (DAF) + HVC	22.19 Hz	pop. ~16 Hz; responders ~28 Hz
K3 — K2/K1	2.85×	pop. ~2.1×; responders ~3.6×
K4 — reversed / correct	2.13×	> 1×

The model is a responder-only population, so the responder-only targets are the relevant ones. make test-repro asserts all of these against the attached model.

Reproducing

uv sync
make figure   # corpus -> encoder -> network -> figure, ~10 min on CPU
make verify   # check artifacts against MANIFEST.sha256

Fully seeded end to end: re-running reproduces the numbers rather than landing nearby. The encoder's dictionary learning and the network's simulation noise are both driven by explicit generators.

Dependencies

Core install is numpy and scipy only — a fresh uv sync brings in three packages. Brian2, soundfile and matplotlib sit behind the brian2, data and plots extras. import spiking_ven never pulls in Brian2. No PyTorch, numba, seaborn or scikit-learn.

The ERB/gammatone filterbank is vendored (from PyPI Gammatone 1.0.3, BSD-3-Clause, upstream archived 2024) rather than depended on, copied byte-for-byte and verified bit-identical to the released package. See THIRD_PARTY_NOTICES.md.

Attached artifacts

File	What
motifs.npz	38 DTW-aligned R469 motifs @ 16 kHz
of_encoder.npz	trained Olshausen-Field sparse encoder (64 bases)
of_ven_model_k4max.npz	trained vocal error network
encoding_comparison_k4max.pdf	the cancellation figure

The corpus is derived from "Labeled Zebra Finch Songs" (Koch, Therese), DOI 10.18738/T8/SAWMUN, released under CC0 1.0. Please cite it.

Known limitations

• The corpus download fails from datacenter IPs (CloudFront returns 403), so CI runs a synthetic-corpus smoke test instead. Use --skip-download with a hand-placed corpus if you are blocked.
• Checksums in MANIFEST.sha256 record what this build produced; a different platform or BLAS can give different last-bit results and so a different digest without anything being wrong. make test-repro is the authoritative reproduction check.