SSMProblems

Installation

In the julia REPL:

] add SSMProblems

Documentation

SSMProblems defines a generic interface for state space models (SSMs). Its main objective is to provide a consistent interface for filtering and smoothing algorithms to interact with.

Consider a standard (Markovian) state-space model from^[Murray]: state space model

The following three distributions fully specify the model:

The initialisation distribution, $f_0$, for the initial latent state $X_0$
The transition distribution, $f$, for the latent state $X_t$ given the previous $X_{t-1}$
The observation distribution, $g$, for an observation $Y_t$ given the state $X_t$

The dynamics of the model are given by,

\[\begin{aligned} x_0 &\sim f_0(x_0) \\ x_t | x_{t-1} &\sim f(x_t | x_{t-1}) \\ y_t | x_t &\sim g(y_t | x_{t}) \end{aligned}\]

and the joint law is,

\[p(x_{0:T}, y_{0:T}) = f_0(x_0) \prod_t g(y_t | x_t) f(x_t | x_{t-1}).\]

We can consider a state space model as being made up of two components:

A latent Markov chain describing the evolution of the latent state
An observation process describing the relationship between the latent states and the observations

Through this lens, we see that the distributions $f_0$, $f$ fully describe the latent Markov chain, whereas $g$ describes the observation process.

A user of SSMProblems may define these three distributions directly. Alternatively, they can define a subset of methods for sampling and evaluating log-densities of the distributions, depending on the requirements of the filtering/smoothing algorithms they intend to use.

Using the first approach, we can define a simple linear state space model as follows:

using Distributions
using SSMProblems

struct SimpleLatentDynamics <: LatentDynamics end

function distribution(rng::AbstractRNG, dyn::SimpleLatentDynamics; kwargs...)
    return Normal(0.0, 1.0)
end

function distribution(rng::AbstractRNG, dyn::SimpleLatentDynamics, step::Int, state::Float64; kwargs...)
    return Normal(state, 0.1)
end

struct SimpleObservationProcess <: ObservationProcess end

function distribution(
    obs::SimpleObservationPRocess, step::Int, state::Float64, observation::Float64; kwargs...
)
    return Normal(state, 0.5)
end

# Construct an SSM from the components
dyn = SimpleLatentDynamics()
obs = SimpleObservationProcess()
model = StateSpaceModel(dyn, obs)

There are a few things to note here:

Two methods must be defined for the LatentDynamics, one containing step/state arguments and used for transitioning, and one without these, used for initialisation.
Every function should accept keyword arguments. This is key feature of SSMProblems that allows it to flexibly represent more exotic models without any performance penalty. You can read more about it here.
If your latent dynamics and observation process cannot be represented as a Distribution object, you may implement specific methods for sampling and log-density evaluation as documented below.

These distribution definitions are used to define simulate and logdensity methods for the latent dynamics and observation process. Package users can then interact with the state space model through these functions.

For example, a bootstrap filter targeting the filtering distribution $p(x_t | y_{0:t})$ using N particles would roughly follow:

dyn, obs = model.dyn, model.obs

for (i, observation) in enumerate(observations)
    idx = resample(rng, log_weights)
    particles = particles[idx]
    for i in 1:N
        particles[i] = simulate(rng, dyn, i, particles[i])
        log_weights[i] += logdensity(obs, i, particles[i], observation)
    end
end

For more thorough examples, see the provided example scripts.

Interface

SSMProblems.AbstractStateSpaceModel — Type

An abstract type for state space models.

Any concrete subtype of AbstractStateSpaceModel should implement a method for AbstractMCMC.sample which performs forward simulation. For an example implementation, see AbstractMCMC.sample(::StateSpaceModel).

For most regular use-cases, the predefined StateSpaceModel type, documented below, should be sufficient.