tfp.substrates.numpy.sts.DynamicLinearRegression

Formal representation of a dynamic linear regresson model.

Inherits From: StructuralTimeSeries

tfp.substrates.numpy.sts.DynamicLinearRegression(
    design_matrix,
    drift_scale_prior=None,
    initial_weights_prior=None,
    observed_time_series=None,
    name=None
)

The dynamic linear regression model is a special case of a linear Gaussian SSM and a generalization of typical (static) linear regression. The model represents regression weights with a latent state which evolves via a Gaussian random walk:

weights[t] ~ Normal(weights[t-1], drift_scale)

The latent state has dimension num_features, while the parameters drift_scale and observation_noise_scale are each (a batch of) scalars. The batch shape of this Distribution is the broadcast batch shape of these parameters, the initial_state_prior, and the design_matrix. num_features is determined from the last dimension of design_matrix (equivalent to the number of columns in the design matrix in linear regression).

design_matrix float Tensor of shape concat([batch_shape, [num_timesteps, num_features]]).
drift_scale_prior instance of tfd.Distribution specifying a prior on the drift_scale parameter. If None, a heuristic default prior is constructed based on the provided observed_time_series. Default value: None.
initial_weights_prior instance of tfd.MultivariateNormal representing the prior distribution on the latent states (the regression weights). Must have event shape [num_features]. If None, a weakly-informative Normal(0., 10.) prior is used. Default value: None.
observed_time_series optional float Tensor of shape batch_shape + [T, 1] (omitting the trailing unit dimension is also supported when T > 1), specifying an observed time series. Any NaNs are interpreted as missing observations; missingness may be also be explicitly specified by passing a tfp.sts.MaskedTimeSeries instance. Any priors not explicitly set will be given default values according to the scale of the observed time series (or batch of time series). Default value: None.
name Python str for the name of this component. Default value: 'DynamicLinearRegression'.

batch_shape Static batch shape of models represented by this component.
design_matrix Tensor representing the design matrix.
init_parameters Parameters used to instantiate this StructuralTimeSeries.
initial_state_prior Prior distribution on the initial latent state (level and scale).
latent_size Python int dimensionality of the latent space in this model.
name Name of this model component.
parameters List of Parameter(name, prior, bijector) namedtuples for this model.

Methods

batch_shape_tensor

View source

batch_shape_tensor()

Runtime batch shape of models represented by this component.

Returns
batch_shape int Tensor giving the broadcast batch shape of all model parameters. This should match the batch shape of derived state space models, i.e., self.make_state_space_model(...).batch_shape_tensor().

copy

View source

copy(
    **override_parameters_kwargs
)

Creates a deep copy.

Args
**override_parameters_kwargs String/value dictionary of initialization arguments to override with new values.

Returns
copy A new instance of type(self) initialized from the union of self.init_parameters and override_parameters_kwargs, i.e., dict(self.init_parameters, **override_parameters_kwargs).

get_parameter

View source

get_parameter(
    parameter_name
)

Returns the parameter with the given name, or a KeyError.

joint_distribution

View source

joint_distribution(
    observed_time_series=None,
    num_timesteps=None,
    trajectories_shape=(),
    initial_step=0,
    mask=None,
    experimental_parallelize=False
)

Constructs the joint distribution over parameters and observed values.

Args
observed_time_series Optional observed time series to model, as a Tensor or tfp.sts.MaskedTimeSeries instance having shape concat([batch_shape, trajectories_shape, num_timesteps, 1]). If an observed time series is provided, the num_timesteps, trajectories_shape, and mask arguments are ignored, and an unnormalized (pinned) distribution over parameter values is returned. Default value: None.
num_timesteps scalar int Tensor number of timesteps to model. This must be specified either directly or by passing an observed_time_series. Default value: 0.
trajectories_shape int Tensor shape of sampled trajectories for each set of parameter values. Ignored if an observed_time_series is passed. Default value: ().
initial_step Optional scalar int Tensor specifying the starting timestep. Default value: 0.
mask Optional bool Tensor having shape concat([batch_shape, trajectories_shape, num_timesteps]), in which True entries indicate that the series value at the corresponding step is missing and should be ignored. This argument should be passed only if observed_time_series is not specified or does not already contain a missingness mask; it is an error to pass both this argument and an observed_time_series value containing a missingness mask. Default value: None.
experimental_parallelize If True, use parallel message passing algorithms from tfp.experimental.parallel_filter to perform time series operations in O(log num_timesteps) sequential steps. The overall FLOP and memory cost may be larger than for the sequential implementations by a constant factor. Default value: False.

Returns
joint_distribution joint distribution of model parameters and observed trajectories. If no observed_time_series was specified, this is an instance of tfd.JointDistributionNamedAutoBatched with a random variable for each model parameter (with names and order matching self.parameters), plus a final random variable observed_time_series representing a trajectory(ies) conditioned on the parameters. If observed_time_series was specified, the return value is given by joint_distribution.experimental_pin( observed_time_series=observed_time_series) where joint_distribution is as just described, so it defines an unnormalized posterior distribution over the parameters.

Example:

The joint distribution can generate prior samples of parameters and trajectories:

from matplotlib import pylab as plt
import tensorflow_probability as tfp; tfp = tfp.substrates.numpy

# Sample and plot 100 trajectories from the prior.
model = tfp.sts.LocalLinearTrend()
prior_samples = model.joint_distribution(num_timesteps=200).sample([100])
plt.plot(
  tf.linalg.matrix_transpose(prior_samples['observed_time_series'][..., 0]))

It also integrates with TFP inference APIs, providing a more flexible alternative to the STS-specific fitting utilities.

jd = model.joint_distribution(observed_time_series)

# Variational inference.
surrogate_posterior = (
  tfp.experimental.vi.build_factored_surrogate_posterior(
    event_shape=jd.event_shape,
    bijector=jd.experimental_default_event_space_bijector()))
losses = tfp.vi.fit_surrogate_posterior(
  target_log_prob_fn=jd.unnormalized_log_prob,
  surrogate_posterior=surrogate_posterior,
  optimizer=tf.optimizers.Adam(0.1),
  num_steps=200)
parameter_samples = surrogate_posterior.sample(50)

# No U-Turn Sampler.
samples, kernel_results = tfp.experimental.mcmc.windowed_adaptive_nuts(
  n_draws=500, joint_dist=dist)

joint_log_prob

View source

joint_log_prob(
    observed_time_series
)

Build the joint density log p(params) + log p(y|params) as a callable.

Args
observed_time_series Observed Tensor trajectories of shape sample_shape + batch_shape + [num_timesteps, 1] (the trailing 1 dimension is optional if num_timesteps > 1), where batch_shape should match self.batch_shape (the broadcast batch shape of all priors on parameters for this structural time series model). Any NaNs are interpreted as missing observations; missingness may be also be explicitly specified by passing a tfp.sts.MaskedTimeSeries instance.

Returns
log_joint_fn A function taking a Tensor argument for each model parameter, in canonical order, and returning a Tensor log probability of shape batch_shape. Note that, unlike tfp.Distributions log_prob methods, the log_joint sums over the sample_shape from y, so that sample_shape does not appear in the output log_prob. This corresponds to viewing multiple samples in y as iid observations from a single model, which is typically the desired behavior for parameter inference.

make_state_space_model

View source

make_state_space_model(
    num_timesteps,
    param_vals,
    initial_state_prior=None,
    initial_step=0,
    **linear_gaussian_ssm_kwargs
)

Instantiate this model as a Distribution over specified num_timesteps.

Args
num_timesteps Python int number of timesteps to model.
param_vals a list of Tensor parameter values in order corresponding to self.parameters, or a dict mapping from parameter names to values.
initial_state_prior an optional Distribution instance overriding the default prior on the model's initial state. This is used in forecasting ("today's prior is yesterday's posterior").
initial_step optional int specifying the initial timestep to model. This is relevant when the model contains time-varying components, e.g., holidays or seasonality.
**linear_gaussian_ssm_kwargs Optional additional keyword arguments to to the base tfd.LinearGaussianStateSpaceModel constructor.

Returns
dist a LinearGaussianStateSpaceModel Distribution object.

prior_sample

View source

prior_sample(
    num_timesteps,
    initial_step=0,
    params_sample_shape=(),
    trajectories_sample_shape=(),
    seed=None
)

Sample from the joint prior over model parameters and trajectories.

Args
num_timesteps Scalar int Tensor number of timesteps to model.
initial_step Optional scalar int Tensor specifying the starting timestep. Default value: 0.
params_sample_shape Number of possible worlds to sample iid from the parameter prior, or more generally, Tensor int shape to fill with iid samples. Default value: [] (i.e., draw a single sample and don't expand the shape).
trajectories_sample_shape For each sampled set of parameters, number of trajectories to sample, or more generally, Tensor int shape to fill with iid samples. Default value: [] (i.e., draw a single sample and don't expand the shape).
seed PRNG seed; see tfp.random.sanitize_seed for details. Default value: None.

Returns
trajectories float Tensor of shape trajectories_sample_shape + params_sample_shape + [num_timesteps, 1] containing all sampled trajectories.
param_samples list of sampled parameter value Tensors, in order corresponding to self.parameters, each of shape params_sample_shape + prior.batch_shape + prior.event_shape.

__add__

View source

__add__(
    other
)

Models the sum of the series from the two components.