# tfp.sts.Autoregressive

Formal representation of an autoregressive model.

Inherits From: `StructuralTimeSeries`

### Used in the notebooks

Used in the tutorials

An autoregressive (AR) model posits a latent `level` whose value at each step is a noisy linear combination of previous steps:

``````level[t+1] = (sum(coefficients * levels[t:t-order:-1]) +
Normal(0., level_scale))
``````

The latent state is `levels[t:t-order:-1]`. We observe a noisy realization of the current level: `f[t] = level[t] + Normal(0., observation_noise_scale)` at each timestep.

If `coefficients=[1.]`, the AR process is a simple random walk, equivalent to a `LocalLevel` model. However, a random walk's variance increases with time, while many AR processes (in particular, any first-order process with `abs(coefficient) < 1`) are stationary, i.e., they maintain a constant variance over time. This makes AR processes useful models of uncertainty.

See the Wikipedia article for details on stationarity and other mathematical properties of autoregressive processes.

`order` scalar Python positive `int` specifying the number of past timesteps to regress on.
`coefficients_prior` optional `tfd.Distribution` instance specifying a prior on the `coefficients` parameter. If `None`, a default standard normal (`tfd.MultivariateNormalDiag(scale_diag=tf.ones([order]))`) prior is used. Default value: `None`.
`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`.
`initial_state_prior` optional `tfd.Distribution` instance specifying a prior on the initial state, corresponding to the values of the process at a set of size `order` of imagined timesteps before the initial step. If `None`, a heuristic default prior is constructed based on the provided `observed_time_series`. Default value: `None`.
`coefficient_constraining_bijector` optional `tfb.Bijector` instance representing a constraining mapping for the autoregressive coefficients. For example, `tfb.Tanh()` constrains the coefficients to lie in `(-1, 1)`, while `tfb.Softplus()` constrains them to be positive, and `tfb.Identity()` implies no constraint. If `None`, the default behavior constrains the coefficients to lie in `(-1, 1)` using a `Tanh` bijector. 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` the name of this model component. Default value: 'Autoregressive'.

`batch_shape` Static batch shape of models represented by this component.
`init_parameters` Parameters used to instantiate this `StructuralTimeSeries`.
`initial_state_prior`

`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

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

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

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. Ignored if an `observed_time_series` is passed. Default value: `()`.
`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.LocalLinearTrend()
prior_samples = model.joint_distribution(num_timesteps=200).sample()
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,
num_steps=200)
parameter_samples = surrogate_posterior.sample(50)

# No U-Turn Sampler.
n_draws=500, joint_dist=dist)
``````

### `joint_log_prob`

View source

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

### `make_state_space_model`

View source

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

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

Models the sum of the series from the two components.

[]
[]