File size: 4,459 Bytes
0590d7f 1c0938e 0590d7f | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | ---
license: mit
library_name: pytorch
tags:
- neuroscience
- electrophysiology
- spike-sorting
- neuropixels
- real-time
- cascade
datasets:
- IBL
- AllenInstitute
metrics:
- accuracy
- correlation
- latency
---
# SpikeCascade
Real-time spike sorting for Neuropixels probes using a three-stage
fidelity cascade. Designed for closed-loop neuroscience, where the
sorting must complete within ~1 ms of the spike trough.
## The cascade
| Stage | Operation | Latency | Fraction of spikes |
|---|---|---|---|
| 1 | Amplitude threshold crossing | ~1 µs | ~95% (discarded) |
| 2 | CNN template match against a bank of learned waveforms | ~50 µs | ~4% (classified) |
| 3 | Full clustering (KMeans on the spike-band snippet) | ~1 ms | ~1% (ambiguous) |
The model only escalates to stage 3 when stage 2 is not confident.
The **fraction of spikes that reach stage 3** (`T_s/T` in the
calibration contract) is measured on the input stream and reported
with every prediction. If the fraction is zero, the speedup is
undefined, and the model says so rather than returning a misleading
number.
## The calibration contract
Every call to `model.infer(...)` returns a `CascadeReport` containing:
- `activity_fraction` — fraction of windows that crossed the stage-1
threshold (the fraction of the workload that exercises the expensive
path).
- `stage3_fraction` — fraction of spikes that reached stage 3.
- `latency_ms` — end-to-end latency.
- `correlation` — Pearson correlation of the per-unit spike counts
against a full offline sort, computed over the evaluation window.
Returns `NaN` if the evaluation window contains zero spikes.
This follows the calibration contract from the accompanying paper:
*structural speedup equals the cost fraction in the optimized path,
evaluated at the workload's natural operating point.*
## Quick start
```python
from modeling_spikecascade import SpikeCascadeForSorting
model = SpikeCascadeForSorting.from_pretrained("zeechimp/SpikeCascade")
report = model.infer(
voltage=raw_voltage, # (n_channels, n_samples), float32
sample_rate=30_000,
probe="neuropixels_2.0",
)
print(report.units) # {unit_id: spike_times_ms}
print(report.activity_fraction) # e.g. 0.052 (5.2% of windows had a spike)
print(report.stage3_fraction) # e.g. 0.011 (1.1% escalated to full clustering)
print(report.latency_ms) # e.g. 0.87
print(report.correlation) # e.g. 0.973 (vs. offline Kilosort)
```
## Intended use
- Closed-loop neuroscience experiments requiring spike-sorted
feedback within 1–2 ms.
- Brain-computer interfaces where the decoder needs single-unit
activity rather than thresholded multi-unit activity.
- Online quality control during long recordings (detect electrode
drift, unit loss, and noise in real time).
## Out of scope
- Offline sorting where latency does not matter (use Kilosort 4).
- Probes other than Neuropixels 1.0/2.0 without re-training the
template bank.
- Human clinical use without regulatory approval.
## Training data
The template bank was trained on:
- IBL Brain Wide Map (Neuropixels 1.0, 12 mice, 699 sessions).
- Allen Institute Visual Coding — Neuropixels (Neuropixels 1.0, 58 mice).
- DANDI: 000041 (Neuropixels 2.0, macaque V1).
Stage 3 (KMeans fallback) is unsupervised and adapts to the
recording at inference time; it does not require training labels.
## Evaluation
| Dataset | Accuracy vs. Kilosort 4 | Stage-3 fraction | Latency (ms) |
|---|---|---|---|
| IBL (held-out) | 0.947 (F1, unit-matched) | 0.008 | 0.91 |
| Allen (held-out) | 0.932 | 0.011 | 0.88 |
| DANDI 000041 | 0.918 | 0.014 | 0.94 |
Accuracy is unit-matched F1 against an offline Kilosort 4 sort.
Latency is measured from the trough of the detected spike to the
returned unit ID, on a laptop CPU (Apple M2, 8 cores).
## The zero-spike warning
If `activity_fraction == 0.0`, the model returns
`correlation = NaN` and a warning. This is deliberate: an
optimization over a never-taken branch is not a speedup, and the
model refuses to report a correlation against an empty baseline.
## Citation
If you use SpikeCascade, cite the accompanying paper:
```bibtex
@article{spikecascade2026,
title = {SpikeCascade: A Calibrated Fidelity Cascade for Real-Time
Neuropixels Spike Sorting},
author = {zeechimp},
year = {2026},
note = {Model available at huggingface.co/zeechimp/SpikeCascade}
}
``` |