tf.contrib.distributions.Binomial

class tf.contrib.distributions.Binomial

See the guide: Statistical Distributions (contrib) > Univariate (scalar) distributions

Binomial distribution.

This distribution is parameterized by a vector p of probabilities and n, the total counts.

Mathematical details

The Binomial is a distribution over the number of successes in n independent trials, with each trial having the same probability of success p. The probability mass function (pmf):

pmf(k) = n! / (k! * (n - k)!) * (p)^k * (1 - p)^(n - k)

Examples

Create a single distribution, corresponding to 5 coin flips.

dist = Binomial(n=5., p=.5)

Create a single distribution (using logits), corresponding to 5 coin flips.

dist = Binomial(n=5., logits=0.)

Creates 3 distributions with the third distribution most likely to have successes.

p = [.2, .3, .8]
# n will be broadcast to [4., 4., 4.], to match p.
dist = Binomial(n=4., p=p)

The distribution functions can be evaluated on counts.

# counts same shape as p.
counts = [1., 2, 3]
dist.prob(counts)  # Shape [3]

# p will be broadcast to [[.2, .3, .8], [.2, .3, .8]] to match counts.
counts = [[1., 2, 1], [2, 2, 4]]
dist.prob(counts)  # Shape [2, 3]

# p will be broadcast to shape [5, 7, 3] to match counts.
counts = [[...]]  # Shape [5, 7, 3]
dist.prob(counts)  # Shape [5, 7, 3]

Properties

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.

Returns:

• allow_nan_stats: Python boolean.

dtype

The DType of Tensors handled by this Distribution.

is_continuous

is_reparameterized

logits

Log-odds of success.

n

Number of trials.

name

Name prepended to all ops created by this Distribution.

p

Probability of success.

parameters

Dictionary of parameters used to instantiate this Distribution.

validate_args

Python boolean indicated possibly expensive checks are enabled.

Methods

__init__(n, logits=None, p=None, validate_args=False, allow_nan_stats=True, name='Binomial')

Initialize a batch of Binomial distributions.

Args:

• n: Non-negative floating point tensor with shape broadcastable to [N1,..., Nm] with m >= 0 and the same dtype as p or logits. Defines this as a batch of N1 x ... x Nm different Binomial 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] m >= 0, and the same dtype as n. Each entry represents logits for the probability of success for independent Binomial distributions. Only one of logits or p should be passed in.
• p: Positive floating point tensor with shape broadcastable to [N1,..., Nm] m >= 0, p in [0, 1]. Each entry represents the probability of success for independent Binomial distributions. Only one of logits or p should be passed in.
• validate_args: Boolean, default False. Whether to assert valid values for parameters n, p, and x in prob and log_prob. If False and inputs are invalid, 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 a binomial distribution.
dist = Binomial(n=2., p=.9)

# Define a 2-batch.
dist = Binomial(n=[4., 5], p=[.1, .3])

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.

Args:

• name: name to give to the op

Returns:

• batch_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]

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

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

Args:

**override_parameters_kwargs: String/value dictionary of initialization arguments to override with new values.

Returns:

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

Args:

• name: name to give to the op

Returns:

• event_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.

Returns:

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

Returns:

• event_shape: TensorShape, possibly unknown.

is_scalar_batch(name='is_scalar_batch')

Indicates that batch_shape == [].

Args:

• name: The name to give this op.

Returns:

• is_scalar_batch: Boolean scalar Tensor.

is_scalar_event(name='is_scalar_event')

Indicates that event_shape == [].

Args:

• name: The name to give this op.

Returns:

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

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

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

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

• log_prob: a Tensor of shape sample_shape(x) + self.batch_shape with values of type self.dtype.

Raises:

• TypeError: if not is_continuous.

log_pmf(value, name='log_pmf', **condition_kwargs)

Log probability mass function.

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

• log_pmf: a Tensor of shape sample_shape(x) + self.batch_shape with values of type self.dtype.

Raises:

• TypeError: if is_continuous.

log_prob(value, name='log_prob', **condition_kwargs)

Log probability density/mass function (depending on is_continuous).

Additional documentation from Binomial:

For each batch member of counts value, P[counts] is the probability that after sampling n draws from this Binomial distribution, the number of successes is k. Note that different sequences of draws can result in the same counts, thus the probability includes a combinatorial coefficient.

value must be a non-negative tensor with dtype dtype and whose shape can be broadcast with self.p and self.n. counts is only legal if it is less than or equal to n and its components are equal to integer values.

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

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

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

Tensor of shape sample_shape(x) + self.batch_shape with values of type self.dtype.

mean(name='mean')

Mean.

mode(name='mode')

Mode.

Additional documentation from Binomial:

Note that when (n + 1) * p is an integer, there are actually two modes. Namely, (n + 1) * p and (n + 1) * p - 1 are both modes. Here we return only the larger of the two modes.

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.

Args:

• sample_shape: Tensor or python list/tuple. Desired shape of a call to sample().
• name: name to prepend ops with.

Returns:

dict of parameter name to Tensor shapes.

param_static_shapes(cls, sample_shape)

param_shapes with static (i.e. TensorShape) shapes.

Args:

• sample_shape: TensorShape or python list/tuple. Desired shape of a call to sample().

Returns:

dict of parameter name to TensorShape.

Raises:

• ValueError: if sample_shape is a TensorShape and is not fully defined.

pdf(value, name='pdf', **condition_kwargs)

Probability density function.

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

• prob: a Tensor of shape sample_shape(x) + self.batch_shape with values of type self.dtype.

Raises:

• TypeError: if not is_continuous.

pmf(value, name='pmf', **condition_kwargs)

Probability mass function.

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

• pmf: a Tensor of shape sample_shape(x) + self.batch_shape with values of type self.dtype.

Raises:

• TypeError: if is_continuous.

prob(value, name='prob', **condition_kwargs)

Probability density/mass function (depending on is_continuous).

Additional documentation from Binomial:

For each batch member of counts value, P[counts] is the probability that after sampling n draws from this Binomial distribution, the number of successes is k. Note that different sequences of draws can result in the same counts, thus the probability includes a combinatorial coefficient.

value must be a non-negative tensor with dtype dtype and whose shape can be broadcast with self.p and self.n. counts is only legal if it is less than or equal to n and its components are equal to integer values.

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

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

Args:

• sample_shape: 0D or 1D int32 Tensor. Shape of the generated samples.
• seed: Python integer seed for RNG
• name: name to give to the op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

• 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).

Args:

• value: float or double Tensor.
• name: The name to give this op. **condition_kwargs: Named arguments forwarded to subclass implementation.

Returns:

Tensorof shapesample_shape(x) + self.batch_shapewith values of typeself.dtype`.

variance(name='variance')

Variance.

Defined in tensorflow/contrib/distributions/python/ops/binomial.py.