Update README.md

1c0938e verified about 13 hours ago

4.46 kB

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

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:

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