# 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 a scalar 1. 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=None)` {#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=None)` {#BaseDistribution.entropy} Entropy of the distribution in nats. - - - #### `tf.contrib.distributions.BaseDistribution.event_shape(name=None)` {#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` {#BaseDistribution.mean} - - - #### `tf.contrib.distributions.BaseDistribution.name` {#BaseDistribution.name} Name to prepend to all ops. - - - #### `tf.contrib.distributions.BaseDistribution.sample(n, seed=None, name=None)` {#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`. - - - ### `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=None)` {#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=None)` {#ContinuousDistribution.entropy} Entropy of the distribution in nats. - - - #### `tf.contrib.distributions.ContinuousDistribution.event_shape(name=None)` {#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_pdf(value, name='log_pdf')` {#ContinuousDistribution.log_pdf} Log of the probability density function. - - - #### `tf.contrib.distributions.ContinuousDistribution.mean` {#ContinuousDistribution.mean} - - - #### `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=None)` {#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`. - - - ### `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=None)` {#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=None)` {#DiscreteDistribution.entropy} Entropy of the distribution in nats. - - - #### `tf.contrib.distributions.DiscreteDistribution.event_shape(name=None)` {#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_pmf(value, name='log_pmf')` {#DiscreteDistribution.log_pmf} Log of the probability mass function. - - - #### `tf.contrib.distributions.DiscreteDistribution.mean` {#DiscreteDistribution.mean} - - - #### `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=None)` {#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`. ### 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_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` {#Chi2.mean} Mean of each batch member. - - - #### `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=None)` {#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.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_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` {#Exponential.mean} Mean of each batch member. - - - #### `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.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_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` {#Gamma.mean} Mean of each batch member. - - - #### `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=None)` {#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.variance` {#Gamma.variance} Variance of each batch member. - - - ### `class tf.contrib.distributions.Gaussian` {#Gaussian} The scalar Gaussian 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 Gaussian distribution. dist = tf.contrib.distributions.Gaussian(mu=0, sigma=3) # Evaluate the cdf at 1, returning a scalar. dist.cdf(1) # Define a batch of two scalar valued Gaussians. # The first has mean 1 and standard deviation 11, the second 2 and 22. dist = tf.contrib.distributions.Gaussian(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 Gaussians. # Both have mean 1, but different standard deviations. dist = tf.contrib.distributions.Gaussian(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.Gaussian.__init__(mu, sigma, name=None)` {#Gaussian.__init__} Construct Gaussian 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.Gaussian.cdf(x, name=None)` {#Gaussian.cdf} CDF of observations in `x` under these Gaussian 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.Gaussian.dtype` {#Gaussian.dtype} - - - #### `tf.contrib.distributions.Gaussian.entropy(name=None)` {#Gaussian.entropy} The entropy of Gaussian distribution(s). ##### Args: * `name`: The name to give this op. ##### Returns: * `entropy`: tensor of dtype `dtype`, the entropy. - - - #### `tf.contrib.distributions.Gaussian.is_reparameterized` {#Gaussian.is_reparameterized} - - - #### `tf.contrib.distributions.Gaussian.log_cdf(x, name=None)` {#Gaussian.log_cdf} Log CDF of observations `x` under these Gaussian 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.Gaussian.log_pdf(x, name=None)` {#Gaussian.log_pdf} Log pdf of observations in `x` under these Gaussian 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.Gaussian.mean` {#Gaussian.mean} - - - #### `tf.contrib.distributions.Gaussian.mu` {#Gaussian.mu} - - - #### `tf.contrib.distributions.Gaussian.pdf(x, name=None)` {#Gaussian.pdf} The PDF of observations in `x` under these Gaussian 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.Gaussian.sample(n, seed=None, name=None)` {#Gaussian.sample} Sample `n` observations from the Gaussian 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.Gaussian.sigma` {#Gaussian.sigma} - - - ### `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_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` {#StudentT.mean} - - - #### `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.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_pdf(x, name='log_pdf')` {#Uniform.log_pdf} - - - #### `tf.contrib.distributions.Uniform.mean` {#Uniform.mean} - - - #### `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` {#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.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. #### 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) = C! / (c_1!...c_k!) * Beta(alpha + c) / Beta(alpha)``` where above `C = sum_j c_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 `N` samples can be produced by: 1. Choose class probabilities `p = (p_1,...,p_k) ~ Dir(alpha)` 2. Draw integers `m = (m_1,...,m_k) ~ Multinomial(p, N)` 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.pdf(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] dist = DirichletMultinomial(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, 2, 0] dist.pdf(counts) # Shape [] # alpha will be broadcast to [[1, 2, 3], [1, 2, 3]] to match counts. counts = [[11, 22, 33], [44, 55, 66]] dist.pdf(counts) # Shape [2] # alpha will be broadcast to shape [5, 7, 3] to match counts. counts = [[...]] # Shape [5, 7, 3] dist.pdf(counts) # Shape [5, 7] ``` Creates a 2-batch of 3-class distributions. ```python alpha = [[1, 2, 3], [4, 5, 6]] # Shape [2, 3] dist = DirichletMultinomial(alpha) # counts will be broadcast to [[11, 22, 33], [11, 22, 33]] to match alpha. counts = [11, 22, 33] dist.pdf(counts) # Shape [2] ``` - - - #### `tf.contrib.distributions.DirichletMultinomial.__init__(alpha)` {#DirichletMultinomial.__init__} Initialize a batch of DirichletMultinomial distributions. ##### Args: * `alpha`: Shape `[N1,..., Nn, k]` positive `float` or `double` tensor with `n >= 0`. Defines this as a batch of `N1 x ... x Nn` different `k` class Dirichlet multinomial distributions. * `Examples`: ```python # Define 1-batch of 2-class Dirichlet multinomial distribution, # also known as a beta-binomial. dist = DirichletMultinomial([1.1, 2.0]) # Define a 2-batch of 3-class distributions. dist = DirichletMultinomial([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]) ``` - - - #### `tf.contrib.distributions.DirichletMultinomial.alpha` {#DirichletMultinomial.alpha} Parameters defining this distribution. - - - #### `tf.contrib.distributions.DirichletMultinomial.cdf(x)` {#DirichletMultinomial.cdf} - - - #### `tf.contrib.distributions.DirichletMultinomial.dtype` {#DirichletMultinomial.dtype} - - - #### `tf.contrib.distributions.DirichletMultinomial.log_cdf(x)` {#DirichletMultinomial.log_cdf} - - - #### `tf.contrib.distributions.DirichletMultinomial.log_pmf(counts, name=None)` {#DirichletMultinomial.log_pmf} `Log(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`, or `int` 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`. * `name`: Name to give this Op, defaults to "log_pmf". ##### Returns: Log probabilities for each record, shape `[N1,...,Nn]`. - - - #### `tf.contrib.distributions.DirichletMultinomial.mean` {#DirichletMultinomial.mean} Class means for every batch member. - - - #### `tf.contrib.distributions.DirichletMultinomial.num_classes` {#DirichletMultinomial.num_classes} Tensor providing number of classes in each batch member. - - - #### `tf.contrib.distributions.DirichletMultinomial.pmf(counts, name=None)` {#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`, or `int` 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`. * `name`: Name to give this Op, defaults to "pmf". ##### Returns: Probabilities for each record, shape `[N1,...,Nn]`. ## Posterior inference with conjugate priors. Functions that transform conjugate prior/likelihood pairs to distributions representing the posterior or posterior predictive. ### Gaussian likelihood with conjugate prior. - - - ### `tf.contrib.distributions.gaussian_conjugates_known_sigma_posterior(prior, sigma, s, n)` {#gaussian_conjugates_known_sigma_posterior} Posterior Gaussian distribution with conjugate prior on the mean. This model assumes that `n` observations (with sum `s`) come from a Gaussian with unknown mean `mu` (described by the Gaussian `prior`) and known variance `sigma^2`. The "known sigma posterior" is the distribution of the unknown `mu`. Accepts a prior Gaussian distribution object, having parameters `mu0` and `sigma0`, as well as known `sigma` values of the predictive distribution(s) (also assumed Gaussian), and statistical estimates `s` (the sum(s) of the observations) and `n` (the number(s) of observations). Returns a posterior (also Gaussian) 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`: `Gaussian` 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 Gaussian posterior distribution object for the unknown observation mean `mu`. ##### Raises: * `TypeError`: if dtype of `s` does not match `dtype`, or `prior` is not a Gaussian object. - - - ### `tf.contrib.distributions.gaussian_congugates_known_sigma_predictive(prior, sigma, s, n)` {#gaussian_congugates_known_sigma_predictive} Posterior predictive Gaussian distribution w. conjugate prior on the mean. This model assumes that `n` observations (with sum `s`) come from a Gaussian with unknown mean `mu` (described by the Gaussian `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 Gaussian distribution object, having parameters `mu0` and `sigma0`, as well as known `sigma` values of the predictive distribution(s) (also assumed Gaussian), and statistical estimates `s` (the sum(s) of the observations) and `n` (the number(s) of observations). Calculates the Gaussian 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`: `Gaussian` 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 Gaussian predictive distribution object. ##### Raises: * `TypeError`: if dtype of `s` does not match `dtype`, or `prior` is not a Gaussian object.