tfp.sts.Sum

See Stable See Nightly

Sum of structural time series components.

Inherits From: StructuralTimeSeries

tfp.sts.Sum(
    components, constant_offset=None, observation_noise_scale_prior=None,
    observed_time_series=None, name=None
)

Used in the notebooks

Used in the tutorials
Structural Time Series Modeling Case Studies: Atmospheric CO2 and Electricity Demand Approximate inference for STS models with non-Gaussian observations

This class enables compositional specification of a structural time series model from basic components. Given a list of component models, it represents an additive model, i.e., a model of time series that may be decomposed into a sum of terms corresponding to the component models.

Formally, the additive model represents a random process g[t] = f1[t] + f2[t] + ... + fN[t] + eps[t], where the f's are the random processes represented by the components, and eps[t] ~ Normal(loc=0, scale=observation_noise_scale) is an observation noise term. See the AdditiveStateSpaceModel documentation for mathematical details.

This model inherits the parameters (with priors) of its components, and adds an observation_noise_scale parameter governing the level of noise in the observed time series.

Examples

To construct a model combining a local linear trend with a day-of-week effect:

  local_trend = tfp.sts.LocalLinearTrend(
      observed_time_series=observed_time_series,
      name='local_trend')
  day_of_week_effect = tfp.sts.Seasonal(
      num_seasons=7,
      observed_time_series=observed_time_series,
      name='day_of_week_effect')
  additive_model = tfp.sts.Sum(
      components=[local_trend, day_of_week_effect],
      observed_time_series=observed_time_series)

  print([p.name for p in additive_model.parameters])
  # => `[observation_noise_scale,
  #      local_trend_level_scale,
  #      local_trend_slope_scale,
  #      day_of_week_effect_drift_scale`]

  print(local_trend.latent_size,
        seasonal.latent_size,
        additive_model.latent_size)
  # => `2`, `7`, `9`

Args
components	Python list of one or more StructuralTimeSeries instances. These must have unique names.
constant_offset	optional scalar float Tensor, or batch of scalars, specifying a constant value added to the sum of outputs from the component models. This allows the components to model the shifted series observed_time_series - constant_offset. If None, this is set to the mean of the provided observed_time_series. Default value: None.
observation_noise_scale_prior	optional tfd.Distribution instance specifying a prior on observation_noise_scale. If None, a heuristic default prior is constructed based on the provided observed_time_series. 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. This is used to set the constant offset, if not provided, and to construct a default heuristic observation_noise_scale_prior if not provided. May optionally be an instance of tfp.sts.MaskedTimeSeries, which includes a mask Tensor to specify timesteps with missing observations. Default value: None.
name	Python str name of this model component; used as name_scope for ops created by this class. Default value: 'Sum'.

Raises
ValueError	if components do not have unique names.

Attributes
batch_shape	Static batch shape of models represented by this component.
components	List of component StructuralTimeSeries models.
components_by_name	OrderedDict mapping component names to components.
constant_offset	Constant value subtracted from observed data.
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().

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

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_component_state_space_models

View source

make_component_state_space_models(
    num_timesteps, param_vals, initial_step=0
)

Build an ordered list of Distribution instances for component models.

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_step	optional int specifying the initial timestep to model. This is relevant when the model contains time-varying components, e.g., holidays or seasonality.

Returns
component_ssms	a Python list of LinearGaussianStateSpaceModel Distribution objects, in order corresponding to self.components.

make_state_space_model

View source

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

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.

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

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.