# 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

>>> paddle.seed(100) # on CPU device
>>> print(x)
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> paddle.seed(200) # on CPU device
>>> print(y)
[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]))
[[0, 1, 5],
[3, 4, 5]])

>>> print(cat.entropy())
1.77528250)

>>> print(cat.kl_divergence(cat2))
[0.07195196])

>>> print(cat.probs(value))
[0.00608027, 0.10829761, 0.26965630])

>>> print(cat.log_prob(value))
[-5.10270691, -2.22287226, -1.31060708])
```
sample ( shape )

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

>>> paddle.seed(100) # on CPU device
>>> print(x)
[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]))
[[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]

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

>>> paddle.seed(100) # on CPU device
>>> print(x)
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> paddle.seed(200) # on CPU device
>>> print(y)
[0.77663314, 0.90824795, 0.15685187, 0.04279523, 0.34468332, 0.79557180])

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

>>> print(cat.kl_divergence(cat2))
[0.07195196])
```
property mean

Mean of distribution

prob ( value )

Probability density/mass function evaluated at value.

Parameters

value (Tensor) – value which will be evaluated

rsample ( shape=() )

reparameterized sample

property variance

Variance of distribution

entropy ( )

Shannon entropy in nats.

Returns

Shannon entropy of Categorical distribution. The data type is float32.

Return type

Tensor

Examples

```>>> import paddle

>>> paddle.seed(100) # on CPU device
>>> print(x)
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> cat = Categorical(x)

>>> print(cat.entropy())
1.77528250)
```
probs ( value )

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 `value` 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

>>> paddle.seed(100) # on CPU device
>>> print(x)
[0.55355281, 0.20714243, 0.01162981, 0.51577556, 0.36369765, 0.26091650])

>>> cat = Categorical(x)

>>> print(cat.probs(value))
[0.00608027, 0.10829761, 0.26965630])
```
log_prob ( value )

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

>>> paddle.seed(100) # on CPU device