README.md

---
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}
}
```