GitHub

Getting Started

StateSpaceDynamics.jl is a comprehensive Julia package for state space modeling, designed specifically with neuroscientific applications in mind. The package provides efficient implementations of various state space models along with tools for parameter estimation, state inference, and model selection.

Installation

To install StateSpaceDynamics.jl, start up Julia and type the following code snippet into the REPL.

using Pkg
Pkg.add("StateSpaceDynamics")

or alternatively, you can enter the package manager by typing ] and then run:

add StateSpaceDynamics

What are State Space Models?

State space models are a class of probabilistic models that describe the evolution of a system through two main components - a latent and observation process. The latent process is a stochastic process that is not directly observed, but is used to generate the observed data. The observation process is a conditional distribution that describes how the observed data is generated from the latent process.

In their most general form, state space models can be written as:

\[\begin{align*} x_{t+1} &\sim p(x_{t+1} | x_t) \\ y_t &\sim p(y_t | x_t) \end{align*}\]

where $x_t$ is the latent state at time $t$ and $y_t$ is the observed data at time $t$.

Example: Linear Dynamical Systems

A fundamental example is the Linear Dynamical System (LDS), which combines linear dynamics with Gaussian noise. The LDS can be expressed in two equivalent forms:

  1. Equation form:

\[\begin{align*} x_{t+1} &= A x_t + B u_t + b + \epsilon_t \\ y_t &= C x_t + D v_t + d + \delta_t \end{align*}\]

where:

  • $A$ is the state transition matrix
  • $C$ is the observation matrix
  • $b$ and $d$ are bias terms
  • $B$ and $D$ are input matrices that scale their respective inputs $u_t$ and $v_t$
  • $\epsilon_t$ and $\delta_t$ are Gaussian noise terms with covariances $Q$ and $R$ respectively
  1. Distributional form:

\[\begin{align*} x_{t+1} &\sim \mathcal{N}(A x_t + B u_t + b, Q) \\ y_t &\sim \mathcal{N}(C x_t + D v_t + d, R) \end{align*}\]

where $Q$ and $R$ are the state and observation noise covariance matrices, respectively.

Models Implemented

StateSpaceDynamics.jl implements several types of state space models:

  1. Linear Dynamical Systems (LDS)

    • Gaussian LDS
    • Poisson LDS

  2. Switching Linear Dynamical Systems (SLDS)

    • Gaussian and Poisson emissions

  3. Probabilistic PCA (PPCA)

Quick Start

Here's a simple example on how to create a Gaussian SSM.

using StateSpaceDynamics
using LinearAlgebra

# Define model dimensions
latent_dim = 3
obs_dim = 10

# Define state model parameters (b = dynamics bias, x0 / P0 = initial mean / cov)
A = Matrix(0.95 * I(latent_dim))
Q = Matrix(0.01 * I(latent_dim))
b = zeros(latent_dim)
x0 = zeros(latent_dim)
P0 = Matrix(0.1 * I(latent_dim))
state_model = GaussianStateModel(; A=A, Q=Q, b=b, x0=x0, P0=P0)

# Define observation model parameters (d = emission bias)
C = ones(obs_dim, latent_dim)
R = Matrix(0.5 * I(obs_dim))
d = zeros(obs_dim)
obs_model = GaussianObservationModel(; C=C, R=R, d=d)

# Construct the LDS. Fitting uses the block-tridiagonal (Newton) smoother.
lds = LinearDynamicalSystem(state_model, obs_model)

Contributing

If you encounter a bug or would like to contribute to the package, please open an issue on our GitHub repository. Once the suggested change has received positive feedback, feel free to submit a PR adhering to the BlueStyle guide.

Please include or update tests for any user-facing change. Tests live in the test/ folder and are run with:

julia --project -e 'using Pkg; Pkg.test()'
# or from the Pkg REPL by typing "]":
test StateSpaceDynamics

Citing StateSpaceDynamics.jl

If you use this software in your research, please cite our publication in the Journal of Open Source Software:

@article{Senne_StateSpaceDynamics_jl_A_Julia_2025,
  author = {Senne, Ryan and Loschinskey, Zachary and Fourie, James and Loughridge, Carson and DePasquale, Brian D.},
  doi = {10.21105/joss.08077},
  journal = {Journal of Open Source Software},
  month = nov,
  number = {115},
  pages = {8077},
  title = {{StateSpaceDynamics.jl: A Julia package for probabilistic state space models (SSMs)}},
  url = {https://joss.theoj.org/papers/10.21105/joss.08077},
  volume = {10},
  year = {2025}
  }