Tutorials¶
These notebooks are rendered with their outputs, so they can be read without running anything.
Start here¶
5. Per-spike diagnostics: the paper's workflow¶
The workflow of Local goodness-of-fit measures for neural decoding, at small scale:
decode position from simulated place cells, compute HPD overlap, the predictive
p-value and KL divergence for every spike, set thresholds from a baseline period, find
when and for which units the model fails, and check whether a revised model fixes it.
Needs only pip install statespacecheck matplotlib.
6. Clusterless per-spike diagnostics¶
The same per-spike diagnostics for spikes described by waveform features rather than
sorted units: build the observation model as a MarkModel, decode a simulated
clusterless recording with a correct and a misspecified mark model, and compute the
diagnostics with clusterless_event_diagnostics. Shows what a consistency diagnostic
can and cannot see, and that sorted units give the same HPD overlap and KL divergence as
event_diagnostics, and p-values within Monte Carlo error. Needs only
pip install statespacecheck matplotlib.
7. A general state space model: a Kalman filter¶
The diagnostics for any state space model, not only neural decoders: run a Kalman
filter that tracks an object from a noisy sensor, put its prediction and each
observation's likelihood on a grid of states, check the grid, and find a biased
sensor and wrong noise settings with HPD overlap, the predictive p-value and KL
divergence. Needs only pip install statespacecheck matplotlib.
Background and extensions¶
These tutorials explain the building blocks and the package's tools beyond the paper. They work with whole time bins rather than individual spikes.
1. Introduction¶
What a state space model's prediction and an observation's likelihood are, and how KL divergence and HPD overlap compare them, on simple Gaussian examples.
2. Highest density regions¶
How highest-density regions are computed, including for multimodal and 2-D distributions, and how coverage affects them.
3. Time-resolved diagnostics¶
Diagnostics over the time bins of a session, with the run-based flagging functions of
statespacecheck.periods (an extension beyond the paper).
4. Predictive checks¶
Monte Carlo predictive checks of whole time bins with log_predictive_density and
predictive_pvalue (an extension beyond the paper, whose p-value is per spike).
Running the tutorials¶
Each tutorial is a pair of files in the repository's
examples/ directory:
a notebook (.ipynb) with its outputs and the same code as a script (.py).
- Tutorial 5 is self-contained: download the notebook and run it anywhere with
statespacecheckandmatplotlibinstalled, for example in Google Colab after!pip install statespacecheck. - Tutorials 1–4 import helpers from
examples/utils.py, so run them from a clone of the repository:
git clone https://github.com/edeno/statespacecheck.git
cd statespacecheck
uv sync --extra docs
uv run --extra docs jupyter nbconvert --to notebook --execute examples/01_introduction.ipynb
or open the notebooks in any Jupyter front end (JupyterLab, VS Code) using that environment.
Found a problem? Please open an issue.