class tf.contrib.distributions.Multinomial
See the guide: Statistical Distributions (contrib) > Multivariate distributions
Multinomial distribution.
This distribution is parameterized by a vector p
of probability parameters for k
classes and n
, the counts per each class..
The Multinomial is a distribution over k-class count data, meaning for each k-tuple of non-negative integer counts = [n_1,...,n_k]
, we have a probability of these draws being made from the distribution. The distribution has hyperparameters p = (p_1,...,p_k)
, and probability mass function (pmf):
pmf(counts) = n! / (n_1!...n_k!) * (p_1)^n_1*(p_2)^n_2*...(p_k)^n_k
where above n = sum_j n_j
, n!
is n
factorial.
Create a 3-class distribution, with the 3rd class is most likely to be drawn, using logits..
logits = [-50., -43, 0] dist = Multinomial(n=4., logits=logits)
Create a 3-class distribution, with the 3rd class is most likely to be drawn.
p = [.2, .3, .5] dist = Multinomial(n=4., p=p)
The distribution functions can be evaluated on counts.
# counts same shape as p. counts = [1., 0, 3] dist.prob(counts) # Shape [] # p will be broadcast to [[.2, .3, .5], [.2, .3, .5]] to match counts. counts = [[1., 2, 1], [2, 2, 0]] dist.prob(counts) # Shape [2] # p will be broadcast to shape [5, 7, 3] to match counts. counts = [[...]] # Shape [5, 7, 3] dist.prob(counts) # Shape [5, 7]
Create a 2-batch of 3-class distributions.
p = [[.1, .2, .7], [.3, .3, .4]] # Shape [2, 3] dist = Multinomial(n=[4., 5], p=p) counts = [[2., 1, 1], [3, 1, 1]] dist.prob(counts) # Shape [2]
allow_nan_stats
Python boolean describing behavior when a stat is undefined.
Stats return +/- infinity when it makes sense. E.g., the variance of a Cauchy distribution is infinity. However, sometimes the statistic is undefined, e.g., if a distribution's pdf does not achieve a maximum within the support of the distribution, the mode is undefined. If the mean is undefined, then by definition the variance is undefined. E.g. the mean for Student's T for df = 1 is undefined (no clear way to say it is either + or - infinity), so the variance = E[(X - mean)^2] is also undefined.
allow_nan_stats
: Python boolean.dtype
The DType
of Tensor
s handled by this Distribution
.
is_continuous
is_reparameterized
logits
Vector of coordinatewise logits.
n
Number of trials.
name
Name prepended to all ops created by this Distribution
.
p
Vector of probabilities summing to one.
Each element is the probability of drawing that coordinate.
parameters
Dictionary of parameters used to instantiate this Distribution
.
validate_args
Python boolean indicated possibly expensive checks are enabled.
__init__(n, logits=None, p=None, validate_args=False, allow_nan_stats=True, name='Multinomial')
Initialize a batch of Multinomial distributions.
n
: Non-negative floating point tensor with shape broadcastable to [N1,..., Nm]
with m >= 0
. Defines this as a batch of N1 x ... x Nm
different Multinomial distributions. Its components should be equal to integer values.logits
: Floating point tensor representing the log-odds of a positive event with shape broadcastable to [N1,..., Nm, k], m >= 0
, and the same dtype as n
. Defines this as a batch of N1 x ... x Nm
different k
class Multinomial distributions. Only one of logits
or p
should be passed in.p
: Positive floating point tensor with shape broadcastable to [N1,..., Nm, k]
m >= 0
and same dtype as n
. Defines this as a batch of N1 x ... x Nm
different k
class Multinomial distributions. p
's components in the last portion of its shape should sum up to 1. Only one of logits
or p
should be passed in.validate_args
: Boolean
, default False
. Whether to assert valid values for parameters n
and p
, and x
in prob
and log_prob
. If False
, correct behavior is not guaranteed.allow_nan_stats
: Boolean
, default True
. If False
, raise an exception if a statistic (e.g. mean/mode/etc...) is undefined for any batch member. If True
, batch members with valid parameters leading to undefined statistics will return NaN for this statistic.name
: The name to prefix Ops created by this distribution class.Examples:
# Define 1-batch of 2-class multinomial distribution, # also known as a Binomial distribution. dist = Multinomial(n=2., p=[.1, .9]) # Define a 2-batch of 3-class distributions. dist = Multinomial(n=[4., 5], p=[[.1, .3, .6], [.4, .05, .55]])
batch_shape(name='batch_shape')
Shape of a single sample from a single event index as a 1-D Tensor
.
The product of the dimensions of the batch_shape
is the number of independent distributions of this kind the instance represents.
name
: name to give to the opbatch_shape
: Tensor
.cdf(value, name='cdf', **condition_kwargs)
Cumulative distribution function.
Given random variable X
, the cumulative distribution function cdf
is:
cdf(x) := P[X <= x]
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.cdf
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.copy(**override_parameters_kwargs)
Creates a deep copy of the distribution.
Note: the copy distribution may continue to depend on the original intialization arguments.
**override_parameters_kwargs: String/value dictionary of initialization arguments to override with new values.
distribution
: A new instance of type(self)
intitialized from the union of self.parameters and override_parameters_kwargs, i.e., dict(self.parameters, **override_parameters_kwargs)
.entropy(name='entropy')
Shannon entropy in nats.
event_shape(name='event_shape')
Shape of a single sample from a single batch as a 1-D int32 Tensor
.
name
: name to give to the opevent_shape
: Tensor
.get_batch_shape()
Shape of a single sample from a single event index as a TensorShape
.
Same meaning as batch_shape
. May be only partially defined.
batch_shape
: TensorShape
, possibly unknown.get_event_shape()
Shape of a single sample from a single batch as a TensorShape
.
Same meaning as event_shape
. May be only partially defined.
event_shape
: TensorShape
, possibly unknown.is_scalar_batch(name='is_scalar_batch')
Indicates that batch_shape == []
.
name
: The name to give this op.is_scalar_batch
: Boolean
scalar
Tensor
.is_scalar_event(name='is_scalar_event')
Indicates that event_shape == []
.
name
: The name to give this op.is_scalar_event
: Boolean
scalar
Tensor
.log_cdf(value, name='log_cdf', **condition_kwargs)
Log cumulative distribution function.
Given random variable X
, the cumulative distribution function cdf
is:
log_cdf(x) := Log[ P[X <= x] ]
Often, a numerical approximation can be used for log_cdf(x)
that yields a more accurate answer than simply taking the logarithm of the cdf
when x << -1
.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.logcdf
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.log_pdf(value, name='log_pdf', **condition_kwargs)
Log probability density function.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.log_prob
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.TypeError
: if not is_continuous
.log_pmf(value, name='log_pmf', **condition_kwargs)
Log probability mass function.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.log_pmf
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.TypeError
: if is_continuous
.log_prob(value, name='log_prob', **condition_kwargs)
Log probability density/mass function (depending on is_continuous
).
Additional documentation from Multinomial
:
For each batch of counts [n_1,...,n_k]
, P[counts]
is the probability that after sampling n
draws from this 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.
Note that input "counts" must be a non-negative tensor with dtype dtype
and whose shape can be broadcast with self.p
and self.n
. For fixed leading dimensions, the last dimension represents counts for the corresponding Multinomial distribution in self.p
. counts
is only legal if it sums up to n
and its components are equal to integer values.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.log_prob
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.log_survival_function(value, name='log_survival_function', **condition_kwargs)
Log survival function.
Given random variable X
, the survival function is defined:
log_survival_function(x) = Log[ P[X > x] ] = Log[ 1 - P[X <= x] ] = Log[ 1 - cdf(x) ]
Typically, different numerical approximations can be used for the log survival function, which are more accurate than 1 - cdf(x)
when x >> 1
.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.
mean(name='mean')
Mean.
mode(name='mode')
Mode.
param_shapes(cls, sample_shape, name='DistributionParamShapes')
Shapes of parameters given the desired shape of a call to sample()
.
Subclasses should override static method _param_shapes
.
sample_shape
: Tensor
or python list/tuple. Desired shape of a call to sample()
.name
: name to prepend ops with.dict
of parameter name to Tensor
shapes.
param_static_shapes(cls, sample_shape)
param_shapes with static (i.e. TensorShape) shapes.
sample_shape
: TensorShape
or python list/tuple. Desired shape of a call to sample()
.dict
of parameter name to TensorShape
.
ValueError
: if sample_shape
is a TensorShape
and is not fully defined.pdf(value, name='pdf', **condition_kwargs)
Probability density function.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.prob
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.TypeError
: if not is_continuous
.pmf(value, name='pmf', **condition_kwargs)
Probability mass function.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.pmf
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.TypeError
: if is_continuous
.prob(value, name='prob', **condition_kwargs)
Probability density/mass function (depending on is_continuous
).
Additional documentation from Multinomial
:
For each batch of counts [n_1,...,n_k]
, P[counts]
is the probability that after sampling n
draws from this 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.
Note that input "counts" must be a non-negative tensor with dtype dtype
and whose shape can be broadcast with self.p
and self.n
. For fixed leading dimensions, the last dimension represents counts for the corresponding Multinomial distribution in self.p
. counts
is only legal if it sums up to n
and its components are equal to integer values.
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.prob
: a Tensor
of shape sample_shape(x) + self.batch_shape
with values of type self.dtype
.sample(sample_shape=(), seed=None, name='sample', **condition_kwargs)
Generate samples of the specified shape.
Note that a call to sample()
without arguments will generate a single sample.
sample_shape
: 0D or 1D int32
Tensor
. Shape of the generated samples.seed
: Python integer seed for RNGname
: name to give to the op. **condition_kwargs: Named arguments forwarded to subclass implementation.samples
: a Tensor
with prepended dimensions sample_shape
.std(name='std')
Standard deviation.
survival_function(value, name='survival_function', **condition_kwargs)
Survival function.
Given random variable X
, the survival function is defined:
survival_function(x) = P[X > x] = 1 - P[X <= x] = 1 - cdf(x).
value
: float
or double
Tensor
.name
: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.Tensorof shape
sample_shape(x) + self.batch_shapewith values of type
self.dtype`.
variance(name='variance')
Variance.
Defined in tensorflow/contrib/distributions/python/ops/multinomial.py
.
© 2017 The TensorFlow Authors. All rights reserved.
Licensed under the Creative Commons Attribution License 3.0.
Code samples licensed under the Apache 2.0 License.
https://www.tensorflow.org/api_docs/python/tf/contrib/distributions/Multinomial