Categorical¶

class paddle.distribution. Categorical ( logits, name=None ) [source]

Categorical distribution is a discrete probability distribution that describes the possible results of a random variable that can take on one of K possible categories, with the probability of each category separately specified.

The probability mass function (pmf) is:

\[pmf(k; p_i) = \prod_{i=1}^{k} p_i^{[x=i]}\]

In the above equation:

\([x=i]\) : it evaluates to 1 if \(x==i\) , 0 otherwise.

Parameters

logits (list|tuple|numpy.ndarray|Tensor) – The logits input of categorical distribution. The data type is float32 or float64.
name (str, optional) – Name for the operation (optional, default is None). For more information, please refer to Name.

Examples

           >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> paddle.seed(200) # on CPU device
>>> y = paddle.rand([6])
>>> print(y)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.77663314, 0.90824795, 0.15685187, 0.04279523, 0.34468332, 0.79557180])

>>> cat = Categorical(x)
>>> cat2 = Categorical(y)

>>> paddle.seed(1000) # on CPU device
>>> print(cat.sample([2,3]))
Tensor(shape=[2, 3], dtype=int64, place=Place(cpu), stop_gradient=True,
[[0, 1, 5],
[3, 4, 5]])

>>> print(cat.entropy())
Tensor(shape=[], dtype=float32, place=Place(cpu), stop_gradient=True,
1.77528250)

>>> print(cat.kl_divergence(cat2))
Tensor(shape=[1], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.07195196])

>>> value = paddle.to_tensor([2,1,3])
>>> print(cat.probs(value))
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.00608027, 0.10829761, 0.26965630])

>>> print(cat.log_prob(value))
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[-5.10270691, -2.22287226, -1.31060708])

          

sample ( shape ) sample¶

Generate samples of the specified shape.

Parameters: shape (list) – Shape of the generated samples.
Returns: A tensor with prepended dimensions shape.
Return type: Tensor

Examples

             >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> 
>>> cat = Categorical(x)
>>> paddle.seed(1000) # on CPU device
>>> print(cat.sample([2,3]))
Tensor(shape=[2, 3], dtype=int64, place=Place(cpu), stop_gradient=True,
[[0, 1, 5],
[3, 4, 5]])

            

property batch_shape

Returns batch shape of distribution

Returns: batch shape
Return type: Sequence[int]

property event_shape

Returns event shape of distribution

Returns: event shape
Return type: Sequence[int]

kl_divergence ( other ) [source] kl_divergence¶

The KL-divergence between two Categorical distributions.

Parameters: other (Categorical) – instance of Categorical. The data type is float32.
Returns: kl-divergence between two Categorical distributions.
Return type: Tensor

Examples

             >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> paddle.seed(200) # on CPU device
>>> y = paddle.rand([6])
>>> print(y)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.77663314, 0.90824795, 0.15685187, 0.04279523, 0.34468332, 0.79557180])

>>> cat = Categorical(x)
>>> cat2 = Categorical(y)

>>> print(cat.kl_divergence(cat2))
Tensor(shape=[1], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.07195196])

            

property mean: Mean of distribution

prob ( value ) prob¶

Probability density/mass function evaluated at value.

Parameters: value (Tensor) – value which will be evaluated

rsample ( shape=() ) rsample¶: reparameterized sample

property variance: Variance of distribution

entropy ( ) entropy¶

Shannon entropy in nats.

Returns: Shannon entropy of Categorical distribution. The data type is float32.
Return type: Tensor

Examples

             >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> cat = Categorical(x)

>>> print(cat.entropy())
Tensor(shape=[], dtype=float32, place=Place(cpu), stop_gradient=True,
1.77528250)

            

probs ( value ) probs¶

Probabilities of the given category (value).

If logits is 2-D or higher dimension, the last dimension will be regarded as category, and the others represents the different distributions. At the same time, if vlaue is 1-D Tensor, value will be broadcast to the same number of distributions as logits. If value is not 1-D Tensor, value should have the same number distributions with logits. That is, ``value[:-1] = logits[:-1].

Parameters: value (Tensor) – The input tensor represents the selected category index.
Returns: probability according to the category index.
Return type: Tensor

Examples

             >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> cat = Categorical(x)

>>> value = paddle.to_tensor([2,1,3])
>>> print(cat.probs(value))
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.00608027, 0.10829761, 0.26965630])

            

log_prob ( value ) log_prob¶

Log probabilities of the given category. Refer to probs method.

Parameters: value (Tensor) – The input tensor represents the selected category index.
Returns: Log probability.
Return type: Tensor

Examples

             >>> import paddle
>>> from paddle.distribution import Categorical

>>> paddle.seed(100) # on CPU device
>>> x = paddle.rand([6])
>>> print(x)
Tensor(shape=[6], dtype=float32, place=Place(cpu), stop_gradient=True,
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> cat = Categorical(x)

>>> value = paddle.to_tensor([2,1,3])
>>> print(cat.log_prob(value))
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[-5.10270691, -2.22287226, -1.31060708])

            

Categorical¶

sample¶

kl_divergence¶

prob¶

rsample¶

entropy¶

probs¶

log_prob¶