Missed TensorFlow Dev Summit? Check out the video playlist. Watch recordings


View source on GitHub

Base class for structural time series models.

    parameters, latent_size, name='StructuralTimeSeries'

A StructuralTimeSeries object represents a declarative specification of a structural time series model, including priors on model parameters. It implements a joint probability model p(params, y) = p(params) p(y | params), where params denotes a list of real-valued parameters specified by the child class, and p(y | params) is a linear Gaussian state space model with structure determined by the child class.


  • parameters: list of Parameter namedtuples, each specifying the name and prior distribution of a model parameter along with a bijective transformation from an unconstrained space to the support of that parameter. The order of this list determines the canonical parameter ordering used by fitting and inference algorithms.
  • latent_size: Python int specifying the dimensionality of the latent state space for this model.
  • name: Python str name for this model component.


  • batch_shape: Static batch shape of models represented by this component.

  • 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.



View source


Runtime batch shape of models represented by this component.


  • 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().


View source


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


  • 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). May optionally be an instance of tfp.sts.MaskedTimeSeries, which includes a mask Tensor to specify timesteps with missing observations.


  • 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.


View source

    num_timesteps, param_vals=None, initial_state_prior=None, initial_step=0

Instantiate this model as a Distribution over specified num_timesteps.


  • 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.


  • dist: a LinearGaussianStateSpaceModel Distribution object.


View source

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

Sample from the joint prior over model parameters and trajectories.


  • 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: .
  • 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: .
  • seed: Python int random seed.


  • 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.