Time Series¶
The pyro.contrib.timeseries
module provides a collection of Bayesian time series
models useful for forecasting applications.
See the GP example for example usage.
Abstract Models¶
-
class
TimeSeriesModel
(name='')[source]¶ Bases:
pyro.nn.module.PyroModule
Base class for univariate and multivariate time series models.
-
log_prob
(targets)[source]¶ Log probability function.
Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: A 0-dimensional log probability for the case of properly multivariate time series models in which the output dimensions are correlated; otherwise returns a 1-dimensional tensor of log probabilities for batched univariate time series models.
-
forecast
(targets, dts)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - dts (torch.Tensor) – A 1-dimensional tensor of times to forecast into the future,
with zero corresponding to the time of the final target
targets[-1]
.
Returns torch.distributions.Distribution: Returns a predictive distribution with batch shape
(S,)
and event shape(obs_dim,)
, whereS
is the size ofdts
. That is, the resulting predictive distributions do not encode correlations between distinct times indts
.- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
-
get_dist
()[source]¶ Get a
Distribution
object corresponding to this time series model. Often this is aGaussianHMM
.
-
Gaussian Processes¶
-
class
IndependentMaternGP
(nu=1.5, dt=1.0, obs_dim=1, length_scale_init=None, kernel_scale_init=None, obs_noise_scale_init=None)[source]¶ Bases:
pyro.contrib.timeseries.base.TimeSeriesModel
A time series model in which each output dimension is modeled independently with a univariate Gaussian Process with a Matern kernel. The targets are assumed to be evenly spaced in time. Training and inference are logarithmic in the length of the time series T.
Parameters: - nu (float) – The order of the Matern kernel; one of 0.5, 1.5 or 2.5.
- dt (float) – The time spacing between neighboring observations of the time series.
- obs_dim (int) – The dimension of the targets at each time step.
- length_scale_init (torch.Tensor) – optional initial values for the kernel length scale
given as a
obs_dim
-dimensional tensor - kernel_scale_init (torch.Tensor) – optional initial values for the kernel scale
given as a
obs_dim
-dimensional tensor - obs_noise_scale_init (torch.Tensor) – optional initial values for the observation noise scale
given as a
obs_dim
-dimensional tensor
-
get_dist
(duration=None)[source]¶ Get the
GaussianHMM
distribution that corresponds toobs_dim
-many independent Matern GPs.Parameters: duration (int) – Optional size of the time axis event_shape[0]
. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.
-
log_prob
(targets)[source]¶ Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: A 1-dimensional tensor of log probabilities of shape (obs_dim,)
-
forecast
(targets, dts)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - dts (torch.Tensor) – A 1-dimensional tensor of times to forecast into the future,
with zero corresponding to the time of the final target
targets[-1]
.
Returns torch.distributions.Normal: Returns a predictive Normal distribution with batch shape
(S,)
and event shape(obs_dim,)
, whereS
is the size ofdts
.- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
-
class
LinearlyCoupledMaternGP
(nu=1.5, dt=1.0, obs_dim=2, num_gps=1, length_scale_init=None, kernel_scale_init=None, obs_noise_scale_init=None)[source]¶ Bases:
pyro.contrib.timeseries.base.TimeSeriesModel
A time series model in which each output dimension is modeled as a linear combination of shared univariate Gaussian Processes with Matern kernels.
In more detail, the generative process is:
\(y_i(t) = \sum_j A_{ij} f_j(t) + \epsilon_i(t)\)The targets \(y_i\) are assumed to be evenly spaced in time. Training and inference are logarithmic in the length of the time series T.
Parameters: - nu (float) – The order of the Matern kernel; one of 0.5, 1.5 or 2.5.
- dt (float) – The time spacing between neighboring observations of the time series.
- obs_dim (int) – The dimension of the targets at each time step.
- num_gps (int) – The number of independent GPs that are mixed to model the time series. Typical values might be \(\N_{\rm gp} \in [\D_{\rm obs} / 2, \D_{\rm obs}]\)
- length_scale_init (torch.Tensor) – optional initial values for the kernel length scale
given as a
num_gps
-dimensional tensor - kernel_scale_init (torch.Tensor) – optional initial values for the kernel scale
given as a
num_gps
-dimensional tensor - obs_noise_scale_init (torch.Tensor) – optional initial values for the observation noise scale
given as a
obs_dim
-dimensional tensor
-
get_dist
(duration=None)[source]¶ Get the
GaussianHMM
distribution that corresponds to aLinearlyCoupledMaternGP
.Parameters: duration (int) – Optional size of the time axis event_shape[0]
. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.
-
log_prob
(targets)[source]¶ Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: a (scalar) log probability
-
forecast
(targets, dts)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - dts (torch.Tensor) – A 1-dimensional tensor of times to forecast into the future,
with zero corresponding to the time of the final target
targets[-1]
.
Returns torch.distributions.MultivariateNormal: Returns a predictive MultivariateNormal distribution with batch shape
(S,)
and event shape(obs_dim,)
, whereS
is the size ofdts
.- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
-
class
DependentMaternGP
(nu=1.5, dt=1.0, obs_dim=1, linearly_coupled=False, length_scale_init=None, obs_noise_scale_init=None)[source]¶ Bases:
pyro.contrib.timeseries.base.TimeSeriesModel
A time series model in which each output dimension is modeled as a univariate Gaussian Process with a Matern kernel. The different output dimensions become correlated because the Gaussian Processes are driven by a correlated Wiener process; see reference [1] for details. If, in addition, linearly_coupled is True, additional correlation is achieved through linear mixing as in
LinearlyCoupledMaternGP
. The targets are assumed to be evenly spaced in time. Training and inference are logarithmic in the length of the time series T.Parameters: - nu (float) – The order of the Matern kernel; must be 1.5.
- dt (float) – The time spacing between neighboring observations of the time series.
- obs_dim (int) – The dimension of the targets at each time step.
- linearly_coupled (bool) – Whether to linearly mix the various gaussian processes in the likelihood. Defaults to False.
- length_scale_init (torch.Tensor) – optional initial values for the kernel length scale
given as a
obs_dim
-dimensional tensor - obs_noise_scale_init (torch.Tensor) – optional initial values for the observation noise scale
given as a
obs_dim
-dimensional tensor
References [1] “Dependent Matern Processes for Multivariate Time Series,” Alexander Vandenberg-Rodes, Babak Shahbaba.
-
get_dist
(duration=None)[source]¶ Get the
GaussianHMM
distribution that corresponds to aDependentMaternGP
Parameters: duration (int) – Optional size of the time axis event_shape[0]
. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.
-
log_prob
(targets)[source]¶ Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: A (scalar) log probability
-
forecast
(targets, dts)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - dts (torch.Tensor) – A 1-dimensional tensor of times to forecast into the future,
with zero corresponding to the time of the final target
targets[-1]
.
Returns torch.distributions.MultivariateNormal: Returns a predictive MultivariateNormal distribution with batch shape
(S,)
and event shape(obs_dim,)
, whereS
is the size ofdts
.- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
Linear Gaussian State Space Models¶
-
class
GenericLGSSM
(obs_dim=1, state_dim=2, obs_noise_scale_init=None, learnable_observation_loc=False)[source]¶ Bases:
pyro.contrib.timeseries.base.TimeSeriesModel
A generic Linear Gaussian State Space Model parameterized with arbitrary time invariant transition and observation dynamics. The targets are (implicitly) assumed to be evenly spaced in time. Training and inference are logarithmic in the length of the time series T.
Parameters: -
get_dist
(duration=None)[source]¶ Get the
GaussianHMM
distribution that corresponds toGenericLGSSM
.Parameters: duration (int) – Optional size of the time axis event_shape[0]
. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.
-
log_prob
(targets)[source]¶ Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: A (scalar) log probability.
-
forecast
(targets, N_timesteps)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - N_timesteps (int) – The number of timesteps to forecast into the future from
the final target
targets[-1]
.
Returns torch.distributions.MultivariateNormal: Returns a predictive MultivariateNormal distribution with batch shape
(N_timesteps,)
and event shape(obs_dim,)
- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
-
-
class
GenericLGSSMWithGPNoiseModel
(obs_dim=1, state_dim=2, nu=1.5, obs_noise_scale_init=None, length_scale_init=None, kernel_scale_init=None, learnable_observation_loc=False)[source]¶ Bases:
pyro.contrib.timeseries.base.TimeSeriesModel
A generic Linear Gaussian State Space Model parameterized with arbitrary time invariant transition and observation dynamics together with separate Gaussian Process noise models for each output dimension. In more detail, the generative process is:
\(y_i(t) = \sum_j A_{ij} z_j(t) + f_i(t) + \epsilon_i(t)\)where the latent variables \({\bf z}(t)\) follow generic time invariant Linear Gaussian dynamics and the \(f_i(t)\) are Gaussian Processes with Matern kernels.
The targets are (implicitly) assumed to be evenly spaced in time. In particular a timestep of \(dt=1.0\) for the continuous-time GP dynamics corresponds to a single discrete step of the \({\bf z}\)-space dynamics. Training and inference are logarithmic in the length of the time series T.
Parameters: - obs_dim (int) – The dimension of the targets at each time step.
- state_dim (int) – The dimension of the \({\bf z}\) latent state at each time step.
- nu (float) – The order of the Matern kernel; one of 0.5, 1.5 or 2.5.
- length_scale_init (torch.Tensor) – optional initial values for the kernel length scale
given as a
obs_dim
-dimensional tensor - kernel_scale_init (torch.Tensor) – optional initial values for the kernel scale
given as a
obs_dim
-dimensional tensor - obs_noise_scale_init (torch.Tensor) – optional initial values for the observation noise scale
given as a
obs_dim
-dimensional tensor - learnable_observation_loc (bool) – whether the mean of the observation model should be learned or not; defaults to False.
-
get_dist
(duration=None)[source]¶ Get the
GaussianHMM
distribution that corresponds toGenericLGSSMWithGPNoiseModel
.Parameters: duration (int) – Optional size of the time axis event_shape[0]
. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.
-
log_prob
(targets)[source]¶ Parameters: targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets of shape (T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valuedtargets
at each time stepReturns torch.Tensor: A (scalar) log probability.
-
forecast
(targets, N_timesteps)[source]¶ Parameters: - targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape
(T, obs_dim)
, whereT
is the length of the time series andobs_dim
is the dimension of the real-valued targets at each time step. These represent the training data that are conditioned on for the purpose of making forecasts. - N_timesteps (int) – The number of timesteps to forecast into the future from
the final target
targets[-1]
.
Returns torch.distributions.MultivariateNormal: Returns a predictive MultivariateNormal distribution with batch shape
(N_timesteps,)
and event shape(obs_dim,)
- targets (torch.Tensor) – A 2-dimensional tensor of real-valued targets
of shape