View source on GitHub
|
Formal representation of a semi-local linear trend model.
Inherits From: StructuralTimeSeries
tfp.sts.SemiLocalLinearTrend(
level_scale_prior=None, slope_mean_prior=None, slope_scale_prior=None,
autoregressive_coef_prior=None, initial_level_prior=None,
initial_slope_prior=None, observed_time_series=None,
constrain_ar_coef_stationary=True, constrain_ar_coef_positive=False, name=None
)
Like the LocalLinearTrend model, a semi-local linear trend posits a
latent level and slope, with the level component updated according to
the current slope plus a random walk:
level[t] = level[t-1] + slope[t-1] + Normal(0., level_scale)
The slope component in a SemiLocalLinearTrend model evolves according to
a first-order autoregressive (AR1) process with potentially nonzero mean:
slope[t] = (slope_mean +
autoregressive_coef * (slope[t-1] - slope_mean) +
Normal(0., slope_scale))
Unlike the random walk used in LocalLinearTrend, a stationary
AR1 process (coefficient in (-1, 1)) maintains bounded variance over time,
so a SemiLocalLinearTrend model will often produce more reasonable
uncertainties when forecasting over long timescales.
Args | |
|---|---|
level_scale_prior
|
optional tfd.Distribution instance specifying a prior
on the level_scale parameter. If None, a heuristic default prior is
constructed based on the provided observed_time_series.
Default value: None.
|
slope_mean_prior
|
optional tfd.Distribution instance specifying a prior
on the slope_mean parameter. If None, a heuristic default prior is
constructed based on the provided observed_time_series.
Default value: None.
|
slope_scale_prior
|
optional tfd.Distribution instance specifying a prior
on the slope_scale parameter. If None, a heuristic default prior is
constructed based on the provided observed_time_series.
Default value: None.
|
autoregressive_coef_prior
|
optional tfd.Distribution instance specifying
a prior on the autoregressive_coef parameter. If None, the default
prior is a standard Normal(0., 1.). Note that the prior may be
implicitly truncated by constrain_ar_coef_stationary and/or
constrain_ar_coef_positive.
Default value: None.
|
initial_level_prior
|
optional tfd.Distribution instance specifying a
prior on the initial level. If None, a heuristic default prior is
constructed based on the provided observed_time_series.
Default value: None.
|
initial_slope_prior
|
optional tfd.Distribution instance specifying a
prior on the initial slope. 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 NaNs
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.
|
constrain_ar_coef_stationary
|
if True, perform inference using a
parameterization that restricts autoregressive_coef to the interval
(-1, 1), or (0, 1) if force_positive_ar_coef is also True,
corresponding to stationary processes. This will implicitly truncate
the support of autoregressive_coef_prior.
Default value: True.
|
constrain_ar_coef_positive
|
if True, perform inference using a
parameterization that restricts autoregressive_coef to be positive,
or in (0, 1) if constrain_ar_coef_stationary is also True. This
will implicitly truncate the support of autoregressive_coef_prior.
Default value: False.
|
name
|
the name of this model component. Default value: 'SemiLocalLinearTrend'. |
Attributes | |
|---|---|
batch_shape
|
Static batch shape of models represented by this component. |
init_parameters
|
Parameters used to instantiate this StructuralTimeSeries.
|
initial_state_prior
|
Prior distribution on the initial latent state (level and scale). |
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
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
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
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.
|
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
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.
|
| 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_state_space_model
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
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 Tensors, in order
corresponding to self.parameters, each of shape
params_sample_shape + prior.batch_shape + prior.event_shape.
|
__add__
__add__(
other
)
Models the sum of the series from the two components.