# Statistical distributions (contrib)
[TOC]
Classes representing statistical distributions and ops for working with them.
## Classes for statistical distributions.
Classes that represent batches of statistical distributions. Each class is
initialized with parameters that define the distributions.
### Base classes
- - -
### `class tf.contrib.distributions.BaseDistribution` {#BaseDistribution}
Abstract base class for probability distributions.
This class, along with `ContinuousDistribution` and `DiscreteDistribution`,
defines the API for probability distributions.
Users will never instantiate a `BaseDistribution`, but will instead
instantiate subclasses of either `ContinuousDistribution` or
`DiscreteDistribution`.
Developers of new distributions should prefer to subclass
`ContinuousDistribution` or `DiscreteDistribution`.
### API
The key methods for probability distributions are defined here. The likelihood
functions (`pdf`, `log_pdf`) and (`pmf`, `log_pmf`) are defined in
`ContinuousDistribution` and `DiscreteDistribution`, respectively.
To keep ops generated by the distribution tied together by name, subclasses
should override `name` and use it to preprend names of ops in other methods
(see `cdf` for an example).
Subclasses that wish to support `cdf` and `log_cdf` can override `log_cdf`
and use the base class's implementation for `cdf`.
### Broadcasting, batching, and shapes
All distributions support batches of independent distributions of that type.
The batch shape is determined by broadcasting together the parameters.
The shape of arguments to `__init__`, `cdf`, `log_cdf`, and the likelihood
functions defined in `ContinuousDistribution` and `DiscreteDistribution`
reflect this broadcasting, as does the return value of `sample`.
`sample_shape = (n,) + batch_shape + event_shape`, where `sample_shape` is the
shape of the `Tensor` returned from `sample`, `n` is the number of samples,
`batch_shape` defines how many independent distributions there are, and
`event_shape` defines the shape of samples from each of those independent
distributions. Samples are independent along the `batch_shape` dimensions,
but not necessarily so along the `event_shape` dimensions (dependending on
the particulars of the underlying distribution).
Using the `Uniform` distribution as an example:
```python
minval = 3.0
maxval = [[4.0, 6.0],
[10.0, 12.0]]
# Broadcasting:
# This instance represents 4 Uniform distributions. Each has a lower bound at
# 3.0 as the `minval` parameter was broadcasted to match `maxval`'s shape.
u = Uniform(minval, maxval)
# `event_shape` is `TensorShape([])`.
event_shape = u.get_event_shape()
# `event_shape_t` is a `Tensor` which will evaluate to [].
event_shape_t = u.event_shape
# Sampling returns a sample per distribution. `samples` has shape
# (5, 2, 2), which is (n,) + batch_shape + event_shape, where n=5,
# batch_shape=(2, 2), and event_shape=().
samples = u.sample(5)
# The broadcasting holds across methods. Here we use `cdf` as an example. The
# same holds for `log_cdf` and the likelihood functions.
# `cum_prob` has shape (2, 2) as the `value` argument was broadcasted to the
# shape of the `Uniform` instance.
cum_prob_broadcast = u.cdf(4.0)
# `cum_prob`'s shape is (2, 2), one per distribution. No broadcasting
# occurred.
cum_prob_per_dist = u.cdf([[4.0, 5.0],
[6.0, 7.0]])
# INVALID as the `value` argument is not broadcastable to the distribution's
# shape.
cum_prob_invalid = u.cdf([4.0, 5.0, 6.0])
```
- - -
#### `tf.contrib.distributions.BaseDistribution.batch_shape(name='batch_shape')` {#BaseDistribution.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.BaseDistribution.cdf(value, name='cdf')` {#BaseDistribution.cdf}
Cumulative distribution function.
- - -
#### `tf.contrib.distributions.BaseDistribution.dtype` {#BaseDistribution.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.BaseDistribution.entropy(name='entropy')` {#BaseDistribution.entropy}
Entropy of the distribution in nats.
- - -
#### `tf.contrib.distributions.BaseDistribution.event_shape(name='event_shape')` {#BaseDistribution.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.BaseDistribution.get_batch_shape()` {#BaseDistribution.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.BaseDistribution.get_event_shape()` {#BaseDistribution.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.BaseDistribution.log_cdf(value, name='log_cdf')` {#BaseDistribution.log_cdf}
Log CDF.
- - -
#### `tf.contrib.distributions.BaseDistribution.mean(name='mean')` {#BaseDistribution.mean}
Mean of the distribution.
- - -
#### `tf.contrib.distributions.BaseDistribution.mode(name='mode')` {#BaseDistribution.mode}
Mode of the distribution.
- - -
#### `tf.contrib.distributions.BaseDistribution.name` {#BaseDistribution.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.BaseDistribution.sample(n, seed=None, name='sample')` {#BaseDistribution.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.BaseDistribution.std(name='std')` {#BaseDistribution.std}
Standard deviation of the distribution.
- - -
#### `tf.contrib.distributions.BaseDistribution.variance(name='variance')` {#BaseDistribution.variance}
Variance of the distribution.
- - -
### `class tf.contrib.distributions.ContinuousDistribution` {#ContinuousDistribution}
Base class for continuous probability distributions.
`ContinuousDistribution` defines the API for the likelihood functions `pdf`
and `log_pdf` of continuous probability distributions, and a property
`is_reparameterized` (returning `True` or `False`) which describes
whether the samples of this distribution are calculated in a differentiable
way from a non-parameterized distribution. For example, the `Normal`
distribution with parameters `mu` and `sigma` is reparameterized as
```Normal(mu, sigma) = sigma * Normal(0, 1) + mu```
Subclasses must override `pdf` and `log_pdf` but one can call this base
class's implementation. They must also override the `is_reparameterized`
property.
See `BaseDistribution` for more information on the API for probability
distributions.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.batch_shape(name='batch_shape')` {#ContinuousDistribution.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.ContinuousDistribution.cdf(value, name='cdf')` {#ContinuousDistribution.cdf}
Cumulative distribution function.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.dtype` {#ContinuousDistribution.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.entropy(name='entropy')` {#ContinuousDistribution.entropy}
Entropy of the distribution in nats.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.event_shape(name='event_shape')` {#ContinuousDistribution.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.ContinuousDistribution.get_batch_shape()` {#ContinuousDistribution.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.get_event_shape()` {#ContinuousDistribution.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.is_reparameterized` {#ContinuousDistribution.is_reparameterized}
- - -
#### `tf.contrib.distributions.ContinuousDistribution.log_cdf(value, name='log_cdf')` {#ContinuousDistribution.log_cdf}
Log CDF.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.log_likelihood(value, name='log_likelihood')` {#ContinuousDistribution.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.ContinuousDistribution.log_pdf(value, name='log_pdf')` {#ContinuousDistribution.log_pdf}
Log of the probability density function.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.mean(name='mean')` {#ContinuousDistribution.mean}
Mean of the distribution.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.mode(name='mode')` {#ContinuousDistribution.mode}
Mode of the distribution.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.name` {#ContinuousDistribution.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.pdf(value, name='pdf')` {#ContinuousDistribution.pdf}
Probability density function.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.sample(n, seed=None, name='sample')` {#ContinuousDistribution.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.std(name='std')` {#ContinuousDistribution.std}
Standard deviation of the distribution.
- - -
#### `tf.contrib.distributions.ContinuousDistribution.variance(name='variance')` {#ContinuousDistribution.variance}
Variance of the distribution.
- - -
### `class tf.contrib.distributions.DiscreteDistribution` {#DiscreteDistribution}
Base class for discrete probability distributions.
`DiscreteDistribution` defines the API for the likelihood functions `pmf` and
`log_pmf` of discrete probability distributions.
Subclasses must override both `pmf` and `log_pmf` but one can call this base
class's implementation.
See `BaseDistribution` for more information on the API for probability
distributions.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.batch_shape(name='batch_shape')` {#DiscreteDistribution.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.DiscreteDistribution.cdf(value, name='cdf')` {#DiscreteDistribution.cdf}
Cumulative distribution function.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.dtype` {#DiscreteDistribution.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.entropy(name='entropy')` {#DiscreteDistribution.entropy}
Entropy of the distribution in nats.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.event_shape(name='event_shape')` {#DiscreteDistribution.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.DiscreteDistribution.get_batch_shape()` {#DiscreteDistribution.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.get_event_shape()` {#DiscreteDistribution.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.log_cdf(value, name='log_cdf')` {#DiscreteDistribution.log_cdf}
Log CDF.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.log_likelihood(value, name='log_likelihood')` {#DiscreteDistribution.log_likelihood}
Log likelihood of this distribution (same as log_pmf).
- - -
#### `tf.contrib.distributions.DiscreteDistribution.log_pmf(value, name='log_pmf')` {#DiscreteDistribution.log_pmf}
Log of the probability mass function.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.mean(name='mean')` {#DiscreteDistribution.mean}
Mean of the distribution.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.mode(name='mode')` {#DiscreteDistribution.mode}
Mode of the distribution.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.name` {#DiscreteDistribution.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.pmf(value, name='pmf')` {#DiscreteDistribution.pmf}
Probability mass function.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.sample(n, seed=None, name='sample')` {#DiscreteDistribution.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.std(name='std')` {#DiscreteDistribution.std}
Standard deviation of the distribution.
- - -
#### `tf.contrib.distributions.DiscreteDistribution.variance(name='variance')` {#DiscreteDistribution.variance}
Variance of the distribution.
### Univariate (scalar) distributions
- - -
### `class tf.contrib.distributions.Chi2` {#Chi2}
The Chi2 distribution with degrees of freedom df.
The PDF of this distribution is:
```pdf(x) = (x^(df/2 - 1)e^(-x/2))/(2^(k/2)Gamma(k/2)), x > 0```
Note that the Chi2 distribution is a special case of the Gamma distribution,
with Chi2(df) = Gamma(df/2, 1/2).
- - -
#### `tf.contrib.distributions.Chi2.__init__(df, name='Chi2')` {#Chi2.__init__}
- - -
#### `tf.contrib.distributions.Chi2.alpha` {#Chi2.alpha}
Shape parameter.
- - -
#### `tf.contrib.distributions.Chi2.batch_shape(name='batch_shape')` {#Chi2.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.Chi2.beta` {#Chi2.beta}
Inverse scale parameter.
- - -
#### `tf.contrib.distributions.Chi2.cdf(x, name='cdf')` {#Chi2.cdf}
CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `cdf`: tensor of dtype `dtype`, the CDFs of `x`.
- - -
#### `tf.contrib.distributions.Chi2.df` {#Chi2.df}
- - -
#### `tf.contrib.distributions.Chi2.dtype` {#Chi2.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.Chi2.entropy(name='entropy')` {#Chi2.entropy}
The entropy of Gamma distribution(s).
This is defined to be
```
entropy = alpha - log(beta) + log(Gamma(alpha))
+ (1-alpha)digamma(alpha)
```
where digamma(alpha) is the digamma function.
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.Chi2.event_shape(name='event_shape')` {#Chi2.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.Chi2.get_batch_shape()` {#Chi2.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Chi2.get_event_shape()` {#Chi2.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Chi2.is_reparameterized` {#Chi2.is_reparameterized}
- - -
#### `tf.contrib.distributions.Chi2.log_cdf(x, name='log_cdf')` {#Chi2.log_cdf}
Log CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_cdf`: tensor of dtype `dtype`, the log-CDFs of `x`.
- - -
#### `tf.contrib.distributions.Chi2.log_likelihood(value, name='log_likelihood')` {#Chi2.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.Chi2.log_pdf(x, name='log_pdf')` {#Chi2.log_pdf}
Log pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Chi2.mean(name='mean')` {#Chi2.mean}
Mean of each batch member.
- - -
#### `tf.contrib.distributions.Chi2.mode(name='mode')` {#Chi2.mode}
Mode of each batch member. Defined only if alpha >= 1.
- - -
#### `tf.contrib.distributions.Chi2.name` {#Chi2.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.Chi2.pdf(x, name='pdf')` {#Chi2.pdf}
Pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the PDFs of `x`
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Chi2.sample(n, seed=None, name='sample')` {#Chi2.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.Chi2.std(name='std')` {#Chi2.std}
Standard deviation of this distribution.
- - -
#### `tf.contrib.distributions.Chi2.variance(name='variance')` {#Chi2.variance}
Variance of each batch member.
- - -
### `class tf.contrib.distributions.Exponential` {#Exponential}
The Exponential distribution with rate parameter lam.
The PDF of this distribution is:
```pdf(x) = (lam * e^(-lam * x)), x > 0```
Note that the Exponential distribution is a special case of the Gamma
distribution, with Exponential(lam) = Gamma(1, lam).
- - -
#### `tf.contrib.distributions.Exponential.__init__(lam, name='Exponential')` {#Exponential.__init__}
- - -
#### `tf.contrib.distributions.Exponential.alpha` {#Exponential.alpha}
Shape parameter.
- - -
#### `tf.contrib.distributions.Exponential.batch_shape(name='batch_shape')` {#Exponential.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.Exponential.beta` {#Exponential.beta}
Inverse scale parameter.
- - -
#### `tf.contrib.distributions.Exponential.cdf(x, name='cdf')` {#Exponential.cdf}
CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `cdf`: tensor of dtype `dtype`, the CDFs of `x`.
- - -
#### `tf.contrib.distributions.Exponential.dtype` {#Exponential.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.Exponential.entropy(name='entropy')` {#Exponential.entropy}
The entropy of Gamma distribution(s).
This is defined to be
```
entropy = alpha - log(beta) + log(Gamma(alpha))
+ (1-alpha)digamma(alpha)
```
where digamma(alpha) is the digamma function.
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.Exponential.event_shape(name='event_shape')` {#Exponential.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.Exponential.get_batch_shape()` {#Exponential.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Exponential.get_event_shape()` {#Exponential.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Exponential.is_reparameterized` {#Exponential.is_reparameterized}
- - -
#### `tf.contrib.distributions.Exponential.lam` {#Exponential.lam}
- - -
#### `tf.contrib.distributions.Exponential.log_cdf(x, name='log_cdf')` {#Exponential.log_cdf}
Log CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_cdf`: tensor of dtype `dtype`, the log-CDFs of `x`.
- - -
#### `tf.contrib.distributions.Exponential.log_likelihood(value, name='log_likelihood')` {#Exponential.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.Exponential.log_pdf(x, name='log_pdf')` {#Exponential.log_pdf}
Log pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Exponential.mean(name='mean')` {#Exponential.mean}
Mean of each batch member.
- - -
#### `tf.contrib.distributions.Exponential.mode(name='mode')` {#Exponential.mode}
Mode of each batch member. Defined only if alpha >= 1.
- - -
#### `tf.contrib.distributions.Exponential.name` {#Exponential.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.Exponential.pdf(x, name='pdf')` {#Exponential.pdf}
Pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the PDFs of `x`
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Exponential.sample(n, seed=None, name=None)` {#Exponential.sample}
Sample `n` observations from the Exponential Distributions.
##### Args:
* `n`: `Scalar`, type int32, the number of observations to sample.
* `seed`: Python integer, the random seed.
* `name`: The name to give this op.
##### Returns:
* `samples`: `[n, ...]`, a `Tensor` of `n` samples for each
of the distributions determined by the hyperparameters.
- - -
#### `tf.contrib.distributions.Exponential.std(name='std')` {#Exponential.std}
Standard deviation of this distribution.
- - -
#### `tf.contrib.distributions.Exponential.variance(name='variance')` {#Exponential.variance}
Variance of each batch member.
- - -
### `class tf.contrib.distributions.Gamma` {#Gamma}
The `Gamma` distribution with parameter alpha and beta.
The parameters are the shape and inverse scale parameters alpha, beta.
The PDF of this distribution is:
```pdf(x) = (beta^alpha)(x^(alpha-1))e^(-x*beta)/Gamma(alpha), x > 0```
and the CDF of this distribution is:
```cdf(x) = GammaInc(alpha, beta * x) / Gamma(alpha), x > 0```
where GammaInc is the incomplete lower Gamma function.
Examples:
```python
dist = Gamma(alpha=3.0, beta=2.0)
dist2 = Gamma(alpha=[3.0, 4.0], beta=[2.0, 3.0])
```
- - -
#### `tf.contrib.distributions.Gamma.__init__(alpha, beta, name='Gamma')` {#Gamma.__init__}
Construct Gamma distributions with parameters `alpha` and `beta`.
The parameters `alpha` and `beta` must be shaped in a way that supports
broadcasting (e.g. `alpha + beta` is a valid operation).
##### Args:
* `alpha`: `float` or `double` tensor, the shape params of the
distribution(s).
alpha must contain only positive values.
* `beta`: `float` or `double` tensor, the inverse scale params of the
distribution(s).
beta must contain only positive values.
* `name`: The name to prepend to all ops created by this distribution.
##### Raises:
* `TypeError`: if `alpha` and `beta` are different dtypes.
- - -
#### `tf.contrib.distributions.Gamma.alpha` {#Gamma.alpha}
Shape parameter.
- - -
#### `tf.contrib.distributions.Gamma.batch_shape(name='batch_shape')` {#Gamma.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.Gamma.beta` {#Gamma.beta}
Inverse scale parameter.
- - -
#### `tf.contrib.distributions.Gamma.cdf(x, name='cdf')` {#Gamma.cdf}
CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `cdf`: tensor of dtype `dtype`, the CDFs of `x`.
- - -
#### `tf.contrib.distributions.Gamma.dtype` {#Gamma.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.Gamma.entropy(name='entropy')` {#Gamma.entropy}
The entropy of Gamma distribution(s).
This is defined to be
```
entropy = alpha - log(beta) + log(Gamma(alpha))
+ (1-alpha)digamma(alpha)
```
where digamma(alpha) is the digamma function.
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.Gamma.event_shape(name='event_shape')` {#Gamma.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.Gamma.get_batch_shape()` {#Gamma.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Gamma.get_event_shape()` {#Gamma.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
##### Returns:
`TensorShape` object.
- - -
#### `tf.contrib.distributions.Gamma.is_reparameterized` {#Gamma.is_reparameterized}
- - -
#### `tf.contrib.distributions.Gamma.log_cdf(x, name='log_cdf')` {#Gamma.log_cdf}
Log CDF of observations `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_cdf`: tensor of dtype `dtype`, the log-CDFs of `x`.
- - -
#### `tf.contrib.distributions.Gamma.log_likelihood(value, name='log_likelihood')` {#Gamma.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.Gamma.log_pdf(x, name='log_pdf')` {#Gamma.log_pdf}
Log pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Gamma.mean(name='mean')` {#Gamma.mean}
Mean of each batch member.
- - -
#### `tf.contrib.distributions.Gamma.mode(name='mode')` {#Gamma.mode}
Mode of each batch member. Defined only if alpha >= 1.
- - -
#### `tf.contrib.distributions.Gamma.name` {#Gamma.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.Gamma.pdf(x, name='pdf')` {#Gamma.pdf}
Pdf of observations in `x` under these Gamma distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `alpha` and `beta`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the PDFs of `x`
##### Raises:
* `TypeError`: if `x` and `alpha` are different dtypes.
- - -
#### `tf.contrib.distributions.Gamma.sample(n, seed=None, name='sample')` {#Gamma.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.Gamma.std(name='std')` {#Gamma.std}
Standard deviation of this distribution.
- - -
#### `tf.contrib.distributions.Gamma.variance(name='variance')` {#Gamma.variance}
Variance of each batch member.
- - -
### `class tf.contrib.distributions.Normal` {#Normal}
The scalar Normal distribution with mean and stddev parameters mu, sigma.
#### Mathematical details
The PDF of this distribution is:
```f(x) = sqrt(1/(2*pi*sigma^2)) exp(-(x-mu)^2/(2*sigma^2))```
#### Examples
Examples of initialization of one or a batch of distributions.
```python
# Define a single scalar Normal distribution.
dist = tf.contrib.distributions.Normal(mu=0, sigma=3)
# Evaluate the cdf at 1, returning a scalar.
dist.cdf(1)
# Define a batch of two scalar valued Normals.
# The first has mean 1 and standard deviation 11, the second 2 and 22.
dist = tf.contrib.distributions.Normal(mu=[1, 2.], sigma=[11, 22.])
# Evaluate the pdf of the first distribution on 0, and the second on 1.5,
# returning a length two tensor.
dist.pdf([0, 1.5])
# Get 3 samples, returning a 3 x 2 tensor.
dist.sample(3)
```
Arguments are broadcast when possible.
```python
# Define a batch of two scalar valued Normals.
# Both have mean 1, but different standard deviations.
dist = tf.contrib.distributions.Normal(mu=1, sigma=[11, 22.])
# Evaluate the pdf of both distributions on the same point, 3.0,
# returning a length 2 tensor.
dist.pdf(3.0)
```
- - -
#### `tf.contrib.distributions.Normal.__init__(mu, sigma, name='Normal')` {#Normal.__init__}
Construct Normal distributions with mean and stddev `mu` and `sigma`.
The parameters `mu` and `sigma` must be shaped in a way that supports
broadcasting (e.g. `mu + sigma` is a valid operation).
##### Args:
* `mu`: `float` or `double` tensor, the means of the distribution(s).
* `sigma`: `float` or `double` tensor, the stddevs of the distribution(s).
sigma must contain only positive values.
* `name`: The name to give Ops created by the initializer.
##### Raises:
* `TypeError`: if mu and sigma are different dtypes.
- - -
#### `tf.contrib.distributions.Normal.batch_shape(name='batch_shape')` {#Normal.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op.
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.Normal.cdf(x, name='cdf')` {#Normal.cdf}
CDF of observations in `x` under these Normal distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `sigma`.
* `name`: The name to give this op.
##### Returns:
* `cdf`: tensor of dtype `dtype`, the CDFs of `x`.
- - -
#### `tf.contrib.distributions.Normal.dtype` {#Normal.dtype}
- - -
#### `tf.contrib.distributions.Normal.entropy(name='entropy')` {#Normal.entropy}
The entropy of Normal distribution(s).
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.Normal.event_shape(name='event_shape')` {#Normal.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op.
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.Normal.get_batch_shape()` {#Normal.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
##### Returns:
batch shape
- - -
#### `tf.contrib.distributions.Normal.get_event_shape()` {#Normal.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
##### Returns:
event shape
- - -
#### `tf.contrib.distributions.Normal.is_reparameterized` {#Normal.is_reparameterized}
- - -
#### `tf.contrib.distributions.Normal.log_cdf(x, name='log_cdf')` {#Normal.log_cdf}
Log CDF of observations `x` under these Normal distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `sigma`.
* `name`: The name to give this op.
##### Returns:
* `log_cdf`: tensor of dtype `dtype`, the log-CDFs of `x`.
- - -
#### `tf.contrib.distributions.Normal.log_likelihood(value, name='log_likelihood')` {#Normal.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.Normal.log_pdf(x, name='log_pdf')` {#Normal.log_pdf}
Log pdf of observations in `x` under these Normal distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `sigma`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
- - -
#### `tf.contrib.distributions.Normal.mean(name='mean')` {#Normal.mean}
Mean of this distribution.
- - -
#### `tf.contrib.distributions.Normal.mode(name='mode')` {#Normal.mode}
Mode of this distribution.
- - -
#### `tf.contrib.distributions.Normal.mu` {#Normal.mu}
Distribution parameter for the mean.
- - -
#### `tf.contrib.distributions.Normal.name` {#Normal.name}
- - -
#### `tf.contrib.distributions.Normal.pdf(x, name='pdf')` {#Normal.pdf}
The PDF of observations in `x` under these Normal distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `sigma`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the pdf values of `x`.
- - -
#### `tf.contrib.distributions.Normal.sample(n, seed=None, name='sample')` {#Normal.sample}
Sample `n` observations from the Normal Distributions.
##### Args:
* `n`: `Scalar`, type int32, the number of observations to sample.
* `seed`: Python integer, the random seed.
* `name`: The name to give this op.
##### Returns:
* `samples`: `[n, ...]`, a `Tensor` of `n` samples for each
of the distributions determined by broadcasting the hyperparameters.
- - -
#### `tf.contrib.distributions.Normal.sigma` {#Normal.sigma}
Distribution parameter for standard deviation.
- - -
#### `tf.contrib.distributions.Normal.std(name='std')` {#Normal.std}
Standard deviation of this distribution.
- - -
#### `tf.contrib.distributions.Normal.variance(name='variance')` {#Normal.variance}
Variance of this distribution.
- - -
### `class tf.contrib.distributions.StudentT` {#StudentT}
Student's t distribution with degree-of-freedom parameter df.
#### Mathematical details
The PDF of this distribution is:
`f(t) = gamma((df+1)/2)/sqrt(df*pi)/gamma(df/2)*(1+t^2/df)^(-(df+1)/2)`
#### Examples
Examples of initialization of one or a batch of distributions.
```python
# Define a single scalar Student t distribution.
single_dist = tf.contrib.distributions.StudentT(df=3)
# Evaluate the pdf at 1, returning a scalar Tensor.
single_dist.pdf(1.)
# Define a batch of two scalar valued Student t's.
# The first has degrees of freedom 2, mean 1, and scale 11.
# The second 3, 2 and 22.
multi_dist = tf.contrib.distributions.StudentT(df=[2, 3],
mu=[1, 2.],
sigma=[11, 22.])
# Evaluate the pdf of the first distribution on 0, and the second on 1.5,
# returning a length two tensor.
multi_dist.pdf([0, 1.5])
# Get 3 samples, returning a 3 x 2 tensor.
multi_dist.sample(3)
```
Arguments are broadcast when possible.
```python
# Define a batch of two Student's t distributions.
# Both have df 2 and mean 1, but different scales.
dist = tf.contrib.distributions.StudentT(df=2, mu=1, sigma=[11, 22.])
# Evaluate the pdf of both distributions on the same point, 3.0,
# returning a length 2 tensor.
dist.pdf(3.0)
```
- - -
#### `tf.contrib.distributions.StudentT.__init__(df, mu, sigma, name='StudentT')` {#StudentT.__init__}
Construct Student's t distributions.
The distributions have degree of freedom `df`, mean `mu`, and scale `sigma`.
The parameters `df`, `mu`, and `sigma` must be shaped in a way that supports
broadcasting (e.g. `df + mu + sigma` is a valid operation).
##### Args:
* `df`: `float` or `double` tensor, the degrees of freedom of the
distribution(s). `df` must contain only positive values.
* `mu`: `float` or `double` tensor, the means of the distribution(s).
* `sigma`: `float` or `double` tensor, the scaling factor for the
distribution(s). `sigma` must contain only positive values.
Note that `sigma` is not the standard deviation of this distribution.
* `name`: The name to give Ops created by the initializer.
##### Raises:
* `TypeError`: if mu and sigma are different dtypes.
- - -
#### `tf.contrib.distributions.StudentT.batch_shape(name='batch_shape')` {#StudentT.batch_shape}
- - -
#### `tf.contrib.distributions.StudentT.cdf(value, name='cdf')` {#StudentT.cdf}
Cumulative distribution function.
- - -
#### `tf.contrib.distributions.StudentT.df` {#StudentT.df}
Degrees of freedom in these Student's t distribution(s).
- - -
#### `tf.contrib.distributions.StudentT.dtype` {#StudentT.dtype}
- - -
#### `tf.contrib.distributions.StudentT.entropy(name='entropy')` {#StudentT.entropy}
The entropy of Student t distribution(s).
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.StudentT.event_shape(name='event_shape')` {#StudentT.event_shape}
- - -
#### `tf.contrib.distributions.StudentT.get_batch_shape()` {#StudentT.get_batch_shape}
- - -
#### `tf.contrib.distributions.StudentT.get_event_shape()` {#StudentT.get_event_shape}
- - -
#### `tf.contrib.distributions.StudentT.is_reparameterized` {#StudentT.is_reparameterized}
- - -
#### `tf.contrib.distributions.StudentT.log_cdf(value, name='log_cdf')` {#StudentT.log_cdf}
Log CDF.
- - -
#### `tf.contrib.distributions.StudentT.log_likelihood(value, name='log_likelihood')` {#StudentT.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.StudentT.log_pdf(x, name='log_pdf')` {#StudentT.log_pdf}
Log pdf of observations in `x` under these Student's t-distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `df`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
- - -
#### `tf.contrib.distributions.StudentT.mean(name='mean')` {#StudentT.mean}
- - -
#### `tf.contrib.distributions.StudentT.mode(name='mode')` {#StudentT.mode}
- - -
#### `tf.contrib.distributions.StudentT.mu` {#StudentT.mu}
Locations of these Student's t distribution(s).
- - -
#### `tf.contrib.distributions.StudentT.name` {#StudentT.name}
- - -
#### `tf.contrib.distributions.StudentT.pdf(x, name='pdf')` {#StudentT.pdf}
The PDF of observations in `x` under these Student's t distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `df`, `mu`, and
`sigma`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the pdf values of `x`.
- - -
#### `tf.contrib.distributions.StudentT.sample(n, seed=None, name='sample')` {#StudentT.sample}
Sample `n` observations from the Student t Distributions.
##### Args:
* `n`: `Scalar`, type int32, the number of observations to sample.
* `seed`: Python integer, the random seed.
* `name`: The name to give this op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.StudentT.sigma` {#StudentT.sigma}
Scaling factors of these Student's t distribution(s).
- - -
#### `tf.contrib.distributions.StudentT.std(name='std')` {#StudentT.std}
- - -
#### `tf.contrib.distributions.StudentT.variance(name='variance')` {#StudentT.variance}
- - -
### `class tf.contrib.distributions.Uniform` {#Uniform}
Uniform distribution with `a` and `b` parameters.
The PDF of this distribution is constant between [`a`, `b`], and 0 elsewhere.
- - -
#### `tf.contrib.distributions.Uniform.__init__(a=0.0, b=1.0, name='Uniform')` {#Uniform.__init__}
Construct Uniform distributions with `a` and `b`.
The parameters `a` and `b` must be shaped in a way that supports
broadcasting (e.g. `b - a` is a valid operation).
Here are examples without broadcasting:
```python
# Without broadcasting
u1 = Uniform(3.0, 4.0) # a single uniform distribution [3, 4]
u2 = Uniform([1.0, 2.0], [3.0, 4.0]) # 2 distributions [1, 3], [2, 4]
u3 = Uniform([[1.0, 2.0],
[3.0, 4.0]],
[[1.5, 2.5],
[3.5, 4.5]]) # 4 distributions
```
And with broadcasting:
```python
u1 = Uniform(3.0, [5.0, 6.0, 7.0]) # 3 distributions
```
##### Args:
* `a`: `float` or `double` tensor, the minimum endpoint.
* `b`: `float` or `double` tensor, the maximum endpoint. Must be > `a`.
* `name`: The name to prefix Ops created by this distribution class.
##### Raises:
* `InvalidArgumentError`: if `a >= b`.
- - -
#### `tf.contrib.distributions.Uniform.a` {#Uniform.a}
- - -
#### `tf.contrib.distributions.Uniform.b` {#Uniform.b}
- - -
#### `tf.contrib.distributions.Uniform.batch_shape(name='batch_shape')` {#Uniform.batch_shape}
- - -
#### `tf.contrib.distributions.Uniform.cdf(x, name='cdf')` {#Uniform.cdf}
CDF of observations in `x` under these Uniform distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `a` and `b`.
* `name`: The name to give this op.
##### Returns:
* `cdf`: tensor of dtype `dtype`, the CDFs of `x`. If `x` is `nan`, will
return `nan`.
- - -
#### `tf.contrib.distributions.Uniform.dtype` {#Uniform.dtype}
- - -
#### `tf.contrib.distributions.Uniform.entropy(name='entropy')` {#Uniform.entropy}
The entropy of Uniform distribution(s).
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropy.
- - -
#### `tf.contrib.distributions.Uniform.event_shape(name='event_shape')` {#Uniform.event_shape}
- - -
#### `tf.contrib.distributions.Uniform.get_batch_shape()` {#Uniform.get_batch_shape}
- - -
#### `tf.contrib.distributions.Uniform.get_event_shape()` {#Uniform.get_event_shape}
- - -
#### `tf.contrib.distributions.Uniform.is_reparameterized` {#Uniform.is_reparameterized}
- - -
#### `tf.contrib.distributions.Uniform.log_cdf(x, name='log_cdf')` {#Uniform.log_cdf}
- - -
#### `tf.contrib.distributions.Uniform.log_likelihood(value, name='log_likelihood')` {#Uniform.log_likelihood}
Log likelihood of this distribution (same as log_pdf).
- - -
#### `tf.contrib.distributions.Uniform.log_pdf(x, name='log_pdf')` {#Uniform.log_pdf}
- - -
#### `tf.contrib.distributions.Uniform.mean(name='mean')` {#Uniform.mean}
- - -
#### `tf.contrib.distributions.Uniform.mode(name='mode')` {#Uniform.mode}
Mode of the distribution.
- - -
#### `tf.contrib.distributions.Uniform.name` {#Uniform.name}
- - -
#### `tf.contrib.distributions.Uniform.pdf(x, name='pdf')` {#Uniform.pdf}
The PDF of observations in `x` under these Uniform distribution(s).
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `a` and `b`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the pdf values of `x`. If `x` is `nan`, will
return `nan`.
- - -
#### `tf.contrib.distributions.Uniform.range(name='range')` {#Uniform.range}
`b - a`.
- - -
#### `tf.contrib.distributions.Uniform.sample(n, seed=None, name='sample')` {#Uniform.sample}
Sample `n` observations from the Uniform Distributions.
##### Args:
* `n`: `Scalar`, type int32, the number of observations to sample.
* `seed`: Python integer, the random seed.
* `name`: The name to give this op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.Uniform.std(name='std')` {#Uniform.std}
- - -
#### `tf.contrib.distributions.Uniform.variance(name='variance')` {#Uniform.variance}
### Multivariate distributions
- - -
### `class tf.contrib.distributions.MultivariateNormal` {#MultivariateNormal}
The Multivariate Normal distribution on `R^k`.
The distribution has mean and covariance parameters mu (1-D), sigma (2-D),
or alternatively mean `mu` and factored covariance (cholesky decomposed
`sigma`) called `sigma_chol`.
#### Mathematical details
The PDF of this distribution is:
```
f(x) = (2*pi)^(-k/2) |det(sigma)|^(-1/2) exp(-1/2*(x-mu)^*.sigma^{-1}.(x-mu))
```
where `.` denotes the inner product on `R^k` and `^*` denotes transpose.
Alternatively, if `sigma` is positive definite, it can be represented in terms
of its lower triangular cholesky factorization
```sigma = sigma_chol . sigma_chol^*```
and the pdf above allows simpler computation:
```
|det(sigma)| = reduce_prod(diag(sigma_chol))^2
x_whitened = sigma^{-1/2} . (x - mu) = tri_solve(sigma_chol, x - mu)
(x-mu)^* .sigma^{-1} . (x-mu) = x_whitened^* . x_whitened
```
where `tri_solve()` solves a triangular system of equations.
#### Examples
A single multi-variate Gaussian distribution is defined by a vector of means
of length `k`, and a covariance matrix of shape `k x k`.
Extra leading dimensions, if provided, allow for batches.
```python
# Initialize a single 3-variate Gaussian with diagonal covariance.
mu = [1, 2, 3]
sigma = [[1, 0, 0], [0, 3, 0], [0, 0, 2]]
dist = tf.contrib.distributions.MultivariateNormal(mu=mu, sigma=sigma)
# Evaluate this on an observation in R^3, returning a scalar.
dist.pdf([-1, 0, 1])
# Initialize a batch of two 3-variate Gaussians.
mu = [[1, 2, 3], [11, 22, 33]]
sigma = ... # shape 2 x 3 x 3
dist = tf.contrib.distributions.MultivariateNormal(mu=mu, sigma=sigma)
# Evaluate this on a two observations, each in R^3, returning a length two
# tensor.
x = [[-1, 0, 1], [-11, 0, 11]] # Shape 2 x 3.
dist.pdf(x)
```
- - -
#### `tf.contrib.distributions.MultivariateNormal.__init__(mu, sigma=None, sigma_chol=None, name=None)` {#MultivariateNormal.__init__}
Multivariate Normal distributions on `R^k`.
User must provide means `mu`, which are tensors of rank `N+1` (`N >= 0`)
with the last dimension having length `k`.
User must provide exactly one of `sigma` (the covariance matrices) or
`sigma_chol` (the cholesky decompositions of the covariance matrices).
`sigma` or `sigma_chol` must be of rank `N+2`. The last two dimensions
must both have length `k`. The first `N` dimensions correspond to batch
indices.
If `sigma_chol` is not provided, the batch cholesky factorization of `sigma`
is calculated for you.
The shapes of `mu` and `sigma` must match for the first `N` dimensions.
Regardless of which parameter is provided, the covariance matrices must all
be **positive definite** (an error is raised if one of them is not).
##### Args:
* `mu`: (N+1)-D. `float` or `double` tensor, the means of the distributions.
* `sigma`: (N+2)-D. (optional) `float` or `double` tensor, the covariances
of the distribution(s). The first `N+1` dimensions must match
those of `mu`. Must be batch-positive-definite.
* `sigma_chol`: (N+2)-D. (optional) `float` or `double` tensor, a
lower-triangular factorization of `sigma`
(`sigma = sigma_chol . sigma_chol^*`). The first `N+1` dimensions
must match those of `mu`. The tensor itself need not be batch
lower triangular: we ignore the upper triangular part. However,
the batch diagonals must be positive (i.e., sigma_chol must be
batch-positive-definite).
* `name`: The name to give Ops created by the initializer.
##### Raises:
* `ValueError`: if neither sigma nor sigma_chol is provided.
* `TypeError`: if mu and sigma (resp. sigma_chol) are different dtypes.
- - -
#### `tf.contrib.distributions.MultivariateNormal.dtype` {#MultivariateNormal.dtype}
- - -
#### `tf.contrib.distributions.MultivariateNormal.entropy(name=None)` {#MultivariateNormal.entropy}
The entropies of these Multivariate Normals.
##### Args:
* `name`: The name to give this op.
##### Returns:
* `entropy`: tensor of dtype `dtype`, the entropies.
- - -
#### `tf.contrib.distributions.MultivariateNormal.is_reparameterized` {#MultivariateNormal.is_reparameterized}
- - -
#### `tf.contrib.distributions.MultivariateNormal.log_pdf(x, name=None)` {#MultivariateNormal.log_pdf}
Log pdf of observations `x` given these Multivariate Normals.
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu`.
* `name`: The name to give this op.
##### Returns:
* `log_pdf`: tensor of dtype `dtype`, the log-PDFs of `x`.
- - -
#### `tf.contrib.distributions.MultivariateNormal.mean` {#MultivariateNormal.mean}
- - -
#### `tf.contrib.distributions.MultivariateNormal.mu` {#MultivariateNormal.mu}
- - -
#### `tf.contrib.distributions.MultivariateNormal.pdf(x, name=None)` {#MultivariateNormal.pdf}
The PDF of observations `x` under these Multivariate Normals.
##### Args:
* `x`: tensor of dtype `dtype`, must be broadcastable with `mu` and `sigma`.
* `name`: The name to give this op.
##### Returns:
* `pdf`: tensor of dtype `dtype`, the pdf values of `x`.
- - -
#### `tf.contrib.distributions.MultivariateNormal.sample(n, seed=None, name=None)` {#MultivariateNormal.sample}
Sample `n` observations from the Multivariate Normal Distributions.
##### Args:
* `n`: `Scalar`, type int32, the number of observations to sample.
* `seed`: Python integer, the random seed.
* `name`: The name to give this op.
##### Returns:
* `samples`: `[n, ...]`, a `Tensor` of `n` samples for each
of the distributions determined by broadcasting the hyperparameters.
- - -
#### `tf.contrib.distributions.MultivariateNormal.sigma` {#MultivariateNormal.sigma}
- - -
#### `tf.contrib.distributions.MultivariateNormal.sigma_det` {#MultivariateNormal.sigma_det}
- - -
### `class tf.contrib.distributions.DirichletMultinomial` {#DirichletMultinomial}
DirichletMultinomial mixture distribution.
This distribution is parameterized by a vector `alpha` of concentration
parameters for `k` classes and `n`, the counts per each class..
#### Mathematical details
The Dirichlet Multinomial is a distribution over k-class count data, meaning
for each k-tuple of non-negative integer `counts = [c_1,...,c_k]`, we have a
probability of these draws being made from the distribution. The distribution
has hyperparameters `alpha = (alpha_1,...,alpha_k)`, and probability mass
function (pmf):
```pmf(counts) = N! / (n_1!...n_k!) * Beta(alpha + c) / Beta(alpha)```
where above `N = sum_j n_j`, `N!` is `N` factorial, and
`Beta(x) = prod_j Gamma(x_j) / Gamma(sum_j x_j)` is the multivariate beta
function.
This is a mixture distribution in that `M` samples can be produced by:
1. Choose class probabilities `p = (p_1,...,p_k) ~ Dir(alpha)`
2. Draw integers `m = (n_1,...,n_k) ~ Multinomial(N, p)`
This class provides methods to create indexed batches of Dirichlet
Multinomial distributions. If the provided `alpha` is rank 2 or higher, for
every fixed set of leading dimensions, the last dimension represents one
single Dirichlet Multinomial distribution. When calling distribution
functions (e.g. `dist.pmf(counts)`), `alpha` and `counts` are broadcast to the
same shape (if possible). In all cases, the last dimension of alpha/counts
represents single Dirichlet Multinomial distributions.
#### Examples
```python
alpha = [1, 2, 3]
n = 2
dist = DirichletMultinomial(n, alpha)
```
Creates a 3-class distribution, with the 3rd class is most likely to be drawn.
The distribution functions can be evaluated on counts.
```python
# counts same shape as alpha.
counts = [0, 0, 2]
dist.pmf(counts) # Shape []
# alpha will be broadcast to [[1, 2, 3], [1, 2, 3]] to match counts.
counts = [[1, 1, 0], [1, 0, 1]]
dist.pmf(counts) # Shape [2]
# alpha will be broadcast to shape [5, 7, 3] to match counts.
counts = [[...]] # Shape [5, 7, 3]
dist.pmf(counts) # Shape [5, 7]
```
Creates a 2-batch of 3-class distributions.
```python
alpha = [[1, 2, 3], [4, 5, 6]] # Shape [2, 3]
n = [3, 3]
dist = DirichletMultinomial(n, alpha)
# counts will be broadcast to [[2, 1, 0], [2, 1, 0]] to match alpha.
counts = [2, 1, 0]
dist.pmf(counts) # Shape [2]
```
- - -
#### `tf.contrib.distributions.DirichletMultinomial.__init__(n, alpha, name='DirichletMultinomial', allow_arbitrary_counts=False)` {#DirichletMultinomial.__init__}
Initialize a batch of DirichletMultinomial distributions.
##### Args:
* `n`: Non-negative `float` or `double` tensor with shape
broadcastable to `[N1,..., Nm]` with `m >= 0`. Defines this as a batch
of `N1 x ... x Nm` different Dirichlet multinomial distributions. Its
components should be equal to integral values.
* `alpha`: Positive `float` or `double` tensor with shape broadcastable to
`[N1,..., Nm, k]` `m >= 0`. Defines this as a batch of `N1 x ... x Nm`
different `k` class Dirichlet multinomial distributions.
* `name`: The name to prefix Ops created by this distribution class.
* `allow_arbitrary_counts`: Boolean. This represents whether the pmf/cdf
allows for the `counts` tensor to be non-integral values.
The pmf/cdf are functions that can be evaluated at non-integral values,
but are only a distribution over non-negative integers.
* `Examples`:
```python
# Define 1-batch of 2-class Dirichlet multinomial distribution,
# also known as a beta-binomial.
dist = DirichletMultinomial(2.0, [1.1, 2.0])
# Define a 2-batch of 3-class distributions.
dist = DirichletMultinomial([3., 4], [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
```
- - -
#### `tf.contrib.distributions.DirichletMultinomial.alpha` {#DirichletMultinomial.alpha}
Parameter defining this distribution.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.batch_shape(name='batch_shape')` {#DirichletMultinomial.batch_shape}
Batch dimensions of this instance as a 1-D int32 `Tensor`.
The product of the dimensions of the `batch_shape` is the number of
independent distributions of this kind the instance represents.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `batch_shape`
- - -
#### `tf.contrib.distributions.DirichletMultinomial.cdf(x, name='cdf')` {#DirichletMultinomial.cdf}
- - -
#### `tf.contrib.distributions.DirichletMultinomial.dtype` {#DirichletMultinomial.dtype}
dtype of samples from this distribution.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.entropy(name='entropy')` {#DirichletMultinomial.entropy}
Entropy of the distribution in nats.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.event_shape(name='event_shape')` {#DirichletMultinomial.event_shape}
Shape of a sample from a single distribution as a 1-D int32 `Tensor`.
##### Args:
* `name`: name to give to the op
##### Returns:
`Tensor` `event_shape`
- - -
#### `tf.contrib.distributions.DirichletMultinomial.get_batch_shape()` {#DirichletMultinomial.get_batch_shape}
`TensorShape` available at graph construction time.
Same meaning as `batch_shape`. May be only partially defined.
##### Returns:
batch shape
- - -
#### `tf.contrib.distributions.DirichletMultinomial.get_event_shape()` {#DirichletMultinomial.get_event_shape}
`TensorShape` available at graph construction time.
Same meaning as `event_shape`. May be only partially defined.
##### Returns:
event shape
- - -
#### `tf.contrib.distributions.DirichletMultinomial.log_cdf(x, name='log_cdf')` {#DirichletMultinomial.log_cdf}
- - -
#### `tf.contrib.distributions.DirichletMultinomial.log_likelihood(value, name='log_likelihood')` {#DirichletMultinomial.log_likelihood}
Log likelihood of this distribution (same as log_pmf).
- - -
#### `tf.contrib.distributions.DirichletMultinomial.log_pmf(counts, name='log_pmf')` {#DirichletMultinomial.log_pmf}
`Log(P[counts])`, computed for every batch member.
For each batch of counts `[n_1,...,n_k]`, `P[counts]` is the probability
that after sampling `n` draws from this Dirichlet Multinomial
distribution, the number of draws falling in class `j` is `n_j`. Note that
different sequences of draws can result in the same counts, thus the
probability includes a combinatorial coefficient.
##### Args:
* `counts`: Non-negative `float` or `double` tensor whose shape can
be broadcast with `self.alpha`. For fixed leading dimensions, the last
dimension represents counts for the corresponding Dirichlet Multinomial
distribution in `self.alpha`. `counts` is only legal if it sums up to
`n` and its components are equal to integral values. The second
condition is relaxed if `allow_arbitrary_counts` is set.
* `name`: Name to give this Op, defaults to "log_pmf".
##### Returns:
Log probabilities for each record, shape `[N1,...,Nn]`.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.mean(name='mean')` {#DirichletMultinomial.mean}
Class means for every batch member.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.mode(name='mode')` {#DirichletMultinomial.mode}
Mode of the distribution.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.n` {#DirichletMultinomial.n}
Parameter defining this distribution.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.name` {#DirichletMultinomial.name}
Name to prepend to all ops.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.pmf(counts, name='pmf')` {#DirichletMultinomial.pmf}
`P[counts]`, computed for every batch member.
For each batch of counts `[c_1,...,c_k]`, `P[counts]` is the probability
that after sampling `sum_j c_j` draws from this Dirichlet Multinomial
distribution, the number of draws falling in class `j` is `c_j`. Note that
different sequences of draws can result in the same counts, thus the
probability includes a combinatorial coefficient.
##### Args:
* `counts`: Non-negative `float`, `double` tensor whose shape can
be broadcast with `self.alpha`. For fixed leading dimensions, the last
dimension represents counts for the corresponding Dirichlet Multinomial
distribution in `self.alpha`. `counts` is only legal if it sums up to
`n` and its components are equal to integral values. The second
condition is relaxed if `allow_arbitrary_counts` is set.
* `name`: Name to give this Op, defaults to "pmf".
##### Returns:
Probabilities for each record, shape `[N1,...,Nn]`.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.sample(n, seed=None, name='sample')` {#DirichletMultinomial.sample}
Generate `n` samples.
##### Args:
* `n`: scalar. Number of samples to draw from each distribution.
* `seed`: Python integer seed for RNG
* `name`: name to give to the op.
##### Returns:
* `samples`: a `Tensor` of shape `(n,) + self.batch_shape + self.event_shape`
with values of type `self.dtype`.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.std(name='std')` {#DirichletMultinomial.std}
Standard deviation of the distribution.
- - -
#### `tf.contrib.distributions.DirichletMultinomial.variance(name='variance')` {#DirichletMultinomial.variance}
Variance of the distribution.
## Posterior inference with conjugate priors.
Functions that transform conjugate prior/likelihood pairs to distributions
representing the posterior or posterior predictive.
### Normal likelihood with conjugate prior.
- - -
### `tf.contrib.distributions.normal_conjugates_known_sigma_posterior(prior, sigma, s, n)` {#normal_conjugates_known_sigma_posterior}
Posterior Normal distribution with conjugate prior on the mean.
This model assumes that `n` observations (with sum `s`) come from a
Normal with unknown mean `mu` (described by the Normal `prior`)
and known variance `sigma^2`. The "known sigma posterior" is
the distribution of the unknown `mu`.
Accepts a prior Normal distribution object, having parameters
`mu0` and `sigma0`, as well as known `sigma` values of the predictive
distribution(s) (also assumed Normal),
and statistical estimates `s` (the sum(s) of the observations) and
`n` (the number(s) of observations).
Returns a posterior (also Normal) distribution object, with parameters
`(mu', sigma'^2)`, where:
```
mu ~ N(mu', sigma'^2)
sigma'^2 = 1/(1/sigma0^2 + n/sigma^2),
mu' = (mu0/sigma0^2 + s/sigma^2) * sigma'^2.
```
Distribution parameters from `prior`, as well as `sigma`, `s`, and `n`.
will broadcast in the case of multidimensional sets of parameters.
##### Args:
* `prior`: `Normal` object of type `dtype`:
the prior distribution having parameters `(mu0, sigma0)`.
* `sigma`: tensor of type `dtype`, taking values `sigma > 0`.
The known stddev parameter(s).
* `s`: Tensor of type `dtype`. The sum(s) of observations.
* `n`: Tensor of type `int`. The number(s) of observations.
##### Returns:
A new Normal posterior distribution object for the unknown observation
mean `mu`.
##### Raises:
* `TypeError`: if dtype of `s` does not match `dtype`, or `prior` is not a
Normal object.
- - -
### `tf.contrib.distributions.normal_congugates_known_sigma_predictive(prior, sigma, s, n)` {#normal_congugates_known_sigma_predictive}
Posterior predictive Normal distribution w. conjugate prior on the mean.
This model assumes that `n` observations (with sum `s`) come from a
Normal with unknown mean `mu` (described by the Normal `prior`)
and known variance `sigma^2`. The "known sigma predictive"
is the distribution of new observations, conditioned on the existing
observations and our prior.
Accepts a prior Normal distribution object, having parameters
`mu0` and `sigma0`, as well as known `sigma` values of the predictive
distribution(s) (also assumed Normal),
and statistical estimates `s` (the sum(s) of the observations) and
`n` (the number(s) of observations).
Calculates the Normal distribution(s) `p(x | sigma^2)`:
```
p(x | sigma^2) = int N(x | mu, sigma^2) N(mu | prior.mu, prior.sigma^2) dmu
= N(x | prior.mu, 1/(sigma^2 + prior.sigma^2))
```
Returns the predictive posterior distribution object, with parameters
`(mu', sigma'^2)`, where:
```
sigma_n^2 = 1/(1/sigma0^2 + n/sigma^2),
mu' = (mu0/sigma0^2 + s/sigma^2) * sigma_n^2.
sigma'^2 = sigma_n^2 + sigma^2,
```
Distribution parameters from `prior`, as well as `sigma`, `s`, and `n`.
will broadcast in the case of multidimensional sets of parameters.
##### Args:
* `prior`: `Normal` object of type `dtype`:
the prior distribution having parameters `(mu0, sigma0)`.
* `sigma`: tensor of type `dtype`, taking values `sigma > 0`.
The known stddev parameter(s).
* `s`: Tensor of type `dtype`. The sum(s) of observations.
* `n`: Tensor of type `int`. The number(s) of observations.
##### Returns:
A new Normal predictive distribution object.
##### Raises:
* `TypeError`: if dtype of `s` does not match `dtype`, or `prior` is not a
Normal object.