Sum of structural time series components.
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
This model inherits the parameters (with priors) of its components, and
observation_noise_scale parameter governing the level of noise in
the observed time series.
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`
__init__( components, observation_noise_scale_prior=None, observed_time_series=None, name=None )
Specify a structural time series model representing a sum of components.
listof one or more StructuralTimeSeries instances. These must have unique names.
tfd.Distributioninstance specifying a prior on
None, a heuristic default prior is constructed based on the provided
observed_time_series. Default value:
batch_shape + [T, 1](omitting the trailing unit dimension is also supported when
T > 1), specifying an observed time series. This is used only if
observation_noise_scale_prioris not provided, to construct a default heuristic prior. Default value:
strname of this model component; used as
name_scopefor ops created by this class. Default value: 'Sum'.
ValueError: if components do not have unique names.
Static batch shape of models represented by this component.
tf.TensorShapegiving 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. It may be partially defined or unknown.
List of component
OrderedDict mapping component names to components.
int dimensionality of the latent space in this model.
Name of this model component.
List of Parameter(name, prior, bijector) namedtuples for this model.
Runtime batch shape of models represented by this component.
Tensorgiving the broadcast batch shape of all model parameters. This should match the batch shape of derived state space models, i.e.,
Build the joint density
log p(params) + log p(y|params) as a callable.
Tensortrajectories of shape
sample_shape + batch_shape + [num_timesteps, 1](the trailing
1dimension is optional if
num_timesteps > 1), where
self.batch_shape(the broadcast batch shape of all priors on parameters for this structural time series model).
log_joint_fn: A function taking a
Tensor argument for each model
parameter, in canonical order, and returning a
Tensor log probability
batch_shape. Note that, unlike
log_prob methods, the
log_joint sums over the
sample_shape from y,
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
make_state_space_model( num_timesteps, param_vals=None, initial_state_prior=None, initial_step=0 )
Instantiate this model as a Distribution over specified
intnumber of timesteps to model.
param_vals: a list of
Tensorparameter values in order corresponding to
self.parameters, or a dict mapping from parameter names to values.
initial_state_prior: an optional
Distributioninstance overriding the default prior on the model's initial state. This is used in forecasting ("today's prior is yesterday's posterior").
intspecifying the initial timestep to model. This is relevant when the model contains time-varying components, e.g., holidays or seasonality.
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.
Tensornumber of timesteps to model.
initial_step: Optional scalar
Tensorspecifying the starting timestep. Default value: 0.
params_sample_shape: Number of possible worlds to sample iid from the parameter prior, or more generally,
intshape to fill with iid samples. Default value: .
trajectories_sample_shape: For each sampled set of parameters, number of trajectories to sample, or more generally,
intshape to fill with iid samples. Default value: .
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.