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.

source

SSMProblems.LatentDynamics — Type

Latent dynamics of a state space model.

Any concrete subtype of LatentDynamics should implement the functions logdensity and simulate for transition dynamics. Whether each of these functions need to be implemented depends on the exact inference algorithm that is intended to be used.

Alternatively, you may specify a method for the function distribution which will be used to define the above methods.

All of these methods should accept keyword arguments through kwargs... to facilitate inference-time dependencies of the dynamics as explained in Control Variables and Keyword Arguments.

source

SSMProblems.ObservationProcess — Type

Observation process of a state space model.

Any concrete subtype of ObservationProcess must implement the logdensity method, as defined below. Optionally, it may also implement simulate for use in forward simulation of the state space model.

Alternatively, you may specify a method for distribution, which will be used to define both of the above methods.

All of these methods should accept keyword arguments through kwargs... to facilitate inference-time dependencies of the observations as explained in Control Variables and Keyword Arguments.

source

SSMProblems.StatePrior — Type

Initial state prior of a state space model.

Any concrete subtype of StatePrior should implement the functions logdensity and simulate as defined below.

Alternatively, you may specify a method for the function distribution which will be used to define the above methods.

source

SSMProblems.StateSpaceModel — Type

A state space model.

A vanilla implementation of a state space model, composed of an initail state prior, latent dynamics and an observation process.

Fields

prior::PT: The initial state prior fo the state space model.
dyn::LD: The latent dynamics of the state space model.
obs::OP: The observation process of the state space model.

Parameters

PT: The type of the initial state prior.
LD: The type of the latent dynamics.
OP: The type of the observation process.

source

SSMProblems.distribution — Method

distribution(dyn::LatentDynamics, step::Integer, prev_state; kwargs...)

Return the transition distribution for the latent dynamics.

The method should return the distribution of the current state (at time step step) given the previous state prev_state. The returned value should be a Distributions.Distribution object that implements sampling and log-density calculations.