Tier 2.1 — Clusterless point-process decoding bridge

2026-05-30 · nstat/extras/decoding/clusterless_bridge.py · branch feat/extras-clusterless-decoding

Why

nSTAT's DecodingAlgorithms implements the exact PPAF / PPHF point-process filters for sorted spikes. Two modern capabilities that the MATLAB toolbox doesn't provide:

Clusterless observations — feed each spike's waveform features (its "marks") directly into a marked point-process likelihood, avoiding cluster-quality dependence (Kloosterman 2014; Deng 2015).
Trajectory classification — a discrete latent state (e.g. local, forward replay, reverse replay, fragmented) sits on top of the continuous position decode and identifies what kind of trajectory is being represented at each moment (Denovellis 2021).

What shipped

fit_clusterless_decoder(position, multiunits, *, place_bin_size=2.0, ...) → ClusterlessDecoderResult: thin wrap of ClusterlessDecoder with sensible defaults (single Environment, RandomWalk continuous transition).
fit_clusterless_classifier(position, multiunits, *, state_names=None, discrete_diagonal=0.98, ...) → ClusterlessClassifierResult: 2-state default continuous / fragmented with DiagonalDiscrete(0.98); pass state_names to extend.
Result dataclasses (plain NumPy — no xarray exposed): posterior, MAP position, per-state marginals, position bin centres.
New [clusterless] opt-dep group in pyproject.toml; like [dynamax] it pulls JAX (~200 MB) and is deliberately excluded from [all-extras].
Drift guards extended: HEAVY_OPT_OUT_OF_ALL_EXTRAS += clusterless; EXPECTED_GROUP_FOR_MODULE, EXPECTED_DOC_STEM_FOR_BRIDGE, DOC_TO_EXAMPLE, EXAMPLE_BACKING_PACKAGE all updated.

LICENSE verification

Per the parity/methods_roadmap.md independence rule, the upstream LICENSE was verified before adding the dependency: replay_trajectory_classification is MIT (compatible with our GPL-2.0; permissive deps can ship inside a GPL package). Last release: v1.4.1 (2024-09-06); actively maintained.

Recipe

from nstat.extras.decoding.clusterless_bridge import fit_clusterless_decoder

result = fit_clusterless_decoder(position, multiunits, place_bin_size=5.0)
result.posterior          # (T, *position_bins), each row sums to 1
result.map_position       # (T, n_position_dims), argmax of posterior

Validation

Check	Result
Bridge module imports without the optional dep	PASS (lazy)
Install-hint `ImportError` contract	PASS (raises with `pip install nstat-toolbox[clusterless]`)
Input shape validation runs before the import gate	PASS (better DX without the lib)
`tests/test_pyproject_consistency.py` drift guards	PASS
`tests/test_extras_docs.py` doc/example mapping	PASS
Functional smoke (decoder + classifier on synthetic 1-D data)	gated on `[clusterless]` install (CI extras job to be added separately)

Out of scope

Wrappers for upstream's sorted variants (SortedSpikes{Decoder,Classifier}) — these duplicate nstat.DecodingAlgorithms for sorted spikes; the bridge focuses on the clusterless additions.
Track-linearization helpers / movie utilities — not in scope.
Dedicated extras-clusterless CI job (parallel to extras-dynamax) — left for a follow-up to keep CI runtime bounded; smoke test currently skips when the dep is absent.

Files changed

New: nstat/extras/decoding/__init__.py, nstat/extras/decoding/clusterless_bridge.py
New: tests/extras/test_clusterless_bridge.py (6 tests)
New: docs/extras/decoding_clusterless.md, examples/extras/decoding_clusterless_demo.py
pyproject.toml — new [clusterless] group.
tests/test_pyproject_consistency.py, tests/test_extras_docs.py, tests/test_extras_examples.py — drift-guard updates.
docs/extras.rst — toctree + autosummary additions.
parity/methods_roadmap.md — mark Tier 2.1 SHIPPED.