# 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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

print(y)
# [0.77663314 0.90824795 0.15685187
#  0.04279523 0.34468332 0.7955718 ]

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

cat.sample([2,3])
# [[0, 0, 5],
#  [3, 4, 5]]

cat.entropy()
# [1.77528]

cat.kl_divergence(cat2)
# [0.071952]

cat.probs(value)
# [0.00608027 0.108298 0.269656]

cat.log_prob(value)
# [-5.10271 -2.22287 -1.31061]
```
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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

cat = Categorical(x)

cat.sample([2,3])
# [[0, 0, 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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

print(y)
# [0.77663314 0.90824795 0.15685187
#  0.04279523 0.34468332 0.7955718 ]

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

cat.kl_divergence(cat2)
# [0.071952]
```
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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

cat = Categorical(x)

cat.entropy()
# [1.77528]
```
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 `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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

cat = Categorical(x)

cat.probs(value)
# [0.00608027 0.108298 0.269656]
```
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

print(x)
# [0.5535528  0.20714243 0.01162981
#  0.51577556 0.36369765 0.2609165 ]

cat = Categorical(x)