Putting Dynamics First: State-Space Modelling for Human Neuroscience

Materials for the CCN2026 Tutorial (New York) Kimmel Center, Grand Hall @ 4:30pm

Harrison Ritz & Luiz Pessoa

State-space models (SSMs) treat a recording as a latent trajectory evolving in time rather than as a bag of trials or a static connectivity matrix. This tutorial builds that view from the ground up: exact inference in linear-Gaussian SSMs (the Kalman filter), learning parameters by EM and the identifiability traps that come with it, and finally switching models that segment task fMRI into discrete dynamical regimes without ever seeing the task.

Prerequisites: linear algebra (eigenvalues, matrix factorizations) and basic probability (Gaussians, conditioning). Some familiarity with Python is enough to follow all three notebooks — no prior experience with R, Julia, or state-space modelling is assumed.

Slides

Notebooks

Three core notebooks, each runnable on Google Colab (with a Google account) or locally. On Colab, set the runtime language first — Runtime → Change runtime type — as noted per notebook below; the badge always opens a Python runtime by default.

1. 01 — introduction to Kalman filtering (Python / dynamax); Colab runtime: Python

2. 02 — fitting LDS models to synthetic data, and what "recovery" does and doesn't mean. Two equivalent versions:

   • Python / dynamax; Colab runtime: Python
   • R / MARSS; Colab runtime: R

3. 03 — fitting SLDS models to HCP task fMRI (Julia / StateSpaceDynamics.jl); Colab runtime: Julia

   Run the setup cells early. Notebook 3 precompiles a sizeable Julia environment (several minutes on a fresh Colab runtime) and downloads ~13 MB of assets — the parcellated HCP tensors, the Schaefer-100/17 atlas, and the fsLR-32k surfaces — into derivatives/.

Running locally

Clone the repo:

git clone https://github.com/harrisonritz/DynamicsTutorial_CCN2026.git
cd DynamicsTutorial_CCN2026

Then set up whichever language(s) you need — the three notebooks are independent.

Python (notebooks 01, 02)

Managed with uv, which installs the right Python version for you (the project needs ≥ 3.14):

uv sync                 # create the environment
uv run jupyter lab      # launch, then select this environment's Python 3 kernel

R (notebook 02_R)

Install R, then from an R session:

install.packages(c("MARSS", "MASS", "IRkernel"))
IRkernel::installspec()   # registers the R kernel with Jupyter

The notebook also installs MARSS/MASS itself if they are missing, so on Colab you only need to switch the runtime to R.

Julia (notebook 03)

Install Julia (the checked-in Manifest.toml was resolved on 1.13). From a terminal at the repo folder:

julia --project=.   # start Julia *in this project's environment*

Install the dependencies (takes a few minutes):

using Pkg
Pkg.instantiate()   # install dependencies from Manifest.toml

Then register the Jupyter kernel and open the notebook (IJulia is already a dependency):

using IJulia
notebook(dir = ".")

Data

The HCP tensors used in notebook 3 are not stored in this repo — the notebook downloads them, along with the atlas and surface files, into derivatives/ (gitignored). They are Schaefer-100 / Yeo-17 parcellated timeseries from the HCP LANGUAGE task: 43 subjects × 2 runs, T = 316 TRs at TR = 0.72 s.

Data were provided by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657), funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research, and by the McDonnell Center for Systems Neuroscience at Washington University. Use of these derivatives is subject to the HCP Open Access Data Use Terms.

Further reading

First Steps

Start with Murphy (2023) ProbML2, Ch. 29, 8. An open-source PDF is available on his website.

Packages

• dynamax — JAX state-space models (notebooks 01–02)
• MARSS — multivariate autoregressive state-space models in R (notebook 01_*R)
• StateSpaceDynamics.jl — SSMs in Julia (notebook 03)

Papers

• Roweis, S., & Ghahramani, Z. (1999). A unifying review of linear gaussian models. Neural Computation, 11(2), 305–345.
• Ghahramani, Z., Rey, G., & Hinton, E. (1996). Parameter Estimation for Linear Dynamical Systems.
• Zoltowski, D., Pillow, J., & Linderman, S. (2020). A general recurrent state space framework for modeling neural dynamics during decision-making. International Conference on Machine Learning, 11680–11691.
• Valente, A., Ostojic, S., & Pillow, J. (2021). Probing the relationship between linear dynamical systems and low-rank recurrent neural network models. In arXiv [q-bio.NC]. arXiv.
• Holmes, E. E. (2013). Derivation of an EM algorithm for constrained and unconstrained multivariate autoregressive state-space (MARSS) models. In arXiv [stat.ME]. arXiv.

Books

• Murphy (2023), Probabilistic Machine Learning: Advanced Topics. MIT Press., Ch. 8, 29
• Simo Sarkka (2013). Bayesian Filtering and Smoothing. Cambridge University Press.

License, citation, and contact

Code and materials are released under GPL-3.0. If you use these materials, please cite the tutorial: Ritz, H. & Pessoa, L. (2026). Putting Dynamics First: State-Space Modelling for Human Neuroscience. Tutorial at the Conference on Cognitive Computational Neuroscience (CCN), New York.

Questions, or something not running? Please open an issue.