@@ -33,6 +35,39 @@ This kernel is part of the Matern family of kernels, with parameter 3/2.
where the double-bars represent vector length (i.e. Euclidean, or L2 Norm).
This kernel, acts over the space `S = R^(D1 x D2 .. x Dd)`.
+
+
+``` python
+__init__(
+ amplitude=None,
+ length_scale=None,
+ feature_ndims=1,
+ validate_args=False,
+ name='MaternThreeHalves'
+)
+```
+
+Construct a MaternThreeHalves kernel instance.
+
+#### Args:
+
+*
: Positive floating point `Tensor` that controls the maximum
+ value of the kernel. Must be broadcastable with `length_scale` and
+ inputs to `apply` and `matrix` methods. A value of `None` is treated
+ like 1.
+*
: Positive floating point `Tensor` that controls how sharp or
+ wide the kernel shape is. This provides a characteristic "unit" of
+ length against which `||x - y||` can be compared for scale. Must be
+ broadcastable with `amplitude` and inputs to `apply` and `matrix`
+ methods. A value of `None` is treated like 1.
+*
: Python `int` number of rightmost dims to include in the
+ squared difference norm in the exponential.
+*
: If `True`, parameters are checked for validity despite
+ possibly degrading runtime performance
+*
: Python `str` name prefixed to Ops created by this class.
+
+
+
## Properties
@@ -69,6 +104,10 @@ concrete implementation sub-classes are obliged to provide.
`TensorShape` instance describing the fully broadcast shape of all
kernel parameters.
+
The number of feature dimensions.
@@ -100,37 +139,6 @@ Name prepended to all ops created by this class.
## Methods
-
-
-``` python
-__init__(
- amplitude=None,
- length_scale=None,
- feature_ndims=1,
- validate_args=False,
- name='MaternThreeHalves'
-)
-```
-
-Construct a MaternThreeHalves kernel instance.
-
-#### Args:
-
-*
: Positive floating point `Tensor` that controls the maximum
- value of the kernel. Must be broadcastable with `length_scale` and
- inputs to `apply` and `matrix` methods. A value of `None` is treated
- like 1.
-*
: Positive floating point `Tensor` that controls how sharp
- or wide the kernel shape is. This provides a characteristic "unit" of
- length against which `||x - y||` can be compared for scale. Must be
- broadcastable with `amplitude` and inputs to `apply` and `matrix`
- methods. A value of `None` is treated like 1.
-*
: Python `int` number of rightmost dims to include in the
- squared difference norm in the exponential.
-*
: If `True`, parameters are checked for validity despite
- possibly degrading runtime performance
-*
``` python
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/positive_semidefinite_kernels/PositiveSemidefiniteKernel.md b/tensorflow_probability/g3doc/api_docs/python/tfp/positive_semidefinite_kernels/PositiveSemidefiniteKernel.md
index 2adb29af9c..54a58d51de 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/positive_semidefinite_kernels/PositiveSemidefiniteKernel.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/positive_semidefinite_kernels/PositiveSemidefiniteKernel.md
@@ -1,6 +1,8 @@
+
+
@@ -101,6 +103,46 @@ partition into 3 pieces:
requirement is that batch dimensions of inputs `x` and `y` be broadcastable
with each other and with the kernel's parameter batch shapes (see above).
+
__init__
+
+``` python
+__init__(
+ feature_ndims,
+ dtype=None,
+ name=None
+)
+```
+
+Construct a PositiveSemidefiniteKernel (subclass) instance.
+
+#### Args:
+
+*
`feature_ndims`: Python `integer` indicating the number of dims (the rank)
+ of the feature space this kernel acts on.
+*
`dtype`: `DType` on which this kernel operates.
+*
`name`: Python `str` name prefixed to Ops created by this class. Default:
+ subclass name.
+
+
+#### Raises:
+
+*
`ValueError`: if `feature_ndims` is not an integer greater than 0
+Inputs to PositiveSemidefiniteKernel methods partition into 3 pieces:
+
+```none
+[b1, ..., bB, e, f1, ..., fF]
+'----------' | '---------'
+ | | '-- Feature dimensions
+ | '-- Example dimension (`matrix`-only)
+ '-- Batch dimensions
+```
+
+The `feature_ndims` argument declares how many of the right-most shape
+dimensions belong to the feature dimensions. This enables us to predict
+which shape dimensions will be 'reduced' away during kernel computation.
+
+
+
## Properties
batch_shape
@@ -133,6 +175,10 @@ concrete implementation sub-classes are obliged to provide.
`TensorShape` instance describing the fully broadcast shape of all
kernel parameters.
+
dtype
+
+DType over which the kernel operates.
+
feature_ndims
The number of feature dimensions.
@@ -160,42 +206,6 @@ Name prepended to all ops created by this class.
## Methods
-
__init__
-
-``` python
-__init__(
- feature_ndims,
- name=None
-)
-```
-
-Construct a PositiveSemidefiniteKernel (subclass) instance.
-
-#### Args:
-
-*
`feature_ndims`: Python `integer` indicating the number of dims (the rank)
- of the feature space this kernel acts on.
-*
`name`: Python `str` name prefixed to Ops created by this class. Default:
- subclass name.
-
-
-#### Raises:
-
-*
`ValueError`: if `feature_ndims` is not an integer greater than 0
-Inputs to PositiveSemidefiniteKernel methods partition into 3 pieces:
-
-```none
-[b1, ..., bB, e, f1, ..., fF]
-'----------' | '---------'
- | | '-- Feature dimensions
- | '-- Example dimension (`matrix`-only)
- '-- Batch dimensions
-```
-
-The `feature_ndims` argument declares how many of the right-most shape
-dimensions belong to the feature dimensions. This enables us to predict
-which shape dimensions will be 'reduced' away during kernel computation.
-
__add__
``` python
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts.md
new file mode 100644
index 0000000000..ecdd1c1e49
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts.md
@@ -0,0 +1,25 @@
+
+
+
+
+
+# Module: tfp.sts
+
+Framework for Bayesian structural time series models.
+
+## Classes
+
+[`class AdditiveStateSpaceModel`](../tfp/sts/AdditiveStateSpaceModel.md): A state space model representing a sum of component state space models.
+
+[`class LocalLinearTrend`](../tfp/sts/LocalLinearTrend.md): Formal representation of a local linear trend model.
+
+[`class LocalLinearTrendStateSpaceModel`](../tfp/sts/LocalLinearTrendStateSpaceModel.md): State space model for a local linear trend.
+
+[`class Seasonal`](../tfp/sts/Seasonal.md): Formal representation of a seasonal effect model.
+
+[`class SeasonalStateSpaceModel`](../tfp/sts/SeasonalStateSpaceModel.md): State space model for a seasonal effect.
+
+[`class StructuralTimeSeries`](../tfp/sts/StructuralTimeSeries.md): Base class for structural time series models.
+
+[`class Sum`](../tfp/sts/Sum.md): Sum of structural time series components.
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/AdditiveStateSpaceModel.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/AdditiveStateSpaceModel.md
new file mode 100644
index 0000000000..df7ff25a04
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/AdditiveStateSpaceModel.md
@@ -0,0 +1,920 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.AdditiveStateSpaceModel
+
+## Class `AdditiveStateSpaceModel`
+
+Inherits From: [`LinearGaussianStateSpaceModel`](../../tfp/distributions/LinearGaussianStateSpaceModel.md)
+
+A state space model representing a sum of component state space models.
+
+A state space model (SSM) posits a set of latent (unobserved) variables that
+evolve over time with dynamics specified by a probabilistic transition model
+`p(z[t+1] | z[t])`. At each timestep, we observe a value sampled from an
+observation model conditioned on the current state, `p(x[t] | z[t])`. The
+special case where both the transition and observation models are Gaussians
+with mean specified as a linear function of the inputs, is known as a linear
+Gaussian state space model and supports tractable exact probabilistic
+calculations; see
tfp.distributions.LinearGaussianStateSpaceModel for
+details.
+
+The `AdditiveStateSpaceModel` represents a sum of component state space
+models. Each of the `N` components describes a random process
+generating a distribution on observed time series `x1[t], x2[t], ..., xN[t]`.
+The additive model represents the sum of these
+processes, `y[t] = x1[t] + x2[t] + ... + xN[t] + eps[t]`, where
+`eps[t] ~ N(0, observation_noise_scale)` is an observation noise term.
+
+#### Mathematical Details
+
+The additive model concatenates the latent states of its component models.
+The generative process runs each component's dynamics in its own subspace of
+latent space, and then observes the sum of the observation models from the
+components.
+
+Formally, the transition model is linear Gaussian:
+
+```
+p(z[t+1] | z[t]) ~ Normal(loc = transition_matrix.matmul(z[t]),
+ cov = transition_cov)
+```
+
+where each `z[t]` is a latent state vector concatenating the component
+state vectors, `z[t] = [z1[t], z2[t], ..., zN[t]]`, so it has size
+`latent_size = sum([c.latent_size for c in components])`.
+
+The transition matrix is the block-diagonal composition of transition
+matrices from the component processes:
+
+```
+transition_matrix =
+ [[ c0.transition_matrix, 0., ..., 0. ],
+ [ 0., c1.transition_matrix, ..., 0. ],
+ [ ... ... ... ],
+ [ 0., 0., ..., cN.transition_matrix ]]
+```
+
+and the noise covariance is similarly the block-diagonal composition of
+component noise covariances:
+
+```
+transition_cov =
+ [[ c0.transition_cov, 0., ..., 0. ],
+ [ 0., c1.transition_cov, ..., 0. ],
+ [ ... ... ... ],
+ [ 0., 0., ..., cN.transition_cov ]]
+```
+
+The observation model is also linear Gaussian,
+
+```
+p(y[t] | z[t]) ~ Normal(loc = observation_matrix.matmul(z[t]),
+ stddev = observation_noise_scale)
+```
+
+This implementation assumes scalar observations, so
+`observation_matrix` has shape `[1, latent_size]`. The additive
+observation matrix simply concatenates the observation matrices from each
+component:
+
+```
+observation_matrix =
+ concat([c0.obs_matrix, c1.obs_matrix, ..., cN.obs_matrix], axis=-1)
+```
+
+The effect is that each component observation matrix acts on the dimensions
+of latent state corresponding to that component, and the overall expected
+observation is the sum of the expected observations from each component.
+
+If `observation_noise_scale` is not explicitly specified, it is also computed
+by summing the noise variances of the component processes:
+
+```
+observation_noise_scale = sqrt(sum([
+ c.observation_noise_scale**2 for c in components]))
+```
+
+#### Examples
+
+To construct an additive state space model combining a local linear trend
+and day-of-week seasonality component (note, the `StructuralTimeSeries`
+classes, e.g., `Sum`, provide a higher-level interface for this
+construction, which will likely be preferred by most users):
+
+```
+ num_timesteps = 30
+ local_ssm = tfp.sts.LocalLinearTrendStateSpaceModel(
+ num_timesteps=num_timesteps,
+ level_scale=0.5,
+ slope_scale=0.1,
+ initial_state_prior=tfd.MultivariateNormalDiag(
+ loc=[0., 0.], scale_diag=[1., 1.]))
+ day_of_week_ssm = tfp.sts.SeasonalStateSpaceModel(
+ num_timesteps=num_timesteps,
+ num_seasons=7,
+ initial_state_prior=tfd.MultivariateNormalDiag(
+ loc=tf.zeros([7]), scale_diag=tf.ones([7])))
+ additive_ssm = tfp.sts.AdditiveStateSpaceModel(
+ component_ssms=[local_ssm, day_of_week_ssm],
+ observation_noise_scale=0.1)
+
+ y = additive_ssm.sample()
+ print(y.shape)
+ # => []
+```
+
+
__init__
+
+``` python
+__init__(
+ component_ssms,
+ observation_noise_scale=None,
+ initial_state_prior=None,
+ initial_step=0,
+ validate_args=False,
+ allow_nan_stats=True,
+ name=None
+)
+```
+
+Build a state space model representing the sum of component models.
+
+#### Args:
+
+*
`component_ssms`: Python `list` containing one or more
+ `tfd.LinearGaussianStateSpaceModel` instances. The components
+ will in general implement different time-series models, with possibly
+ different `latent_size`, but they must have the same `dtype`, event
+ shape (`num_timesteps` and `observation_size`), and their batch shapes
+ must broadcast to a compatible batch shape.
+*
`observation_noise_scale`: Optional scalar `float` `Tensor` indicating the
+ standard deviation of the observation noise. May contain additional
+ batch dimensions, which must broadcast with the batch shape of elements
+ in `component_ssms`. If `observation_noise_scale` is specified for the
+ `AdditiveStateSpaceModel`, the observation noise scales of component
+ models are ignored. If `None`, the observation noise scale is derived
+ by summing the noise variances of the component models, i.e.,
+ `observation_noise_scale = sqrt(sum(
+ [ssm.observation_noise_scale**2 for ssm in component_ssms]))`.
+*
`initial_state_prior`: Optional instance of `tfd.MultivariateNormal`
+ representing a prior distribution on the latent state at time
+ `initial_step`. If `None`, defaults to the independent priors from
+ component models, i.e.,
+ `[component.initial_state_prior for component in component_ssms]`.
+ Default value: `None`.
+*
`initial_step`: Optional scalar `int` `Tensor` specifying the starting
+ timestep.
+ Default value: 0.
+*
`validate_args`: Python `bool`. Whether to validate input
+ with asserts. If `validate_args` is `False`, and the inputs are
+ invalid, correct behavior is not guaranteed.
+ Default value: `False`.
+*
`allow_nan_stats`: Python `bool`. If `False`, raise an
+ exception if a statistic (e.g. mean/mode/etc...) is undefined for any
+ batch member. If `True`, batch members with valid parameters leading to
+ undefined statistics will return NaN for this statistic.
+ Default value: `True`.
+*
`name`: Python `str` name prefixed to ops created by this class.
+ Default value: "AdditiveStateSpaceModel".
+
+
+#### Raises:
+
+*
`ValueError`: if components have different `num_timesteps`.
+
+
+
+## Properties
+
+
allow_nan_stats
+
+Python `bool` describing behavior when a stat is undefined.
+
+Stats return +/- infinity when it makes sense. E.g., the variance of a
+Cauchy distribution is infinity. However, sometimes the statistic is
+undefined, e.g., if a distribution's pdf does not achieve a maximum within
+the support of the distribution, the mode is undefined. If the mean is
+undefined, then by definition the variance is undefined. E.g. the mean for
+Student's T for df = 1 is undefined (no clear way to say it is either + or -
+infinity), so the variance = E[(X - mean)**2] is also undefined.
+
+#### Returns:
+
+*
`allow_nan_stats`: Python `bool`.
+
+
batch_shape
+
+Shape of a single sample from a single event index as a `TensorShape`.
+
+May be partially defined or unknown.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Returns:
+
+*
`batch_shape`: `TensorShape`, possibly unknown.
+
+
dtype
+
+The `DType` of `Tensor`s handled by this `Distribution`.
+
+
event_shape
+
+Shape of a single sample from a single batch as a `TensorShape`.
+
+May be partially defined or unknown.
+
+#### Returns:
+
+*
`event_shape`: `TensorShape`, possibly unknown.
+
+
name
+
+Name prepended to all ops created by this `Distribution`.
+
+
parameters
+
+Dictionary of parameters used to instantiate this `Distribution`.
+
+
reparameterization_type
+
+Describes how samples from the distribution are reparameterized.
+
+Currently this is one of the static instances
+`distributions.FULLY_REPARAMETERIZED`
+or `distributions.NOT_REPARAMETERIZED`.
+
+#### Returns:
+
+An instance of `ReparameterizationType`.
+
+
validate_args
+
+Python `bool` indicating possibly expensive checks are enabled.
+
+
+
+## Methods
+
+
batch_shape_tensor
+
+``` python
+batch_shape_tensor(name='batch_shape_tensor')
+```
+
+Shape of a single sample from a single event index as a 1-D `Tensor`.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`batch_shape`: `Tensor`.
+
+
cdf
+
+``` python
+cdf(
+ value,
+ name='cdf'
+)
+```
+
+Cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+cdf(x) := P[X <= x]
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
copy
+
+``` python
+copy(**override_parameters_kwargs)
+```
+
+Creates a deep copy of the distribution.
+
+Note: the copy distribution may continue to depend on the original
+initialization arguments.
+
+#### Args:
+
+*
`**override_parameters_kwargs`: String/value dictionary of initialization
+ arguments to override with new values.
+
+
+#### Returns:
+
+*
`distribution`: A new instance of `type(self)` initialized from the union
+ of self.parameters and override_parameters_kwargs, i.e.,
+ `dict(self.parameters, **override_parameters_kwargs)`.
+
+
covariance
+
+``` python
+covariance(name='covariance')
+```
+
+Covariance.
+
+Covariance is (possibly) defined only for non-scalar-event distributions.
+
+For example, for a length-`k`, vector-valued distribution, it is calculated
+as,
+
+```none
+Cov[i, j] = Covariance(X_i, X_j) = E[(X_i - E[X_i]) (X_j - E[X_j])]
+```
+
+where `Cov` is a (batch of) `k x k` matrix, `0 <= (i, j) < k`, and `E`
+denotes expectation.
+
+Alternatively, for non-vector, multivariate distributions (e.g.,
+matrix-valued, Wishart), `Covariance` shall return a (batch of) matrices
+under some vectorization of the events, i.e.,
+
+```none
+Cov[i, j] = Covariance(Vec(X)_i, Vec(X)_j) = [as above]
+```
+
+where `Cov` is a (batch of) `k' x k'` matrices,
+`0 <= (i, j) < k' = reduce_prod(event_shape)`, and `Vec` is some function
+mapping indices of this distribution's event dimensions to indices of a
+length-`k'` vector.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`covariance`: Floating-point `Tensor` with shape `[B1, ..., Bn, k', k']`
+ where the first `n` dimensions are batch coordinates and
+ `k' = reduce_prod(self.event_shape)`.
+
+
cross_entropy
+
+``` python
+cross_entropy(
+ other,
+ name='cross_entropy'
+)
+```
+
+Computes the (Shannon) cross entropy.
+
+Denote this distribution (`self`) by `P` and the `other` distribution by
+`Q`. Assuming `P, Q` are absolutely continuous with respect to
+one another and permit densities `p(x) dr(x)` and `q(x) dr(x)`, (Shanon)
+cross entropy is defined as:
+
+```none
+H[P, Q] = E_p[-log q(X)] = -int_F p(x) log q(x) dr(x)
+```
+
+where `F` denotes the support of the random variable `X ~ P`.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cross_entropy`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of (Shanon) cross entropy.
+
+
entropy
+
+``` python
+entropy(name='entropy')
+```
+
+Shannon entropy in nats.
+
+
event_shape_tensor
+
+``` python
+event_shape_tensor(name='event_shape_tensor')
+```
+
+Shape of a single sample from a single batch as a 1-D int32 `Tensor`.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`event_shape`: `Tensor`.
+
+
forward_filter
+
+``` python
+forward_filter(x)
+```
+
+Run a Kalman filter over a provided sequence of outputs.
+
+Note that the returned values `filtered_means`, `predicted_means`, and
+`observation_means` depend on the observed time series `x`, while the
+corresponding covariances are independent of the observed series; i.e., they
+depend only on the model itself. This means that the mean values have shape
+`concat([sample_shape(x), batch_shape, [num_timesteps,
+{latent/observation}_size]])`, while the covariances have shape
+`concat[(batch_shape, [num_timesteps, {latent/observation}_size,
+{latent/observation}_size]])`, which does not depend on the sample shape.
+
+#### Args:
+
+*
`x`: a float-type `Tensor` with rightmost dimensions
+ `[num_timesteps, observation_size]` matching
+ `self.event_shape`. Additional dimensions must match or be
+ broadcastable to `self.batch_shape`; any further dimensions
+ are interpreted as a sample shape.
+
+
+#### Returns:
+
+*
`log_likelihoods`: Per-timestep log marginal likelihoods `log
+ p(x_t | x_{:t-1})` evaluated at the input `x`, as a `Tensor`
+ of shape `sample_shape(x) + batch_shape + [num_timesteps].`
+*
`filtered_means`: Means of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `sample_shape(x) + batch_shape + [num_timesteps, latent_size]`.
+*
`filtered_covs`: Covariances of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `batch_shape + [num_timesteps, latent_size, latent_size]`.
+*
`predicted_means`: Means of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, latent_size]`.
+*
`predicted_covs`: Covariances of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `batch_shape + [num_timesteps, latent_size,
+ latent_size]`.
+*
`observation_means`: Means of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, observation_size]`.
+*
`observation_covs`: Covariances of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `batch_shape + [num_timesteps,
+ observation_size, observation_size]`.
+
+
is_scalar_batch
+
+``` python
+is_scalar_batch(name='is_scalar_batch')
+```
+
+Indicates that `batch_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_batch`: `bool` scalar `Tensor`.
+
+
is_scalar_event
+
+``` python
+is_scalar_event(name='is_scalar_event')
+```
+
+Indicates that `event_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_event`: `bool` scalar `Tensor`.
+
+
kl_divergence
+
+``` python
+kl_divergence(
+ other,
+ name='kl_divergence'
+)
+```
+
+Computes the Kullback--Leibler divergence.
+
+Denote this distribution (`self`) by `p` and the `other` distribution by
+`q`. Assuming `p, q` are absolutely continuous with respect to reference
+measure `r`, the KL divergence is defined as:
+
+```none
+KL[p, q] = E_p[log(p(X)/q(X))]
+ = -int_F p(x) log q(x) dr(x) + int_F p(x) log p(x) dr(x)
+ = H[p, q] - H[p]
+```
+
+where `F` denotes the support of the random variable `X ~ p`, `H[., .]`
+denotes (Shanon) cross entropy, and `H[.]` denotes (Shanon) entropy.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`kl_divergence`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of the Kullback-Leibler
+ divergence.
+
+
log_cdf
+
+``` python
+log_cdf(
+ value,
+ name='log_cdf'
+)
+```
+
+Log cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+log_cdf(x) := Log[ P[X <= x] ]
+```
+
+Often, a numerical approximation can be used for `log_cdf(x)` that yields
+a more accurate answer than simply taking the logarithm of the `cdf` when
+`x << -1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`logcdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_prob
+
+``` python
+log_prob(
+ value,
+ name='log_prob'
+)
+```
+
+Log probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`log_prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_survival_function
+
+``` python
+log_survival_function(
+ value,
+ name='log_survival_function'
+)
+```
+
+Log survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+log_survival_function(x) = Log[ P[X > x] ]
+ = Log[ 1 - P[X <= x] ]
+ = Log[ 1 - cdf(x) ]
+```
+
+Typically, different numerical approximations can be used for the log
+survival function, which are more accurate than `1 - cdf(x)` when `x >> 1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
mean
+
+``` python
+mean(name='mean')
+```
+
+Mean.
+
+
mode
+
+``` python
+mode(name='mode')
+```
+
+Mode.
+
+
param_shapes
+
+``` python
+param_shapes(
+ cls,
+ sample_shape,
+ name='DistributionParamShapes'
+)
+```
+
+Shapes of parameters given the desired shape of a call to `sample()`.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`.
+
+Subclasses should override class method `_param_shapes`.
+
+#### Args:
+
+*
`sample_shape`: `Tensor` or python list/tuple. Desired shape of a call to
+ `sample()`.
+*
`name`: name to prepend ops with.
+
+
+#### Returns:
+
+`dict` of parameter name to `Tensor` shapes.
+
+
param_static_shapes
+
+``` python
+param_static_shapes(
+ cls,
+ sample_shape
+)
+```
+
+param_shapes with static (i.e. `TensorShape`) shapes.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`. Assumes that the sample's
+shape is known statically.
+
+Subclasses should override class method `_param_shapes` to return
+constant-valued tensors when constant values are fed.
+
+#### Args:
+
+*
`sample_shape`: `TensorShape` or python list/tuple. Desired shape of a call
+ to `sample()`.
+
+
+#### Returns:
+
+`dict` of parameter name to `TensorShape`.
+
+
+#### Raises:
+
+*
`ValueError`: if `sample_shape` is a `TensorShape` and is not fully defined.
+
+
prob
+
+``` python
+prob(
+ value,
+ name='prob'
+)
+```
+
+Probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
quantile
+
+``` python
+quantile(
+ value,
+ name='quantile'
+)
+```
+
+Quantile function. Aka "inverse cdf" or "percent point function".
+
+Given random variable `X` and `p in [0, 1]`, the `quantile` is:
+
+```none
+quantile(p) := x such that P[X <= x] == p
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`quantile`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
sample
+
+``` python
+sample(
+ sample_shape=(),
+ seed=None,
+ name='sample'
+)
+```
+
+Generate samples of the specified shape.
+
+Note that a call to `sample()` without arguments will generate a single
+sample.
+
+#### Args:
+
+*
`sample_shape`: 0D or 1D `int32` `Tensor`. Shape of the generated samples.
+*
`seed`: Python integer seed for RNG
+*
`name`: name to give to the op.
+
+
+#### Returns:
+
+*
`samples`: a `Tensor` with prepended dimensions `sample_shape`.
+
+
stddev
+
+``` python
+stddev(name='stddev')
+```
+
+Standard deviation.
+
+Standard deviation is defined as,
+
+```none
+stddev = E[(X - E[X])**2]**0.5
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `stddev.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`stddev`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
survival_function
+
+``` python
+survival_function(
+ value,
+ name='survival_function'
+)
+```
+
+Survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+survival_function(x) = P[X > x]
+ = 1 - P[X <= x]
+ = 1 - cdf(x).
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
variance
+
+``` python
+variance(name='variance')
+```
+
+Variance.
+
+Variance is defined as,
+
+```none
+Var = E[(X - E[X])**2]
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `Var.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`variance`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrend.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrend.md
new file mode 100644
index 0000000000..809a37f264
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrend.md
@@ -0,0 +1,238 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.LocalLinearTrend
+
+## Class `LocalLinearTrend`
+
+Inherits From: [`StructuralTimeSeries`](../../tfp/sts/StructuralTimeSeries.md)
+
+Formal representation of a local linear trend model.
+
+The local linear trend model posits a `level` and `slope`, each
+evolving via a Gaussian random walk:
+
+```
+level[t] = level[t-1] + slope[t-1] + Normal(0., level_scale)
+slope[t] = slope[t-1] + Normal(0., slope_scale)
+```
+
+The latent state is the two-dimensional tuple `[level, slope]`. At each
+timestep we observe a noisy realization of the current level:
+`f[t] = level[t] + Normal(0., observation_noise_scale)`. This model
+is appropriate for data where the trend direction and magnitude (latent
+`slope`) is consistent within short periods but may evolve over time.
+
+Note that this model can produce very high uncertainty forecasts, as
+uncertainty over the slope compounds quickly. If you expect your data to
+have nonzero long-term trend, i.e. that slopes tend to revert to some mean,
+then the `SemiLocalLinearTrend` model may produce sharper forecasts.
+
+
__init__
+
+``` python
+__init__(
+ level_scale_prior=None,
+ slope_scale_prior=None,
+ initial_level_prior=None,
+ initial_slope_prior=None,
+ observed_time_series=None,
+ name=None
+)
+```
+
+Specify a local linear trend model.
+
+#### 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_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`.
+*
`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 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: 'LocalLinearTrend'.
+
+
+
+## Properties
+
+
batch_shape
+
+Static batch shape of models represented by this component.
+
+#### Returns:
+
+*
`batch_shape`: A `tf.TensorShape` 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`. It may be partially
+ defined or unknown.
+
+
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
+
+``` python
+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
+
+``` python
+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).
+
+
+#### 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
+
+``` python
+make_state_space_model(
+ num_timesteps,
+ param_vals=None,
+ 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
+
+``` python
+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 `Tensor`s, in order
+ corresponding to `self.parameters`, each of shape
+ `params_sample_shape + prior.batch_shape + prior.event_shape`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrendStateSpaceModel.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrendStateSpaceModel.md
new file mode 100644
index 0000000000..3391dbc548
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/LocalLinearTrendStateSpaceModel.md
@@ -0,0 +1,889 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.LocalLinearTrendStateSpaceModel
+
+## Class `LocalLinearTrendStateSpaceModel`
+
+Inherits From: [`LinearGaussianStateSpaceModel`](../../tfp/distributions/LinearGaussianStateSpaceModel.md)
+
+State space model for a local linear trend.
+
+A state space model (SSM) posits a set of latent (unobserved) variables that
+evolve over time with dynamics specified by a probabilistic transition model
+`p(z[t+1] | z[t])`. At each timestep, we observe a value sampled from an
+observation model conditioned on the current state, `p(x[t] | z[t])`. The
+special case where both the transition and observation models are Gaussians
+with mean specified as a linear function of the inputs, is known as a linear
+Gaussian state space model and supports tractable exact probabilistic
+calculations; see
tfp.distributions.LinearGaussianStateSpaceModel for
+details.
+
+The local linear trend model is a special case of a linear Gaussian SSM, in
+which the latent state posits a `level` and `slope`, each evolving via a
+Gaussian random walk:
+
+```python
+level[t] = level[t-1] + slope[t-1] + Normal(0., level_scale)
+slope[t] = slope[t-1] + Normal(0., slope_scale)
+```
+
+The latent state is the two-dimensional tuple `[level, slope]`. The
+`level` is observed at each timestep.
+
+The parameters `level_scale`, `slope_scale`, and `observation_noise_scale`
+are each (a batch of) scalars. The batch shape of this `Distribution` is the
+broadcast batch shape of these parameters and of the `initial_state_prior`.
+
+#### Mathematical Details
+
+The linear trend model implements a
+
tfp.distributions.LinearGaussianStateSpaceModel with `latent_size = 2`
+and `observation_size = 1`, following the transition model:
+
+```
+transition_matrix = [[1., 1.]
+ [0., 1.]]
+transition_noise ~ N(loc=0., scale=diag([level_scale, slope_scale]))
+```
+
+which implements the evolution of `[level, slope]` described above, and
+the observation model:
+
+```
+observation_matrix = [[1., 0.]]
+observation_noise ~ N(loc=0, scale=observation_noise_scale)
+```
+
+which picks out the first latent component, i.e., the `level`, as the
+observation at each timestep.
+
+#### Examples
+
+A simple model definition:
+
+```python
+linear_trend_model = LocalLinearTrendStateSpaceModel(
+ num_timesteps=50,
+ level_scale=0.5,
+ slope_scale=0.5,
+ initial_state_prior=tfd.MultivariateNormalDiag(scale_diag=[1., 1.]))
+
+y = linear_trend_model.sample() # y has shape [50, 1]
+lp = linear_trend_model.log_prob(y) # log_prob is scalar
+```
+
+Passing additional parameter dimensions constructs a batch of models. The
+overall batch shape is the broadcast batch shape of the parameters:
+
+```python
+linear_trend_model = LocalLinearTrendStateSpaceModel(
+ num_timesteps=50,
+ level_scale=tf.ones([10]),
+ slope_scale=0.5,
+ initial_state_prior=tfd.MultivariateNormalDiag(
+ scale_diag=tf.ones([10, 10, 2])))
+
+y = linear_trend_model.sample(5) # y has shape [5, 10, 10, 50, 1]
+lp = linear_trend_model.log_prob(y) # has shape [5, 10, 10]
+```
+
+
__init__
+
+``` python
+__init__(
+ num_timesteps,
+ level_scale,
+ slope_scale,
+ initial_state_prior,
+ observation_noise_scale=0.0,
+ initial_step=0,
+ validate_args=False,
+ allow_nan_stats=True,
+ name=None
+)
+```
+
+Build a state space model implementing a local linear trend.
+
+#### Args:
+
+*
`num_timesteps`: Scalar `int` `Tensor` number of timesteps to model
+ with this distribution.
+*
`level_scale`: Scalar (any additional dimensions are treated as batch
+ dimensions) `float` `Tensor` indicating the standard deviation of the
+ level transitions.
+*
`slope_scale`: Scalar (any additional dimensions are treated as batch
+ dimensions) `float` `Tensor` indicating the standard deviation of the
+ slope transitions.
+*
`initial_state_prior`: instance of `tfd.MultivariateNormal`
+ representing the prior distribution on latent states; must
+ have event shape `[2]`.
+*
`observation_noise_scale`: Scalar (any additional dimensions are
+ treated as batch dimensions) `float` `Tensor` indicating the standard
+ deviation of the observation noise.
+*
`initial_step`: Optional scalar `int` `Tensor` specifying the starting
+ timestep.
+ Default value: 0.
+*
`validate_args`: Python `bool`. Whether to validate input
+ with asserts. If `validate_args` is `False`, and the inputs are
+ invalid, correct behavior is not guaranteed.
+ Default value: `False`.
+*
`allow_nan_stats`: Python `bool`. If `False`, raise an
+ exception if a statistic (e.g. mean/mode/etc...) is undefined for any
+ batch member. If `True`, batch members with valid parameters leading to
+ undefined statistics will return NaN for this statistic.
+ Default value: `True`.
+*
`name`: Python `str` name prefixed to ops created by this class.
+ Default value: "LocalLinearTrendStateSpaceModel".
+
+
+
+## Properties
+
+
allow_nan_stats
+
+Python `bool` describing behavior when a stat is undefined.
+
+Stats return +/- infinity when it makes sense. E.g., the variance of a
+Cauchy distribution is infinity. However, sometimes the statistic is
+undefined, e.g., if a distribution's pdf does not achieve a maximum within
+the support of the distribution, the mode is undefined. If the mean is
+undefined, then by definition the variance is undefined. E.g. the mean for
+Student's T for df = 1 is undefined (no clear way to say it is either + or -
+infinity), so the variance = E[(X - mean)**2] is also undefined.
+
+#### Returns:
+
+*
`allow_nan_stats`: Python `bool`.
+
+
batch_shape
+
+Shape of a single sample from a single event index as a `TensorShape`.
+
+May be partially defined or unknown.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Returns:
+
+*
`batch_shape`: `TensorShape`, possibly unknown.
+
+
dtype
+
+The `DType` of `Tensor`s handled by this `Distribution`.
+
+
event_shape
+
+Shape of a single sample from a single batch as a `TensorShape`.
+
+May be partially defined or unknown.
+
+#### Returns:
+
+*
`event_shape`: `TensorShape`, possibly unknown.
+
+
level_scale
+
+Standard deviation of the level transitions.
+
+
name
+
+Name prepended to all ops created by this `Distribution`.
+
+
observation_noise_scale
+
+Standard deviation of the observation noise.
+
+
parameters
+
+Dictionary of parameters used to instantiate this `Distribution`.
+
+
reparameterization_type
+
+Describes how samples from the distribution are reparameterized.
+
+Currently this is one of the static instances
+`distributions.FULLY_REPARAMETERIZED`
+or `distributions.NOT_REPARAMETERIZED`.
+
+#### Returns:
+
+An instance of `ReparameterizationType`.
+
+
slope_scale
+
+Standard deviation of the slope transitions.
+
+
validate_args
+
+Python `bool` indicating possibly expensive checks are enabled.
+
+
+
+## Methods
+
+
batch_shape_tensor
+
+``` python
+batch_shape_tensor(name='batch_shape_tensor')
+```
+
+Shape of a single sample from a single event index as a 1-D `Tensor`.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`batch_shape`: `Tensor`.
+
+
cdf
+
+``` python
+cdf(
+ value,
+ name='cdf'
+)
+```
+
+Cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+cdf(x) := P[X <= x]
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
copy
+
+``` python
+copy(**override_parameters_kwargs)
+```
+
+Creates a deep copy of the distribution.
+
+Note: the copy distribution may continue to depend on the original
+initialization arguments.
+
+#### Args:
+
+*
`**override_parameters_kwargs`: String/value dictionary of initialization
+ arguments to override with new values.
+
+
+#### Returns:
+
+*
`distribution`: A new instance of `type(self)` initialized from the union
+ of self.parameters and override_parameters_kwargs, i.e.,
+ `dict(self.parameters, **override_parameters_kwargs)`.
+
+
covariance
+
+``` python
+covariance(name='covariance')
+```
+
+Covariance.
+
+Covariance is (possibly) defined only for non-scalar-event distributions.
+
+For example, for a length-`k`, vector-valued distribution, it is calculated
+as,
+
+```none
+Cov[i, j] = Covariance(X_i, X_j) = E[(X_i - E[X_i]) (X_j - E[X_j])]
+```
+
+where `Cov` is a (batch of) `k x k` matrix, `0 <= (i, j) < k`, and `E`
+denotes expectation.
+
+Alternatively, for non-vector, multivariate distributions (e.g.,
+matrix-valued, Wishart), `Covariance` shall return a (batch of) matrices
+under some vectorization of the events, i.e.,
+
+```none
+Cov[i, j] = Covariance(Vec(X)_i, Vec(X)_j) = [as above]
+```
+
+where `Cov` is a (batch of) `k' x k'` matrices,
+`0 <= (i, j) < k' = reduce_prod(event_shape)`, and `Vec` is some function
+mapping indices of this distribution's event dimensions to indices of a
+length-`k'` vector.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`covariance`: Floating-point `Tensor` with shape `[B1, ..., Bn, k', k']`
+ where the first `n` dimensions are batch coordinates and
+ `k' = reduce_prod(self.event_shape)`.
+
+
cross_entropy
+
+``` python
+cross_entropy(
+ other,
+ name='cross_entropy'
+)
+```
+
+Computes the (Shannon) cross entropy.
+
+Denote this distribution (`self`) by `P` and the `other` distribution by
+`Q`. Assuming `P, Q` are absolutely continuous with respect to
+one another and permit densities `p(x) dr(x)` and `q(x) dr(x)`, (Shanon)
+cross entropy is defined as:
+
+```none
+H[P, Q] = E_p[-log q(X)] = -int_F p(x) log q(x) dr(x)
+```
+
+where `F` denotes the support of the random variable `X ~ P`.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cross_entropy`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of (Shanon) cross entropy.
+
+
entropy
+
+``` python
+entropy(name='entropy')
+```
+
+Shannon entropy in nats.
+
+
event_shape_tensor
+
+``` python
+event_shape_tensor(name='event_shape_tensor')
+```
+
+Shape of a single sample from a single batch as a 1-D int32 `Tensor`.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`event_shape`: `Tensor`.
+
+
forward_filter
+
+``` python
+forward_filter(x)
+```
+
+Run a Kalman filter over a provided sequence of outputs.
+
+Note that the returned values `filtered_means`, `predicted_means`, and
+`observation_means` depend on the observed time series `x`, while the
+corresponding covariances are independent of the observed series; i.e., they
+depend only on the model itself. This means that the mean values have shape
+`concat([sample_shape(x), batch_shape, [num_timesteps,
+{latent/observation}_size]])`, while the covariances have shape
+`concat[(batch_shape, [num_timesteps, {latent/observation}_size,
+{latent/observation}_size]])`, which does not depend on the sample shape.
+
+#### Args:
+
+*
`x`: a float-type `Tensor` with rightmost dimensions
+ `[num_timesteps, observation_size]` matching
+ `self.event_shape`. Additional dimensions must match or be
+ broadcastable to `self.batch_shape`; any further dimensions
+ are interpreted as a sample shape.
+
+
+#### Returns:
+
+*
`log_likelihoods`: Per-timestep log marginal likelihoods `log
+ p(x_t | x_{:t-1})` evaluated at the input `x`, as a `Tensor`
+ of shape `sample_shape(x) + batch_shape + [num_timesteps].`
+*
`filtered_means`: Means of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `sample_shape(x) + batch_shape + [num_timesteps, latent_size]`.
+*
`filtered_covs`: Covariances of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `batch_shape + [num_timesteps, latent_size, latent_size]`.
+*
`predicted_means`: Means of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, latent_size]`.
+*
`predicted_covs`: Covariances of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `batch_shape + [num_timesteps, latent_size,
+ latent_size]`.
+*
`observation_means`: Means of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, observation_size]`.
+*
`observation_covs`: Covariances of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `batch_shape + [num_timesteps,
+ observation_size, observation_size]`.
+
+
is_scalar_batch
+
+``` python
+is_scalar_batch(name='is_scalar_batch')
+```
+
+Indicates that `batch_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_batch`: `bool` scalar `Tensor`.
+
+
is_scalar_event
+
+``` python
+is_scalar_event(name='is_scalar_event')
+```
+
+Indicates that `event_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_event`: `bool` scalar `Tensor`.
+
+
kl_divergence
+
+``` python
+kl_divergence(
+ other,
+ name='kl_divergence'
+)
+```
+
+Computes the Kullback--Leibler divergence.
+
+Denote this distribution (`self`) by `p` and the `other` distribution by
+`q`. Assuming `p, q` are absolutely continuous with respect to reference
+measure `r`, the KL divergence is defined as:
+
+```none
+KL[p, q] = E_p[log(p(X)/q(X))]
+ = -int_F p(x) log q(x) dr(x) + int_F p(x) log p(x) dr(x)
+ = H[p, q] - H[p]
+```
+
+where `F` denotes the support of the random variable `X ~ p`, `H[., .]`
+denotes (Shanon) cross entropy, and `H[.]` denotes (Shanon) entropy.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`kl_divergence`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of the Kullback-Leibler
+ divergence.
+
+
log_cdf
+
+``` python
+log_cdf(
+ value,
+ name='log_cdf'
+)
+```
+
+Log cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+log_cdf(x) := Log[ P[X <= x] ]
+```
+
+Often, a numerical approximation can be used for `log_cdf(x)` that yields
+a more accurate answer than simply taking the logarithm of the `cdf` when
+`x << -1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`logcdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_prob
+
+``` python
+log_prob(
+ value,
+ name='log_prob'
+)
+```
+
+Log probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`log_prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_survival_function
+
+``` python
+log_survival_function(
+ value,
+ name='log_survival_function'
+)
+```
+
+Log survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+log_survival_function(x) = Log[ P[X > x] ]
+ = Log[ 1 - P[X <= x] ]
+ = Log[ 1 - cdf(x) ]
+```
+
+Typically, different numerical approximations can be used for the log
+survival function, which are more accurate than `1 - cdf(x)` when `x >> 1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
mean
+
+``` python
+mean(name='mean')
+```
+
+Mean.
+
+
mode
+
+``` python
+mode(name='mode')
+```
+
+Mode.
+
+
param_shapes
+
+``` python
+param_shapes(
+ cls,
+ sample_shape,
+ name='DistributionParamShapes'
+)
+```
+
+Shapes of parameters given the desired shape of a call to `sample()`.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`.
+
+Subclasses should override class method `_param_shapes`.
+
+#### Args:
+
+*
`sample_shape`: `Tensor` or python list/tuple. Desired shape of a call to
+ `sample()`.
+*
`name`: name to prepend ops with.
+
+
+#### Returns:
+
+`dict` of parameter name to `Tensor` shapes.
+
+
param_static_shapes
+
+``` python
+param_static_shapes(
+ cls,
+ sample_shape
+)
+```
+
+param_shapes with static (i.e. `TensorShape`) shapes.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`. Assumes that the sample's
+shape is known statically.
+
+Subclasses should override class method `_param_shapes` to return
+constant-valued tensors when constant values are fed.
+
+#### Args:
+
+*
`sample_shape`: `TensorShape` or python list/tuple. Desired shape of a call
+ to `sample()`.
+
+
+#### Returns:
+
+`dict` of parameter name to `TensorShape`.
+
+
+#### Raises:
+
+*
`ValueError`: if `sample_shape` is a `TensorShape` and is not fully defined.
+
+
prob
+
+``` python
+prob(
+ value,
+ name='prob'
+)
+```
+
+Probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
quantile
+
+``` python
+quantile(
+ value,
+ name='quantile'
+)
+```
+
+Quantile function. Aka "inverse cdf" or "percent point function".
+
+Given random variable `X` and `p in [0, 1]`, the `quantile` is:
+
+```none
+quantile(p) := x such that P[X <= x] == p
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`quantile`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
sample
+
+``` python
+sample(
+ sample_shape=(),
+ seed=None,
+ name='sample'
+)
+```
+
+Generate samples of the specified shape.
+
+Note that a call to `sample()` without arguments will generate a single
+sample.
+
+#### Args:
+
+*
`sample_shape`: 0D or 1D `int32` `Tensor`. Shape of the generated samples.
+*
`seed`: Python integer seed for RNG
+*
`name`: name to give to the op.
+
+
+#### Returns:
+
+*
`samples`: a `Tensor` with prepended dimensions `sample_shape`.
+
+
stddev
+
+``` python
+stddev(name='stddev')
+```
+
+Standard deviation.
+
+Standard deviation is defined as,
+
+```none
+stddev = E[(X - E[X])**2]**0.5
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `stddev.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`stddev`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
survival_function
+
+``` python
+survival_function(
+ value,
+ name='survival_function'
+)
+```
+
+Survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+survival_function(x) = P[X > x]
+ = 1 - P[X <= x]
+ = 1 - cdf(x).
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
variance
+
+``` python
+variance(name='variance')
+```
+
+Variance.
+
+Variance is defined as,
+
+```none
+Var = E[(X - E[X])**2]
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `Var.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`variance`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Seasonal.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Seasonal.md
new file mode 100644
index 0000000000..45ab1d7528
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Seasonal.md
@@ -0,0 +1,291 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.Seasonal
+
+## Class `Seasonal`
+
+Inherits From: [`StructuralTimeSeries`](../../tfp/sts/StructuralTimeSeries.md)
+
+Formal representation of a seasonal effect model.
+
+A seasonal effect model posits a fixed set of recurring, discrete 'seasons',
+each of which is active for a fixed number of timesteps and, while active,
+contributes a different effect to the time series. These are generally not
+meteorological seasons, but represent regular recurring patterns such as
+hour-of-day or day-of-week effects. Each season lasts for a fixed number of
+timesteps. The effect of each season drifts from one occurrence to the next
+following a Gaussian random walk:
+
+```python
+effects[season, occurrence[i]] = (
+ effects[season, occurrence[i-1]] + Normal(loc=0., scale=drift_scale))
+```
+
+The `drift_scale` parameter governs the standard deviation of the random walk;
+for example, in a day-of-week model it governs the change in effect from this
+Monday to next Monday.
+
+#### Examples
+
+A seasonal effect model representing day-of-week seasonality on hourly data:
+
+```python
+day_of_week = tfp.sts.Seasonal(num_seasons=7,
+ num_steps_per_season=24,
+ observed_time_series=y,
+ name='day_of_week')
+```
+
+A seasonal effect model representing month-of-year seasonality on daily data,
+with explicit priors:
+
+```python
+month_of_year = tfp.sts.Seasonal(
+ num_seasons=12,
+ num_steps_per_season=[31, 28, 31, 30, 30, 31, 31, 31, 30, 31, 30, 31],
+ drift_scale_prior=tfd.LogNormal(loc=-1., scale=0.1),
+ initial_effect_prior=tf.Normal(loc=0., scale=5.),
+ name='month_of_year')
+```
+
+Note that a general implementation of month-of-year seasonality would require
+additional logic; this version works over time periods not involving a leap
+year.
+
+A model representing both day-of-week and hour-of-day seasonality, on hourly
+data:
+
+```
+day_of_week = tfp.sts.Seasonal(num_seasons=7,
+ num_steps_per_season=24,
+ observed_time_series=y,
+ name='day_of_week')
+hour_of_day = tfp.sts.Seasonal(num_seasons=24,
+ num_steps_per_season=1,
+ observed_time_series=y,
+ name='hour_of_day')
+model = tfp.sts.Sum(components=[day_of_week, hour_of_day],
+ observed_time_series=y)
+```
+
+
__init__
+
+``` python
+__init__(
+ num_seasons,
+ num_steps_per_season=1,
+ drift_scale_prior=None,
+ initial_effect_prior=None,
+ observed_time_series=None,
+ name=None
+)
+```
+
+Specify a seasonal effects model.
+
+#### Args:
+
+*
`num_seasons`: Scalar Python `int` number of seasons.
+*
`num_steps_per_season`: Python `int` number of steps in each
+ season. This may be either a scalar (shape `[]`), in which case all
+ seasons have the same length, or a NumPy array of shape `[num_seasons]`.
+ Default value: 1.
+*
`drift_scale_prior`: optional `tfd.Distribution` instance specifying a prior
+ on the `drift_scale` parameter. If `None`, a heuristic default prior is
+ constructed based on the provided `observed_time_series`.
+ Default value: `None`.
+*
`initial_effect_prior`: optional `tfd.Distribution` instance specifying a
+ normal prior on the initial effect of each season. This may be either
+ a scalar `tfd.Normal` prior, in which case it applies independently to
+ every season, or it may be multivariate normal (e.g.,
+ `tfd.MultivariateNormalDiag`) with event shape `[num_seasons]`, in
+ which case it specifies a joint prior across all seasons. 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 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: 'Seasonal'.
+
+
+
+## Properties
+
+
batch_shape
+
+Static batch shape of models represented by this component.
+
+#### Returns:
+
+*
`batch_shape`: A `tf.TensorShape` 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`. It may be partially
+ defined or unknown.
+
+
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.
+
+
num_seasons
+
+Number of seasons.
+
+
num_steps_per_season
+
+Number of steps per season.
+
+
parameters
+
+List of Parameter(name, prior, bijector) namedtuples for this model.
+
+
+
+## Methods
+
+
batch_shape_tensor
+
+``` python
+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
+
+``` python
+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).
+
+
+#### 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
+
+``` python
+make_state_space_model(
+ num_timesteps,
+ param_vals=None,
+ 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
+
+``` python
+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 `Tensor`s, in order
+ corresponding to `self.parameters`, each of shape
+ `params_sample_shape + prior.batch_shape + prior.event_shape`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/SeasonalStateSpaceModel.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/SeasonalStateSpaceModel.md
new file mode 100644
index 0000000000..5b87b1d1a7
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/SeasonalStateSpaceModel.md
@@ -0,0 +1,917 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.SeasonalStateSpaceModel
+
+## Class `SeasonalStateSpaceModel`
+
+Inherits From: [`LinearGaussianStateSpaceModel`](../../tfp/distributions/LinearGaussianStateSpaceModel.md)
+
+State space model for a seasonal effect.
+
+A state space model (SSM) posits a set of latent (unobserved) variables that
+evolve over time with dynamics specified by a probabilistic transition model
+`p(z[t+1] | z[t])`. At each timestep, we observe a value sampled from an
+observation model conditioned on the current state, `p(x[t] | z[t])`. The
+special case where both the transition and observation models are Gaussians
+with mean specified as a linear function of the inputs, is known as a linear
+Gaussian state space model and supports tractable exact probabilistic
+calculations; see
tfp.distributions.LinearGaussianStateSpaceModel for
+details.
+
+A seasonal effect model is a special case of a linear Gaussian SSM. The
+latent states represent an unknown effect from each of several 'seasons';
+these are generally not meteorological seasons, but represent regular
+recurring patterns such as hour-of-day or day-of-week effects. The effect of
+each season drifts from one occurrence to the next, following a Gaussian
+random walk:
+
+```python
+effects[season, occurrence[i]] = (
+ effects[season, occurrence[i-1]] + Normal(loc=0., scale=drift_scale))
+```
+
+The latent state has dimension `num_seasons`, containing one effect for each
+seasonal component. The parameters `drift_scale` and
+`observation_noise_scale` are each (a batch of) scalars. The batch shape of
+this `Distribution` is the broadcast batch shape of these parameters and of
+the `initial_state_prior`.
+
+#### Mathematical Details
+
+The seasonal effect model implements a
+
tfp.distributions.LinearGaussianStateSpaceModel with
+`latent_size = num_seasons` and `observation_size = 1`. The latent state
+is organized so that the *current* seasonal effect is always in the first
+(zeroth) dimension. The transition model rotates the latent state to shift
+to a new effect at the end of each season:
+
+```
+transition_matrix[t] = (permutation_matrix([1, 2, ..., num_seasons-1, 0])
+ if season_is_changing(t)
+ else eye(num_seasons)
+transition_noise[t] ~ Normal(loc=0., scale_diag=(
+ [drift_scale, 0, ..., 0]
+ if season_is_changing(t)
+ else [0, 0, ..., 0]))
+```
+
+where `season_is_changing(t)` is `True` if ``t `mod`
+sum(num_steps_per_season)`` is in the set of final days for each season,
+given by `cumsum(num_steps_per_season) - 1`. The observation model always
+picks out the effect for the current season, i.e., the first element of
+the latent state:
+
+```
+observation_matrix = [[1., 0., ..., 0.]]
+observation_noise ~ Normal(loc=0, scale=observation_noise_scale)
+```
+
+#### Examples
+
+A state-space model with day-of-week seasonality on hourly data:
+
+```python
+day_of_week = SeasonalStateSpaceModel(
+ num_timesteps=30,
+ num_seasons=7,
+ drift_scale=0.1,
+ initial_state_prior=tfd.MultivariateNormalDiag(
+ scale_diag=tf.ones([7], dtype=tf.float32),
+ num_steps_per_season=24)
+```
+
+A model with basic month-of-year seasonality on daily data, demonstrating
+seasons of varying length:
+
+```python
+month_of_year = SeasonalStateSpaceModel(
+ num_timesteps=2 * 365, # 2 years
+ num_seasons=12,
+ drift_scale=0.1,
+ initial_state_prior=tfd.MultivariateNormalDiag(
+ scale_diag=tf.ones([12], dtype=tf.float32)),
+ num_steps_per_season=[31, 28, 31, 30, 30, 31, 31, 31, 30, 31, 30, 31],
+ initial_step=22)
+```
+
+Note that we've used `initial_step=22` to denote that the model begins
+on January 23 (steps are zero-indexed). A general implementation of
+month-of-year seasonality would require additional logic; this
+version works over time periods not involving a leap year.
+
+
__init__
+
+``` python
+__init__(
+ num_timesteps,
+ num_seasons,
+ drift_scale,
+ initial_state_prior,
+ observation_noise_scale=0.0,
+ num_steps_per_season=1,
+ initial_step=0,
+ validate_args=False,
+ allow_nan_stats=True,
+ name=None
+)
+```
+
+Build a state space model implementing seasonal effects.
+
+#### Args:
+
+*
`num_timesteps`: Scalar `int` `Tensor` number of timesteps to model
+ with this distribution.
+*
`num_seasons`: Scalar Python `int` number of seasons.
+*
`drift_scale`: Scalar (any additional dimensions are treated as batch
+ dimensions) `float` `Tensor` indicating the standard deviation of the
+ change in effect between consecutive occurrences of a given season.
+ This is assumed to be the same for all seasons.
+*
`initial_state_prior`: instance of `tfd.MultivariateNormal`
+ representing the prior distribution on latent states; must
+ have event shape `[num_seasons]`.
+*
`observation_noise_scale`: Scalar (any additional dimensions are
+ treated as batch dimensions) `float` `Tensor` indicating the standard
+ deviation of the observation noise.
+ Default value: 0.
+*
`num_steps_per_season`: Python `int` number of steps in each
+ season. This may be either a scalar (shape `[]`), in which case all
+ seasons have the same length, or a NumPy array of shape `[num_seasons]`.
+ Default value: 1.
+*
`initial_step`: Optional scalar `int` `Tensor` specifying the starting
+ timestep.
+ Default value: 0.
+*
`validate_args`: Python `bool`. Whether to validate input
+ with asserts. If `validate_args` is `False`, and the inputs are
+ invalid, correct behavior is not guaranteed.
+ Default value: `False`.
+*
`allow_nan_stats`: Python `bool`. If `False`, raise an
+ exception if a statistic (e.g. mean/mode/etc...) is undefined for any
+ batch member. If `True`, batch members with valid parameters leading to
+ undefined statistics will return NaN for this statistic.
+ Default value: `True`.
+*
`name`: Python `str` name prefixed to ops created by this class.
+ Default value: "SeasonalStateSpaceModel".
+
+
+#### Raises:
+
+*
`ValueError`: if `num_steps_per_season` has invalid shape (neither
+ scalar nor `[num_seasons]`).
+
+
+
+## Properties
+
+
allow_nan_stats
+
+Python `bool` describing behavior when a stat is undefined.
+
+Stats return +/- infinity when it makes sense. E.g., the variance of a
+Cauchy distribution is infinity. However, sometimes the statistic is
+undefined, e.g., if a distribution's pdf does not achieve a maximum within
+the support of the distribution, the mode is undefined. If the mean is
+undefined, then by definition the variance is undefined. E.g. the mean for
+Student's T for df = 1 is undefined (no clear way to say it is either + or -
+infinity), so the variance = E[(X - mean)**2] is also undefined.
+
+#### Returns:
+
+*
`allow_nan_stats`: Python `bool`.
+
+
batch_shape
+
+Shape of a single sample from a single event index as a `TensorShape`.
+
+May be partially defined or unknown.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Returns:
+
+*
`batch_shape`: `TensorShape`, possibly unknown.
+
+
drift_scale
+
+Standard deviation of the drift in effects between seasonal cycles.
+
+
dtype
+
+The `DType` of `Tensor`s handled by this `Distribution`.
+
+
event_shape
+
+Shape of a single sample from a single batch as a `TensorShape`.
+
+May be partially defined or unknown.
+
+#### Returns:
+
+*
`event_shape`: `TensorShape`, possibly unknown.
+
+
name
+
+Name prepended to all ops created by this `Distribution`.
+
+
num_seasons
+
+Number of seasons.
+
+
num_steps_per_season
+
+Number of steps in each season.
+
+
observation_noise_scale
+
+Standard deviation of the observation noise.
+
+
parameters
+
+Dictionary of parameters used to instantiate this `Distribution`.
+
+
reparameterization_type
+
+Describes how samples from the distribution are reparameterized.
+
+Currently this is one of the static instances
+`distributions.FULLY_REPARAMETERIZED`
+or `distributions.NOT_REPARAMETERIZED`.
+
+#### Returns:
+
+An instance of `ReparameterizationType`.
+
+
validate_args
+
+Python `bool` indicating possibly expensive checks are enabled.
+
+
+
+## Methods
+
+
batch_shape_tensor
+
+``` python
+batch_shape_tensor(name='batch_shape_tensor')
+```
+
+Shape of a single sample from a single event index as a 1-D `Tensor`.
+
+The batch dimensions are indexes into independent, non-identical
+parameterizations of this distribution.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`batch_shape`: `Tensor`.
+
+
cdf
+
+``` python
+cdf(
+ value,
+ name='cdf'
+)
+```
+
+Cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+cdf(x) := P[X <= x]
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
copy
+
+``` python
+copy(**override_parameters_kwargs)
+```
+
+Creates a deep copy of the distribution.
+
+Note: the copy distribution may continue to depend on the original
+initialization arguments.
+
+#### Args:
+
+*
`**override_parameters_kwargs`: String/value dictionary of initialization
+ arguments to override with new values.
+
+
+#### Returns:
+
+*
`distribution`: A new instance of `type(self)` initialized from the union
+ of self.parameters and override_parameters_kwargs, i.e.,
+ `dict(self.parameters, **override_parameters_kwargs)`.
+
+
covariance
+
+``` python
+covariance(name='covariance')
+```
+
+Covariance.
+
+Covariance is (possibly) defined only for non-scalar-event distributions.
+
+For example, for a length-`k`, vector-valued distribution, it is calculated
+as,
+
+```none
+Cov[i, j] = Covariance(X_i, X_j) = E[(X_i - E[X_i]) (X_j - E[X_j])]
+```
+
+where `Cov` is a (batch of) `k x k` matrix, `0 <= (i, j) < k`, and `E`
+denotes expectation.
+
+Alternatively, for non-vector, multivariate distributions (e.g.,
+matrix-valued, Wishart), `Covariance` shall return a (batch of) matrices
+under some vectorization of the events, i.e.,
+
+```none
+Cov[i, j] = Covariance(Vec(X)_i, Vec(X)_j) = [as above]
+```
+
+where `Cov` is a (batch of) `k' x k'` matrices,
+`0 <= (i, j) < k' = reduce_prod(event_shape)`, and `Vec` is some function
+mapping indices of this distribution's event dimensions to indices of a
+length-`k'` vector.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`covariance`: Floating-point `Tensor` with shape `[B1, ..., Bn, k', k']`
+ where the first `n` dimensions are batch coordinates and
+ `k' = reduce_prod(self.event_shape)`.
+
+
cross_entropy
+
+``` python
+cross_entropy(
+ other,
+ name='cross_entropy'
+)
+```
+
+Computes the (Shannon) cross entropy.
+
+Denote this distribution (`self`) by `P` and the `other` distribution by
+`Q`. Assuming `P, Q` are absolutely continuous with respect to
+one another and permit densities `p(x) dr(x)` and `q(x) dr(x)`, (Shanon)
+cross entropy is defined as:
+
+```none
+H[P, Q] = E_p[-log q(X)] = -int_F p(x) log q(x) dr(x)
+```
+
+where `F` denotes the support of the random variable `X ~ P`.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`cross_entropy`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of (Shanon) cross entropy.
+
+
entropy
+
+``` python
+entropy(name='entropy')
+```
+
+Shannon entropy in nats.
+
+
event_shape_tensor
+
+``` python
+event_shape_tensor(name='event_shape_tensor')
+```
+
+Shape of a single sample from a single batch as a 1-D int32 `Tensor`.
+
+#### Args:
+
+*
`name`: name to give to the op
+
+
+#### Returns:
+
+*
`event_shape`: `Tensor`.
+
+
forward_filter
+
+``` python
+forward_filter(x)
+```
+
+Run a Kalman filter over a provided sequence of outputs.
+
+Note that the returned values `filtered_means`, `predicted_means`, and
+`observation_means` depend on the observed time series `x`, while the
+corresponding covariances are independent of the observed series; i.e., they
+depend only on the model itself. This means that the mean values have shape
+`concat([sample_shape(x), batch_shape, [num_timesteps,
+{latent/observation}_size]])`, while the covariances have shape
+`concat[(batch_shape, [num_timesteps, {latent/observation}_size,
+{latent/observation}_size]])`, which does not depend on the sample shape.
+
+#### Args:
+
+*
`x`: a float-type `Tensor` with rightmost dimensions
+ `[num_timesteps, observation_size]` matching
+ `self.event_shape`. Additional dimensions must match or be
+ broadcastable to `self.batch_shape`; any further dimensions
+ are interpreted as a sample shape.
+
+
+#### Returns:
+
+*
`log_likelihoods`: Per-timestep log marginal likelihoods `log
+ p(x_t | x_{:t-1})` evaluated at the input `x`, as a `Tensor`
+ of shape `sample_shape(x) + batch_shape + [num_timesteps].`
+*
`filtered_means`: Means of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `sample_shape(x) + batch_shape + [num_timesteps, latent_size]`.
+*
`filtered_covs`: Covariances of the per-timestep filtered marginal
+ distributions p(z_t | x_{:t}), as a Tensor of shape
+ `batch_shape + [num_timesteps, latent_size, latent_size]`.
+*
`predicted_means`: Means of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, latent_size]`.
+*
`predicted_covs`: Covariances of the per-timestep predictive
+ distributions over latent states, p(z_{t+1} | x_{:t}), as a
+ Tensor of shape `batch_shape + [num_timesteps, latent_size,
+ latent_size]`.
+*
`observation_means`: Means of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `sample_shape(x) + batch_shape +
+ [num_timesteps, observation_size]`.
+*
`observation_covs`: Covariances of the per-timestep predictive
+ distributions over observations, p(x_{t} | x_{:t-1}), as a
+ Tensor of shape `batch_shape + [num_timesteps,
+ observation_size, observation_size]`.
+
+
is_scalar_batch
+
+``` python
+is_scalar_batch(name='is_scalar_batch')
+```
+
+Indicates that `batch_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_batch`: `bool` scalar `Tensor`.
+
+
is_scalar_event
+
+``` python
+is_scalar_event(name='is_scalar_event')
+```
+
+Indicates that `event_shape == []`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`is_scalar_event`: `bool` scalar `Tensor`.
+
+
kl_divergence
+
+``` python
+kl_divergence(
+ other,
+ name='kl_divergence'
+)
+```
+
+Computes the Kullback--Leibler divergence.
+
+Denote this distribution (`self`) by `p` and the `other` distribution by
+`q`. Assuming `p, q` are absolutely continuous with respect to reference
+measure `r`, the KL divergence is defined as:
+
+```none
+KL[p, q] = E_p[log(p(X)/q(X))]
+ = -int_F p(x) log q(x) dr(x) + int_F p(x) log p(x) dr(x)
+ = H[p, q] - H[p]
+```
+
+where `F` denotes the support of the random variable `X ~ p`, `H[., .]`
+denotes (Shanon) cross entropy, and `H[.]` denotes (Shanon) entropy.
+
+#### Args:
+
+*
`other`:
tfp.distributions.Distribution instance.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`kl_divergence`: `self.dtype` `Tensor` with shape `[B1, ..., Bn]`
+ representing `n` different calculations of the Kullback-Leibler
+ divergence.
+
+
log_cdf
+
+``` python
+log_cdf(
+ value,
+ name='log_cdf'
+)
+```
+
+Log cumulative distribution function.
+
+Given random variable `X`, the cumulative distribution function `cdf` is:
+
+```none
+log_cdf(x) := Log[ P[X <= x] ]
+```
+
+Often, a numerical approximation can be used for `log_cdf(x)` that yields
+a more accurate answer than simply taking the logarithm of the `cdf` when
+`x << -1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`logcdf`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_prob
+
+``` python
+log_prob(
+ value,
+ name='log_prob'
+)
+```
+
+Log probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`log_prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
log_survival_function
+
+``` python
+log_survival_function(
+ value,
+ name='log_survival_function'
+)
+```
+
+Log survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+log_survival_function(x) = Log[ P[X > x] ]
+ = Log[ 1 - P[X <= x] ]
+ = Log[ 1 - cdf(x) ]
+```
+
+Typically, different numerical approximations can be used for the log
+survival function, which are more accurate than `1 - cdf(x)` when `x >> 1`.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
mean
+
+``` python
+mean(name='mean')
+```
+
+Mean.
+
+
mode
+
+``` python
+mode(name='mode')
+```
+
+Mode.
+
+
param_shapes
+
+``` python
+param_shapes(
+ cls,
+ sample_shape,
+ name='DistributionParamShapes'
+)
+```
+
+Shapes of parameters given the desired shape of a call to `sample()`.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`.
+
+Subclasses should override class method `_param_shapes`.
+
+#### Args:
+
+*
`sample_shape`: `Tensor` or python list/tuple. Desired shape of a call to
+ `sample()`.
+*
`name`: name to prepend ops with.
+
+
+#### Returns:
+
+`dict` of parameter name to `Tensor` shapes.
+
+
param_static_shapes
+
+``` python
+param_static_shapes(
+ cls,
+ sample_shape
+)
+```
+
+param_shapes with static (i.e. `TensorShape`) shapes.
+
+This is a class method that describes what key/value arguments are required
+to instantiate the given `Distribution` so that a particular shape is
+returned for that instance's call to `sample()`. Assumes that the sample's
+shape is known statically.
+
+Subclasses should override class method `_param_shapes` to return
+constant-valued tensors when constant values are fed.
+
+#### Args:
+
+*
`sample_shape`: `TensorShape` or python list/tuple. Desired shape of a call
+ to `sample()`.
+
+
+#### Returns:
+
+`dict` of parameter name to `TensorShape`.
+
+
+#### Raises:
+
+*
`ValueError`: if `sample_shape` is a `TensorShape` and is not fully defined.
+
+
prob
+
+``` python
+prob(
+ value,
+ name='prob'
+)
+```
+
+Probability density/mass function.
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`prob`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
quantile
+
+``` python
+quantile(
+ value,
+ name='quantile'
+)
+```
+
+Quantile function. Aka "inverse cdf" or "percent point function".
+
+Given random variable `X` and `p in [0, 1]`, the `quantile` is:
+
+```none
+quantile(p) := x such that P[X <= x] == p
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`quantile`: a `Tensor` of shape `sample_shape(x) + self.batch_shape` with
+ values of type `self.dtype`.
+
+
sample
+
+``` python
+sample(
+ sample_shape=(),
+ seed=None,
+ name='sample'
+)
+```
+
+Generate samples of the specified shape.
+
+Note that a call to `sample()` without arguments will generate a single
+sample.
+
+#### Args:
+
+*
`sample_shape`: 0D or 1D `int32` `Tensor`. Shape of the generated samples.
+*
`seed`: Python integer seed for RNG
+*
`name`: name to give to the op.
+
+
+#### Returns:
+
+*
`samples`: a `Tensor` with prepended dimensions `sample_shape`.
+
+
stddev
+
+``` python
+stddev(name='stddev')
+```
+
+Standard deviation.
+
+Standard deviation is defined as,
+
+```none
+stddev = E[(X - E[X])**2]**0.5
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `stddev.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`stddev`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
survival_function
+
+``` python
+survival_function(
+ value,
+ name='survival_function'
+)
+```
+
+Survival function.
+
+Given random variable `X`, the survival function is defined:
+
+```none
+survival_function(x) = P[X > x]
+ = 1 - P[X <= x]
+ = 1 - cdf(x).
+```
+
+#### Args:
+
+*
`value`: `float` or `double` `Tensor`.
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+`Tensor` of shape `sample_shape(x) + self.batch_shape` with values of type
+ `self.dtype`.
+
+
variance
+
+``` python
+variance(name='variance')
+```
+
+Variance.
+
+Variance is defined as,
+
+```none
+Var = E[(X - E[X])**2]
+```
+
+where `X` is the random variable associated with this distribution, `E`
+denotes expectation, and `Var.shape = batch_shape + event_shape`.
+
+#### Args:
+
+*
`name`: Python `str` prepended to names of ops created by this function.
+
+
+#### Returns:
+
+*
`variance`: Floating-point `Tensor` with shape identical to
+ `batch_shape + event_shape`, i.e., the same shape as `self.mean()`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/StructuralTimeSeries.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/StructuralTimeSeries.md
new file mode 100644
index 0000000000..92f1e61b90
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/StructuralTimeSeries.md
@@ -0,0 +1,203 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.StructuralTimeSeries
+
+## Class `StructuralTimeSeries`
+
+
+
+Base class for structural time series models.
+
+A StructuralTimeSeries object represents a declarative specification of a
+structural time series model, including priors on model parameters.
+It implements a joint probability model
+ `p(params, y) = p(params) p(y | params)`,
+where `params` denotes a list of real-valued parameters specified by the child
+class, and `p(y | params)` is a linear Gaussian state space model with
+structure determined by the child class.
+
+
__init__
+
+``` python
+__init__(
+ parameters,
+ latent_size,
+ name='StructuralTimeSeries'
+)
+```
+
+Construct a specification for a structural time series model.
+
+#### Args:
+
+*
`parameters`: list of Parameter namedtuples, each specifying the name
+ and prior distribution of a model parameter along with a
+ bijective transformation from an unconstrained space to the support
+ of that parameter. The order of this list determines the canonical
+ parameter ordering used by fitting and inference algorithms.
+*
`latent_size`: Python `int` specifying the dimensionality of the latent
+ state space for this model.
+*
`name`: Python `str` name for this model component.
+
+
+
+## Properties
+
+
batch_shape
+
+Static batch shape of models represented by this component.
+
+#### Returns:
+
+*
`batch_shape`: A `tf.TensorShape` 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`. It may be partially
+ defined or unknown.
+
+
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
+
+``` python
+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
+
+``` python
+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).
+
+
+#### 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
+
+``` python
+make_state_space_model(
+ num_timesteps,
+ param_vals=None,
+ 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
+
+``` python
+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 `Tensor`s, in order
+ corresponding to `self.parameters`, each of shape
+ `params_sample_shape + prior.batch_shape + prior.event_shape`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Sum.md b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Sum.md
new file mode 100644
index 0000000000..0f959874b2
--- /dev/null
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/sts/Sum.md
@@ -0,0 +1,263 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# tfp.sts.Sum
+
+## Class `Sum`
+
+Inherits From: [`StructuralTimeSeries`](../../tfp/sts/StructuralTimeSeries.md)
+
+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
+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`
+```
+
+
__init__
+
+``` python
+__init__(
+ components,
+ observation_noise_scale_prior=None,
+ observed_time_series=None,
+ name=None
+)
+```
+
+Specify a structural time series model representing a sum of components.
+
+#### Args:
+
+*
`components`: Python `list` of one or more StructuralTimeSeries instances.
+ These must have unique names.
+*
`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 only if `observation_noise_scale_prior` is not provided, to
+ construct a default heuristic prior.
+ 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.
+
+
+
+## Properties
+
+
batch_shape
+
+Static batch shape of models represented by this component.
+
+#### Returns:
+
+*
`batch_shape`: A `tf.TensorShape` 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`. It may be partially
+ defined or unknown.
+
+
components
+
+List of component `StructuralTimeSeries` models.
+
+
components_by_name
+
+OrderedDict mapping component names to components.
+
+
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
+
+``` python
+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
+
+``` python
+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).
+
+
+#### 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
+
+``` python
+make_state_space_model(
+ num_timesteps,
+ param_vals=None,
+ 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
+
+``` python
+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 `Tensor`s, in order
+ corresponding to `self.parameters`, each of shape
+ `params_sample_shape + prior.batch_shape + prior.event_shape`.
+
+
+
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions.md
index 64ed653059..d9ecebfb36 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions.md
@@ -1,5 +1,6 @@
+
@@ -10,7 +11,7 @@
Trainable distributions.
-"Trainable distributions" are instances of `tfp.distributions` which are
+"Trainable distributions" are instances of
tfp.distributions which are
parameterized by a transformation of a single input `Tensor`. The
transformations are presumed to use TensorFlow variables and typically need to
be fit, e.g., using `tf.train` optimizers or `tfp.optimizers`.
@@ -31,11 +32,11 @@ be fit, e.g., using `tf.train` optimizers or `tfp.optimizers`.
## Other Members
-`__all__`
+
__all__
-`absolute_import`
+
absolute_import
-`division`
+
division
-`print_function`
+
print_function
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/bernoulli.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/bernoulli.md
index 0a569cf9c6..022fe1bc18 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/bernoulli.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/bernoulli.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.bernoulli
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/multivariate_normal_tril.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/multivariate_normal_tril.md
index 6e033c41ee..8b6b90489e 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/multivariate_normal_tril.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/multivariate_normal_tril.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.multivariate_normal_tril
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/normal.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/normal.md
index 2ae2d9e814..074e2856e9 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/normal.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/normal.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.normal
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/poisson.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/poisson.md
index 762e353ba1..25815dd92f 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/poisson.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/poisson.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.poisson
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/softplus_and_shift.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/softplus_and_shift.md
index 3342660bf4..679a661fe0 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/softplus_and_shift.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/softplus_and_shift.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.softplus_and_shift
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/tril_with_diag_softplus_and_shift.md b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/tril_with_diag_softplus_and_shift.md
index 5da2399233..4f008d5bc9 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/tril_with_diag_softplus_and_shift.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/trainable_distributions/tril_with_diag_softplus_and_shift.md
@@ -1,5 +1,6 @@
+
# tfp.trainable_distributions.tril_with_diag_softplus_and_shift
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/util.md b/tensorflow_probability/g3doc/api_docs/python/tfp/util.md
index 101f3d5d8e..a68e7cd50b 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/util.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/util.md
@@ -1,5 +1,6 @@
+
# Module: tfp.util
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring.md b/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring.md
index a3cc623f15..1dfdff213d 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring.md
@@ -1,5 +1,6 @@
+
@@ -16,11 +17,11 @@ Utilities for programmable docstrings.
## Other Members
-`__all__`
+
__all__
-`absolute_import`
+
absolute_import
-`division`
+
division
-`print_function`
+
print_function
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring/expand_docstring.md b/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring/expand_docstring.md
index 9d300c0a2f..8cd96d2c38 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring/expand_docstring.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/util/docstring/expand_docstring.md
@@ -1,5 +1,6 @@
+
# tfp.util.docstring.expand_docstring
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/util/externalize_variables_as_args.md b/tensorflow_probability/g3doc/api_docs/python/tfp/util/externalize_variables_as_args.md
index 7c09f0f966..7aa17514e7 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/util/externalize_variables_as_args.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/util/externalize_variables_as_args.md
@@ -1,5 +1,6 @@
+
# tfp.util.externalize_variables_as_args
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi.md
index eb328f4743..6dc0312801 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi.md
@@ -1,5 +1,6 @@
+
# Module: tfp.vi
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/amari_alpha.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/amari_alpha.md
index 917918c91d..18699bd10c 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/amari_alpha.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/amari_alpha.md
@@ -1,5 +1,6 @@
+
# tfp.vi.amari_alpha
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/arithmetic_geometric.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/arithmetic_geometric.md
index d969c13333..e08a94a14c 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/arithmetic_geometric.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/arithmetic_geometric.md
@@ -1,5 +1,6 @@
+
# tfp.vi.arithmetic_geometric
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/chi_square.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/chi_square.md
index a1e84a44bd..12256c9d73 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/chi_square.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/chi_square.md
@@ -1,5 +1,6 @@
+
# tfp.vi.chi_square
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco.md
index c1ae923bd9..e291ab5d11 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco.md
@@ -1,5 +1,6 @@
+
# tfp.vi.csiszar_vimco
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco_helper.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco_helper.md
index 14b4cc44e0..2b5fdc0700 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco_helper.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/csiszar_vimco_helper.md
@@ -1,5 +1,6 @@
+
# tfp.vi.csiszar_vimco_helper
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/dual_csiszar_function.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/dual_csiszar_function.md
index 86f372262a..0ed8583297 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/dual_csiszar_function.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/dual_csiszar_function.md
@@ -1,5 +1,6 @@
+
# tfp.vi.dual_csiszar_function
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jeffreys.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jeffreys.md
index 74723b65a2..82a0bc5fb6 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jeffreys.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jeffreys.md
@@ -1,5 +1,6 @@
+
# tfp.vi.jeffreys
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jensen_shannon.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jensen_shannon.md
index ed242c569a..6c8a2dc7e8 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jensen_shannon.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/jensen_shannon.md
@@ -1,5 +1,6 @@
+
# tfp.vi.jensen_shannon
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_forward.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_forward.md
index 45451be136..f3c106fe96 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_forward.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_forward.md
@@ -1,5 +1,6 @@
+
# tfp.vi.kl_forward
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_reverse.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_reverse.md
index 4463b76485..01aaf69e44 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_reverse.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/kl_reverse.md
@@ -1,5 +1,6 @@
+
# tfp.vi.kl_reverse
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/log1p_abs.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/log1p_abs.md
index 34b7a4068e..a484634ead 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/log1p_abs.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/log1p_abs.md
@@ -1,5 +1,6 @@
+
# tfp.vi.log1p_abs
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/modified_gan.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/modified_gan.md
index 7285028456..ac913067c7 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/modified_gan.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/modified_gan.md
@@ -1,5 +1,6 @@
+
# tfp.vi.modified_gan
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/monte_carlo_csiszar_f_divergence.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/monte_carlo_csiszar_f_divergence.md
index ce238294ad..8ebf4eba72 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/monte_carlo_csiszar_f_divergence.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/monte_carlo_csiszar_f_divergence.md
@@ -1,5 +1,6 @@
+
# tfp.vi.monte_carlo_csiszar_f_divergence
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/pearson.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/pearson.md
index 69f8c7c018..f4ff4f1597 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/pearson.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/pearson.md
@@ -1,5 +1,6 @@
+
# tfp.vi.pearson
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/squared_hellinger.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/squared_hellinger.md
index 69ec1aae53..cf76784521 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/squared_hellinger.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/squared_hellinger.md
@@ -1,5 +1,6 @@
+
# tfp.vi.squared_hellinger
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/symmetrized_csiszar_function.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/symmetrized_csiszar_function.md
index bb3e526405..3c20909803 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/symmetrized_csiszar_function.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/symmetrized_csiszar_function.md
@@ -1,5 +1,6 @@
+
# tfp.vi.symmetrized_csiszar_function
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/t_power.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/t_power.md
index 87eec44095..21eea22279 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/t_power.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/t_power.md
@@ -1,5 +1,6 @@
+
# tfp.vi.t_power
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/total_variation.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/total_variation.md
index d9ece2cc03..91de746a3d 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/total_variation.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/total_variation.md
@@ -1,5 +1,6 @@
+
# tfp.vi.total_variation
diff --git a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/triangular.md b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/triangular.md
index c9ae23de43..f87289bf65 100644
--- a/tensorflow_probability/g3doc/api_docs/python/tfp/vi/triangular.md
+++ b/tensorflow_probability/g3doc/api_docs/python/tfp/vi/triangular.md
@@ -1,5 +1,6 @@
+
# tfp.vi.triangular