Create README.md

README.md

@@ -0,0 +1,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("your-org/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}
+}
+```