gluonts.mx.distribution.lds module

class gluonts.mx.distribution.lds.LDS(emission_coeff: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], transition_coeff: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], innovation_coeff: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], noise_std: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], residuals: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], prior_mean: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], prior_cov: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], latent_dim: int, output_dim: int, seq_length: int)[source]

Bases: gluonts.mx.distribution.distribution.Distribution

Implements Linear Dynamical System (LDS) as a distribution.

The LDS is given by

\[\begin{split}z_t = A_t l_{t-1} + b_t + \epsilon_t \\ l_t = C_t l_{t-1} + g_t \nu\end{split}\]

where

\[\begin{split}\epsilon_t = N(0, S_v) \\ \nu = N(0, 1)\end{split}\]

\(A_t\), \(C_t\) and \(g_t\) are the emission, transition and innovation coefficients respectively. The residual terms are denoted by \(b_t\).

The target \(z_t\) can be \(d\)-dimensional in which case

\[A_t \in R^{d \times h}, b_t \in R^{d}, C_t \in R^{h \times h}, g_t \in R^{h}\]

where \(h\) is dimension of the latent state.

Parameters

  • emission_coeff – Tensor of shape (batch_size, seq_length, obs_dim, latent_dim)

  • transition_coeff – Tensor of shape (batch_size, seq_length, latent_dim, latent_dim)

  • innovation_coeff – Tensor of shape (batch_size, seq_length, latent_dim)

  • noise_std – Tensor of shape (batch_size, seq_length, obs_dim)

  • residuals – Tensor of shape (batch_size, seq_length, obs_dim)

  • prior_mean – Tensor of shape (batch_size, latent_dim)

  • prior_cov – Tensor of shape (batch_size, latent_dim, latent_dim)

  • latent_dim – Dimension of the latent state

  • output_dim – Dimension of the output

  • seq_length – Sequence length

  • F –

property F
arg_names = None
property batch_shape

Layout of the set of events contemplated by the distribution.

Invoking sample() from a distribution yields a tensor of shape batch_shape + event_shape, and computing log_prob (or loss more in general) on such sample will yield a tensor of shape batch_shape.

This property is available in general only in mx.ndarray mode, when the shape of the distribution arguments can be accessed.

property event_dim

Number of event dimensions, i.e., length of the event_shape tuple.

This is 0 for distributions over scalars, 1 over vectors, 2 over matrices, and so on.

property event_shape

Shape of each individual event contemplated by the distribution.

For example, distributions over scalars have event_shape = (), over vectors have event_shape = (d, ) where d is the length of the vectors, over matrices have event_shape = (d1, d2), and so on.

Invoking sample() from a distribution yields a tensor of shape batch_shape + event_shape.

This property is available in general only in mx.ndarray mode, when the shape of the distribution arguments can be accessed.

kalman_filter(targets: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], observed: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Tuple[Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], ...][source]

Performs Kalman filtering given observations.

Parameters

  • targets – Observations, shape (batch_size, seq_length, output_dim)

  • observed – Flag tensor indicating which observations are genuine (1.0) and which are missing (0.0)

Returns

  • Tensor – Log probabilities, shape (batch_size, seq_length)

  • Tensor – Mean of p(l_T | l_{T-1}), where T is seq_length, with shape (batch_size, latent_dim)

  • Tensor – Covariance of p(l_T | l_{T-1}), where T is seq_length, with shape (batch_size, latent_dim, latent_dim)

log_prob(x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], scale: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol, None] = None, observed: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol, None] = None)[source]

Compute the log probability of observations.

This method also returns the final state of the system.

Parameters

  • x – Observations, shape (batch_size, seq_length, output_dim)

  • scale – Scale of each sequence in x, shape (batch_size, output_dim)

  • observed – Flag tensor indicating which observations are genuine (1.0) and which are missing (0.0)

Returns

  • Tensor – Log probabilities, shape (batch_size, seq_length)

  • Tensor – Final mean, shape (batch_size, latent_dim)

  • Tensor – Final covariance, shape (batch_size, latent_dim, latent_dim)

sample(num_samples: Optional[int] = None, scale: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol, None] = None) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Generates samples from the LDS: p(z_1, z_2, ldots, z_{seq_length}).

Parameters

  • num_samples – Number of samples to generate

  • scale – Scale of each sequence in x, shape (batch_size, output_dim)

Returns

Samples, shape (num_samples, batch_size, seq_length, output_dim)

Return type

Tensor

sample_marginals(num_samples: Optional[int] = None, scale: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol, None] = None) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Generates samples from the marginals p(z_t), t = 1, ldots, seq_length.

Parameters

  • num_samples – Number of samples to generate

  • scale – Scale of each sequence in x, shape (batch_size, output_dim)

Returns

Samples, shape (num_samples, batch_size, seq_length, output_dim)

Return type

Tensor

class gluonts.mx.distribution.lds.LDSArgsProj(output_dim: int, noise_std_bounds: gluonts.mx.distribution.lds.ParameterBounds, innovation_bounds: gluonts.mx.distribution.lds.ParameterBounds)[source]

Bases: mxnet.gluon.block.HybridBlock

hybrid_forward(F, x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Tuple[Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]][source]

Overrides to construct symbolic graph for this Block.

Parameters

  • x (Symbol or NDArray) – The first input tensor.

  • *args (list of Symbol or list of NDArray) – Additional input tensors.

class gluonts.mx.distribution.lds.ParameterBounds(lower, upper)[source]

Bases: object

gluonts.mx.distribution.lds.kalman_filter_step(F, target: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], prior_mean: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], prior_cov: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], emission_coeff: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], residual: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], noise_std: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], latent_dim: int, output_dim: int)[source]

One step of the Kalman filter.

This function computes the filtered state (mean and covariance) given the linear system coefficients the prior state (mean and variance), as well as observations.

Parameters

  • F –

  • target – Observations of the system output, shape (batch_size, output_dim)

  • prior_mean – Prior mean of the latent state, shape (batch_size, latent_dim)

  • prior_cov – Prior covariance of the latent state, shape (batch_size, latent_dim, latent_dim)

  • emission_coeff – Emission coefficient, shape (batch_size, output_dim, latent_dim)

  • residual – Residual component, shape (batch_size, output_dim)

  • noise_std – Standard deviation of the output noise, shape (batch_size, output_dim)

  • latent_dim – Dimension of the latent state vector

Returns

  • Tensor – Filtered_mean, shape (batch_size, latent_dim)

  • Tensor – Filtered_covariance, shape (batch_size, latent_dim, latent_dim)

  • Tensor – Log probability, shape (batch_size, )