chainer.Distribution

class chainer.Distribution

Interface of Distribution

Distribution is a bass class for dealing with probability distributions.

This class provides the following capabilities.

1. Sampling random points.
2. Evaluating a probability-related function at a given realization value. (e.g., probability density function, probability mass function)
3. Obtaining properties of distributions. (e.g., mean, variance)

Note that every method and property that computes them from chainer.Variable can basically be differentiated.

In this class, sampled random points and realization values given in probability-related function is called sample. Sample consists of batches, and each batch consists of independent events. Each event consists of values, and each value in an event cannot be sampled independently in general. Each event in a batch is independent while it is not sampled from an identical distribution. And each batch in sample is sampled from an identical distribution.

Each part of the sample-batch-event hierarchy has its own shape, which is called sample_shape, batch_shape, and event_shape, respectively.

On initialization, it takes distribution-specific parameters as inputs. batch_shape and event_shape is decided by the shape of the parameter when generating an instance of a class.

Example

The following code is an example of sample-batch-event hierarchy on using MultivariateNormal distribution. This makes 2d normal distributions. dist consists of 12(4 * 3) independent 2d normal distributions. And on initialization, batch_shape and event_shape is decided.

>>> import chainer
>>> import chainer.distributions as D
>>> import numpy as np
>>> d = 2
>>> shape = (4, 3)
>>> loc = np.random.normal(
...     size=shape + (d,)).astype(np.float32)
>>> cov = np.random.normal(size=shape + (d, d)).astype(np.float32)
>>> cov = np.matmul(cov, np.rollaxis(cov, -1, -2))
>>> l = np.linalg.cholesky(cov)
>>> dist = D.MultivariateNormal(loc, scale_tril=l)
>>> dist.event_shape
(2,)
>>> dist.batch_shape
(4, 3)
>>> sample = dist.sample(sample_shape=(6, 5))
>>> sample.shape
(6, 5, 4, 3, 2)

Every probability-related function takes realization value whose shape is the concatenation of sample_shape, batch_shape, and event_shape and returns an evaluated value whose shape is the concatenation of sample_shape, and batch_shape.

Methods

cdf(x)

Evaluates the cumulative distribution function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Cumulative distribution function value evaluated at x. Return type:Variable

icdf(x)

Evaluates the inverse cumulative distribution function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Inverse cumulative distribution function value evaluated at x. Return type:Variable

log_cdf(x)

Evaluates the log of cumulative distribution function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Logarithm of cumulative distribution function value evaluated at x. Return type:Variable

log_prob(x)

Evaluates the logarithm of probability at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Logarithm of probability evaluated at x. Return type:Variable

log_survival_function(x)

Evaluates the logarithm of survival function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Logarithm of survival function value evaluated at x. Return type:Variable

perplexity(x)

Evaluates the perplexity function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Perplexity function value evaluated at x. Return type:Variable

prob(x)

Evaluates probability at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Probability evaluated at x. Return type:Variable

sample(sample_shape=())

Samples random points from the distribution.

This function calls sample_n and reshapes a result of sample_n to sample_shape + batch_shape + event_shape. On implementing sampling code in an inherited ditribution class, it is not recommended to override this function. Instead of doing this, it is preferable to override sample_n.

Parameters:sample_shape (tuple of int) – Sampling shape. Returns:Sampled random points. Return type:Variable

sample_n(n)

Samples n random points from the distribution.

This function returns sampled points whose shape is (n,) + batch_shape + event_shape. When implementing sampling code in a subclass, it is recommended to override this method.

Parameters:n (int) – Sampling size. Returns:sampled random points. Return type:Variable

survival_function(x)

Evaluates the survival function at the given points.

Parameters:x (Variable or numpy.ndarray or cupy.ndarray) – Data points in the domain of the distribution Returns:Survival function value evaluated at x. Return type:Variable

Attributes

batch_shape

Returns the shape of a batch.

Returns:The shape of a sample that is not identical and indipendent. Return type:tuple

covariance

Returns the covariance of the distribution.

Returns:The covariance of the distribution. Return type:Variable

entropy

Returns the entropy of the distribution.

Returns:The entropy of the distribution. Return type:Variable

event_shape

Returns the shape of an event.

Returns:The shape of a sample that is not identical and independent. Return type:tuple

mean

Returns the mean of the distribution.

Returns:The mean of the distribution. Return type:Variable

mode

Returns the mode of the distribution.

Returns:The mode of the distribution. Return type:Variable

params

Returns the parameters of the distribution.

Returns:The parameters of the distribution. Return type:dict

stddev

Returns the standard deviation of the distribution.

Returns:The standard deviation of the distribution. Return type:Variable

support

Returns the support of the distribution.

Returns:String that means support of this distribution. Return type:str

variance

Returns the variance of the distribution.

Returns:The variance of the distribution. Return type:Variable

xp

Array module for the distribution.

Depending on which of CPU/GPU this distribution is on, this property returns numpy or cupy.