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
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. 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, 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.
|
View source on GitHub