markovflow.emission_model

Module containing emission models for projection.

Module Contents

class EmissionModel(emission_matrix: tf.Tensor)

Takes output from StateSpaceModel methods and linearly projects it into a space of dimension \(m\) (output_dim):

\[\begin{split}&fₖ = Hₖ xₖ\\ &x ∈ ℝ^d\\ &f ∈ ℝ^m\\ &H ∈ ℝ^{m × d}\end{split}\]

This class provides methods for projecting states or covariances, sampling and calculating the marginals.

Parameters

emission_matrix – The emission matrix that projects at each time point from the StateSpaceModel, with shape batch_dim + [num_data, output_dim, state_dim].

property batch_shape → tf.TensorShape

Return the shape of any leading dimension in the emission matrix that comes before the last three.

property num_data → tf.Tensor

Return the number of time points that the emission matrix is applied to.

property output_dim → int

Return the dimension of the output after the emission matrix is applied.

property state_dim → int

Return the state dimension of the StateSpaceModel we emit from.

property emission_matrix → tf.Tensor

Return the emission matrix.

Returns

A tensor for the emission matrix, with shape batch_dim + [num_data, output_dim, state_dim].

project_state_marginals_to_f(means: tf.Tensor, covariances: tf.Tensor, full_output_cov: bool = False) → Tuple[tf.Tensor, tf.Tensor]

Project the marginal mean and covariance of states to get means and (co)variance of \(f\).

Parameters

• means – A tensor of means with shape batch_shape + [num_data, state_dim].

• covariances – A tensor of covariances with shape batch_shape + [num_data, state_dim, state_dim].

• full_output_cov – Full output covariance (True) or marginal variances (False).

Returns

The means and covariances with respective shapes batch_shape + [num_data, output_dim], and either batch_shape + [num_data, output_dim, output_dim] or batch_shape + [num_data, output_dim].

project_state_to_f(state: tf.Tensor) → tf.Tensor

Project a state to \(f\) by multiplying by \(H\).

Parameters

state – A tensor with shape batch_shape + [num_data, state_dim].

Returns

A tensor with shape batch_shape + [num_data, output_dim].

project_state_covariance_to_f(covariance: tf.Tensor, full_output_cov: bool = False) → tf.Tensor

Project a state covariance \(S\) to an \(f\) covariance by calculating \(HSHᵀ\) (or its diagonal).

Parameters

• covariance – A tensor with shape batch_shape + [num_data, state_dim, state_dim].

• full_output_cov – Full output covariance (True) or marginal variances (False).

Returns

A tensor either with shape batch_shape + [num_data, output_dim, output_dim] or batch_shape + [num_data, output_dim].

class ComposedPairEmissionModel(outer_emission_model: EmissionModel, inner_emission_model: EmissionModel)

Bases: EmissionModel

Linear projection for use with kernels that have an intermediate projection. That is, there exists a projection from the state space to an intermediate space, and from that space to the observation space:

\[\begin{split}&fₖ = Hₒₖ gₖ = Hₒₖ Hₗ xₖ = Hₖ xₖ\\ &gₖ = Hₗ xₖ\\ &x ∈ ℝ^d\\ &g ∈ ℝ^l \verb|, the inner space|\\ &f ∈ ℝ^m \verb|, the outer space|\\ &H ∈ ℝ^{m × d}\\ &Hₒ ∈ ℝ^{m × l}\\ &Hₗ ∈ ℝ^{l × d}\end{split}\]

This class provides methods for projecting states or covariances, sampling and calculating the marginals, from state space to both the observation and intermediate space.

Parameters

• outer_emission_model – The emission model for projecting from the intermediate space to the observation space.

• inner_emission_model – The emission model for projecting from state space to the intermediate space.

property state_dim → int

Return the state dimension of the StateSpaceModel we emit from.

property inner_dim → int

Return the output dimension of the inner emission model.

property inner_emission_matrix → tf.Tensor

Return the emission matrix used for projecting from the state space to the intermediate space.

Returns

A tensor for the emission matrix, with shape batch_dim + [num_data, inner_dim, state_dim].

project_state_marginals_to_g(means: tf.Tensor, covariances: tf.Tensor, full_output_cov: bool = True) → Tuple[tf.Tensor, tf.Tensor]

Project the marginal mean and covariance of states to get means for \(g\).

Parameters

• means – A tensor of means with shape batch_shape + [num_data, state_dim].

• covariances – A tensor of covariances with shape batch_shape + [num_data, state_dim, state_dim].

• full_output_cov – Full output covariance (True) or marginal variances (False).

Returns

The means and covariances with respective shapes batch_shape + [num_data, inner_dim], and either batch_shape + [num_data, inner_dim, inner_dim] or batch_shape + [num_data, inner_dim].

project_state_to_g(state: tf.Tensor) → tf.Tensor

Project a state to \(g\) by multiplying by the inner emission matrix.

Parameters

state – A tensor with shape batch_shape + [num_data, state_dim].

Returns

A tensor with shape batch_shape + [num_data, inner_dim].

project_state_covariance_to_g(covariance: tf.Tensor, full_output_cov: bool = True) → tf.Tensor

Project a state covariance \(S\) to a \(g\) covariance by calculating \(HSHᵀ\) with the inner \(H\).

Parameters

• covariance – A tensor with shape batch_shape + [num_data, state_dim, state_dim].

• full_output_cov – Full output covariance (True) or marginal variances (False).

Returns

A tensor either with shape batch_shape + [num_data, inner_dim, inner_dim] or batch_shape + [num_data, inner_dim].

class StackEmissionModel(emission_matrix: tf.Tensor)

Bases: EmissionModel

Linear projection for use with a StackKernel, where we implicitly assume that we have parallel independent SDEs that model each one of the output dimensions.

In such a scenario we assume that the \(m\) (output_dim) independent SDEs can be broadcast together so the output_dim is part of the batch_shape (last dim in the batch_shape).

So the emission matrix that defines the StackEmissionModel has the following shape:

batch_shape + [num_data, 1, state_dim]

…where batch_shape = (..., num_kernels) and num_kernels = output_dim. The singleton pre-last dimension is for the individual output_dim of each kernel. Remember that each kernel explicitly models one of the output dimensions.

We effectively run \(m\) (output_dim) independent SDEs as follows:

\[\begin{split}&fₖ⁽ᵐ⁾ = Hₖ⁽ᵐ⁾ xₖ⁽ᵐ⁾\\ &x⁽ᵐ⁾ ∈ ℝᵈ\\ &f⁽ᵐ⁾∈ ℝ\\ &H⁽ᵐ⁾ ∈ ℝ^{1 × d}\end{split}\]

This class provides methods for projecting states or covariances and calculating the marginals from the state space to the observation space. It is acting as the base EmissionModel class with an extra transposition in the end to make sure that the output_dim gets moved from the batch_shape to the last dim of the projected matrices.

Parameters

emission_matrix – The emission matrix that projects from the StateSpaceModel, with shape batch_shape + [num_data, 1, state_dim] where batch_shape = (..., num_kernels).

property output_dim → int

Return the dimension of the output after the emission matrix is applied.

project_state_to_f(state: tf.Tensor) → tf.Tensor

Project each of the num_kernel states \(s\) to \(f\) by multiplying by the corresponding \(H\).

Parameters

state – A tensor with shape batch_shape + [num_data, state_dim] where batch_shape = (..., num_kernels) and num_kernels = output_dim.

Returns

A tensor with shape batch_shape[:-1] + [num_data, output_dim].

project_state_covariance_to_f(covariance: tf.Tensor, full_output_cov: bool = False) → tf.Tensor

Project a state covariance \(S\) to an \(f\) covariance by calculating \(HSHᵀ\) (or its diagonal). If it is called with full_output_cov=True it will return the same as full_output_cov=False but in a compatible (diagonal) shape.

Parameters

• covariance – A tensor with shape batch_shape + [num_data, state_dim, state_dim] where batch_shape = (..., num_kernels) and num_kernels = output_dim

• full_output_cov – Full output covariance (True) or marginal variances (False).

Returns

A tensor either with shape batch_shape[:-1] + [num_data, output_dim, output_dim] or batch_shape[:-1] + [num_data, output_dim].