## 12.5 Categorical Distribution

### 12.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 section 5.11 for the definition of the softmax function.

### 12.5.2 Sampling Statement

y ~ categorical(theta)

Increment target log probability density with categorical_lpmf( y | theta) dropping constant additive terms.

### 12.5.3 Sampling Statement

y ~ categorical_logit(beta)

Increment target log probability density with categorical_logit_lpmf( y | beta) dropping constant additive terms.

### 12.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 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.

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.

int categorical_rng(vector theta)
Generate a categorical variate with $$N$$-simplex distribution parameter theta; may only be used in generated quantities block

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 generated quantities block