tfp.sts.Sum

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 `float` `Tensor` of shape broadcasting to `concat([batch_shape, [num_timesteps]]`) 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. Any `NaN`s 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` 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.
`init_parameters`	Parameters used to instantiate this `StructuralTimeSeries`.
`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)`.

`joint_distribution`

View source

joint_distribution(
    observed_time_series=None, num_timesteps=None, trajectories_shape=None,
    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. If not specified (either directly or by passing an `observed_time_series`), defaults to a one-to-one correspondence between trajectories and parameter settings (implicitly `trajectories_shape=()`). Default value: `None`.
`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.

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

# Sample and plot 100 trajectories from the prior.
model = tfp.sts.LocalLinearTrendModel()
prior_samples = model.joint_distribution().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. (deprecated)

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.

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 `NaN`s 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.

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, **linear_gaussian_ssm_kwargs
)

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.
`**linear_gaussian_ssm_kwargs`	Optional additional keyword arguments to to the base `tfd.LinearGaussianStateSpaceModel` constructors.

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, 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. (deprecated)

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 `Tensor`s, 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.

tfp.sts.Sum

Used in the notebooks

Examples

Args

Raises

Attributes

Methods

batch_shape_tensor

copy

joint_distribution

Example:

joint_log_prob

make_component_state_space_models

make_state_space_model

prior_sample

__add__

`batch_shape_tensor`

`copy`

`joint_distribution`

`joint_log_prob`

`make_component_state_space_models`

`make_state_space_model`

`prior_sample`

`add`