Source code for hybrid_aif.distributions.categorical

"""Categorical distribution over ``num_levels`` outcomes.

Stored parameterization: ``logits`` (unnormalized log-probabilities), the natural
parameters up to an additive gauge constant — numerically safest for softmax/log
arithmetic and what conjugate updates against Dirichlet counts want to touch.
Event shape: ``()`` (samples are integer indices); the ``logits`` trailing axis
is the level (parameter) axis.
"""

import jax
import jax.numpy as jnp
from jax import Array

from hybrid_aif.distributions.base import ExponentialFamily
from hybrid_aif.interval import Interval


[docs] class Categorical(ExponentialFamily): """A categorical distribution over ``num_levels`` outcomes, batched over leading axes. Stored as ``logits``; the event shape is ``()``: a sample or a ``log_prob`` argument is an integer level index. :attr:`probs` and :attr:`log_probs` give the normalised table, :meth:`from_probs` builds one from probabilities, :meth:`mean` is the probability vector, and :meth:`natural` pins the last level's logit to zero (the gauge choice). """ #: Unnormalized log-probabilities, ``(..., num_levels)``: the natural parameters up to an #: additive gauge constant per batch entry. The trailing axis is the level axis. logits: Array @property def batch_shape(self) -> tuple[int, ...]: return self.logits.shape[:-1] @property def num_levels(self) -> int: return self.logits.shape[-1] @property def log_probs(self) -> Array: return jax.nn.log_softmax(self.logits, axis=-1) @property def probs(self) -> Array: return jax.nn.softmax(self.logits, axis=-1) @classmethod def from_probs(cls, probs: Array) -> "Categorical": return cls(logits=jnp.log(probs))
[docs] def log_prob(self, x: Array) -> Array: return jnp.take_along_axis(self.log_probs, x[..., None].astype(jnp.int32), axis=-1)[..., 0]
[docs] def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array: z = jax.random.categorical(key, self.logits, shape=sample_shape + self.batch_shape) return z.astype(jnp.int32)
[docs] def mean(self) -> Array: """Moment view: the probability vector (one-hot expectation).""" return self.probs
[docs] def entropy(self) -> Interval: lp = self.log_probs return Interval.exact(-jnp.sum(jnp.exp(lp) * lp, axis=-1))
[docs] def kl_to(self, other: "Categorical") -> Interval: p, lp, lq = self.probs, self.log_probs, other.log_probs return Interval.exact(jnp.sum(p * (lp - lq), axis=-1))
[docs] def natural(self) -> tuple[Array, ...]: """Logits with the last state pinned to zero (gauge choice).""" return (self.logits - self.logits[..., -1:],)
[docs] @classmethod def from_natural(cls, logits: Array) -> "Categorical": return cls(logits=logits)