14.5 Categorical distribution

14.5.1 Probability mass functions

If \(N \in \mathbb{N}\), \(N > 0\), and if \(\theta \in \mathbb{R}^N\) forms an \(N\)-simplex (i.e., has nonnegative entries summing to one), then for \(y \in \{1,\ldots,N\}\), \[ \text{Categorical}(y~|~\theta) = \theta_y. \] In addition, Stan provides a log-odds scaled categorical distribution, \[ \text{CategoricalLogit}(y~|~\beta) = \text{Categorical}(y~|~\text{softmax}(\beta)). \] See the definition of softmax for the definition of the softmax function.

14.5.2 Sampling statement

y ~ categorical(theta)

Increment target log probability density with categorical_lupmf(y | theta) dropping constant additive terms.
Available since 2.0

14.5.3 Sampling statement

y ~ categorical_logit(beta)

Increment target log probability density with categorical_logit_lupmf(y | beta).
Available since 2.4

14.5.4 Stan functions

All of the categorical distributions are vectorized so that the outcome y can be a single integer (type int) or an array of integers (type array[] int).

real categorical_lpmf(ints y | vector theta)
The log categorical probability mass function with outcome(s) y in \(1:N\) given \(N\)-vector of outcome probabilities theta. The parameter theta must have non-negative entries that sum to one, but it need not be a variable declared as a simplex.
Available since 2.12

real categorical_lupmf(ints y | vector theta)
The log categorical probability mass function with outcome(s) y in \(1:N\) given \(N\)-vector of outcome probabilities theta dropping constant additive terms. The parameter theta must have non-negative entries that sum to one, but it need not be a variable declared as a simplex.
Available since 2.25

real categorical_logit_lpmf(ints y | vector beta)
The log categorical probability mass function with outcome(s) y in \(1:N\) given log-odds of outcomes beta.
Available since 2.12

real categorical_logit_lupmf(ints y | vector beta)
The log categorical probability mass function with outcome(s) y in \(1:N\) given log-odds of outcomes beta dropping constant additive terms.
Available since 2.25

int categorical_rng(vector theta)
Generate a categorical variate with \(N\)-simplex distribution parameter theta; may only be used in transformed data and generated quantities blocks
Available since 2.0

int categorical_logit_rng(vector beta)
Generate a categorical variate with outcome in range \(1:N\) from log-odds vector beta; may only be used in transformed data and generated quantities blocks
Available since 2.16