nstat.extras.decoding.clusterless_bridge

Clusterless / trajectory-classification decoding via replay_trajectory_classification.

This bridge connects nSTAT’s point-process decoding lineage (PPAF / PPHF in nstat.DecodingAlgorithms) with the modern marked point-process state-space decoders of Denovellis et al. 2021, eLife — implemented in replay_trajectory_classification (MIT). Two capabilities that the MATLAB nSTAT toolbox does not provide:

Clusterless decoding — the observation model is a marked point process where each spike carries the multi-dim waveform features that would have been used for spike sorting; this avoids the cluster-quality dependence of sorted decoders. See the seminal Kloosterman et al. (2014) / Deng et al. (2015) clusterless framework and Denovellis 2021 for the state-space integration.
Trajectory classification — a discrete latent state (e.g. local, forward replay, reverse replay, fragmented) sits on top of the continuous position decode, letting the model identify what kind of trajectory is being represented at each moment.

Scope of this bridge

fit_clusterless_decoder() — wraps ClusterlessDecoder (single continuous state, one movement model).
fit_clusterless_classifier() — wraps ClusterlessClassifier (multiple discrete states / movement-model mixtures).

Both accept plain NumPy inputs (the position trajectory and the multiunit-mark cube) and return ClusterlessDecoderResult / ClusterlessClassifierResult — frozen dataclasses with plain NumPy fields, so downstream code never sees xarray. The actual state-space inference, parameter fitting, and likelihood machinery is all delegated to the upstream library; this bridge is intentionally thin (data conversion, sensible defaults, plain-NumPy outputs).

Install

pip install nstat-toolbox[clusterless]

Pulls replay_trajectory_classification and its JAX-based numerical stack (~200 MB). Like [dynamax], this group is not rolled into [all-extras]; install it explicitly when you need clusterless decoding.

Functions

`fit_clusterless_classifier`(position, ...[, ...])	Fit + classify with the clusterless trajectory-classification model.
`fit_clusterless_decoder`(position, multiunits, *)	Fit + decode a single-state clusterless point-process state-space decoder.

Classes

`ClusterlessClassifierResult`(posterior, ...)	Output of `fit_clusterless_classifier()`.
`ClusterlessDecoderResult`(posterior, ...)	Output of `fit_clusterless_decoder()`.

class nstat.extras.decoding.clusterless_bridge.ClusterlessDecoderResult(posterior, map_position, position_bin_centers, causal_posterior)[source]

Bases: object

Output of fit_clusterless_decoder().

Plain-NumPy view of the upstream xarray.Dataset returned by predict().

Variables:

posterior (numpy.ndarray) – Smoothed (acausal) posterior over the decoded variable, shape (n_time, n_position_bins[0], ...) — the leading dim is time, the trailing dims are the position-bin grid for each spatial dimension. Sums to 1 along the position axes at each time.
map_position (numpy.ndarray) – Posterior-mode (MAP) position bin index at each time, shape (n_time, n_position_dims). Use position_bin_centers to convert to physical units.
position_bin_centers (tuple[numpy.ndarray, ...]) – Bin centres along each position dimension; tuple of 1-D arrays.
causal_posterior (numpy.ndarray) – Filter (causal) posterior — same shape as posterior but conditioning only on the past at each time.

Parameters:

posterior (ndarray)
map_position (ndarray)
position_bin_centers (tuple[ndarray, ...])
causal_posterior (ndarray)

posterior: ndarray

map_position: ndarray

position_bin_centers: tuple[ndarray, ...]

causal_posterior: ndarray

class nstat.extras.decoding.clusterless_bridge.ClusterlessClassifierResult(posterior, state_probabilities, state_names, position_bin_centers)[source]

Bases: object

Output of fit_clusterless_classifier().

Plain-NumPy view of the upstream xarray.Dataset returned by predict().

Variables:

posterior (numpy.ndarray) – Smoothed joint posterior over (state, position), shape (n_time, n_states, n_position_bins[0], ...).
state_probabilities (numpy.ndarray) – Marginal smoothed posterior over the discrete state, shape (n_time, n_states). Sums to 1 along the state axis.
state_names (list[str]) – Human-readable name for each discrete state, length n_states.
position_bin_centers (tuple[numpy.ndarray, ...]) – Bin centres along each position dimension; tuple of 1-D arrays.

Parameters:

posterior (ndarray)
state_probabilities (ndarray)
state_names (list[str])
position_bin_centers (tuple[ndarray, ...])

posterior: ndarray

state_probabilities: ndarray

state_names: list[str]

position_bin_centers: tuple[ndarray, ...]

nstat.extras.decoding.clusterless_bridge.fit_clusterless_decoder(position, multiunits, *, place_bin_size=2.0, movement_var=None, is_training=None, is_compute_acausal=True)[source]

Fit + decode a single-state clusterless point-process state-space decoder.

Wraps replay_trajectory_classification.ClusterlessDecoder with sensible defaults: a single Environment with the given place_bin_size and a single RandomWalk continuous-state transition. For multi-state (e.g. replay) classification, use fit_clusterless_classifier() instead.

Parameters:

position (ndarray) – Animal position on the training trajectory, shape (n_time, n_position_dims) (1-D arrays are reshaped).
multiunits (ndarray) – Multiunit mark cube, shape (n_time, n_marks, n_electrodes). NaN entries denote “no spike on this electrode at this time” — the upstream convention.
place_bin_size (float) – Spatial discretization in the same units as position.
movement_var (float | None) – Variance of the random-walk transition between consecutive position bins. None (default) lets the library use its own data-driven estimate via estimate_movement_var.
is_training (ndarray | None) – Boolean mask of which time bins to use for encoding (model fitting); decoding is then run over all time bins. If None, every time bin is used for both.
is_compute_acausal (bool) – If True (default), also run the backward smoother and use its (acausal) posterior as the primary output.

Return type:

ClusterlessDecoderResult

References

Denovellis EL, Frank LM, Eden UT (2021), eLife. Kloosterman F et al. (2014), J Neural Eng (clusterless framework).

nstat.extras.decoding.clusterless_bridge.fit_clusterless_classifier(position, multiunits, *, place_bin_size=2.0, state_names=None, discrete_diagonal=0.98, is_training=None, is_compute_acausal=True)[source]

Fit + classify with the clusterless trajectory-classification model.

Wraps replay_trajectory_classification.ClusterlessClassifier with a default 2-state setup ("continuous" = local random walk, "fragmented" = uniform) controlled by a diagonal discrete-state transition (high self-persistence). Override state_names to fit a custom number of discrete states; the matching continuous_transition_types is built proportionally.

Parameters:

position (ndarray) – See fit_clusterless_decoder().
multiunits (ndarray) – See fit_clusterless_decoder().
is_training (ndarray | None) – See fit_clusterless_decoder().
place_bin_size (float) – Spatial discretization in the same units as position.
state_names (list[str] | None) – Names of the discrete states. None (default) gives ["continuous", "fragmented"]. Pass at least one name; the continuous-transition cell defaults to RandomWalk per state, and the discrete transition is a diagonal matrix with self-persistence discrete_diagonal.
discrete_diagonal (float) – Self-persistence probability on the discrete-state transition matrix (off-diagonals split the remainder).
is_compute_acausal (bool) – Compute the backward smoother as well as the forward filter.

Return type:

ClusterlessClassifierResult

References

Denovellis EL, Frank LM, Eden UT (2021), eLife — for the classification framework integrated with clusterless decoding.