# Copyright Contributors to the Pyro project.
# SPDX-License-Identifier: Apache-2.0
from typing import Optional
import jax
from jax import Array, lax, nn, random
import jax.numpy as jnp
from jax.scipy.special import betainc, betaln, gammaln, xlog1py, xlogy
from jax.typing import ArrayLike
from numpyro.distributions import constraints
from numpyro.distributions.constraints import Constraint
from numpyro.distributions.continuous import Beta, Dirichlet, Gamma
from numpyro.distributions.discrete import (
BinomialProbs,
HurdleProbs,
MultinomialProbs,
Poisson,
ZeroInflatedDistribution,
)
from numpyro.distributions.distribution import Distribution
from numpyro.distributions.util import (
promote_shapes,
promote_to_inexact,
validate_sample,
)
from numpyro.util import is_prng_key
def _log_beta_1(alpha, value):
# Note: support sparse `value`
return gammaln(1 + value) + gammaln(alpha) - gammaln(value + alpha)
[docs]
class BetaBinomial(Distribution):
r"""A Beta-Binomial compound distribution: the probability of success
(``probs`` for the :class:`~numpyro.distributions.Binomial` distribution)
is unknown and randomly drawn from a :class:`~numpyro.distributions.Beta`
distribution prior to a certain number of Bernoulli trials given by
``total_count``. Marginalizing out the success probability yields a
discrete distribution on :math:`\{0, 1, \dots, n\}` that is useful for
modeling overdispersed binomial count data.
The Probability Mass Function (PMF) of the Beta-Binomial distribution is
defined as:
.. math::
P(X = k \mid \alpha, \beta, n) =
\binom{n}{k} \frac{\mathrm{B}(k + \alpha,\ n - k + \beta)}
{\mathrm{B}(\alpha, \beta)},
\quad k \in \{0, 1, \dots, n\}
where :math:`\alpha` is :attr:`concentration1`, :math:`\beta` is
:attr:`concentration0`, :math:`n` is :attr:`total_count`, and
:math:`\mathrm{B}` is the beta function.
:param numpy.ndarray concentration1: 1st concentration parameter (alpha) for the
Beta distribution.
:param numpy.ndarray concentration0: 2nd concentration parameter (beta) for the
Beta distribution.
:param numpy.ndarray total_count: number of Bernoulli trials.
"""
arg_constraints = {
"concentration1": constraints.positive,
"concentration0": constraints.positive,
"total_count": constraints.nonnegative_integer,
}
has_enumerate_support = True
enumerate_support = BinomialProbs.enumerate_support
pytree_data_fields = ("concentration1", "concentration0", "total_count", "_beta")
def __init__(
self,
concentration1: ArrayLike,
concentration0: ArrayLike,
total_count: ArrayLike = 1,
*,
validate_args: Optional[bool] = None,
):
self.concentration1, self.concentration0, self.total_count = promote_shapes(
concentration1, concentration0, total_count
)
batch_shape = lax.broadcast_shapes(
jnp.shape(concentration1), jnp.shape(concentration0), jnp.shape(total_count)
)
concentration1 = jnp.broadcast_to(concentration1, batch_shape)
concentration0 = jnp.broadcast_to(concentration0, batch_shape)
self._beta = Beta(concentration1, concentration0)
super(BetaBinomial, self).__init__(batch_shape, validate_args=validate_args)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
r"""If :math:`X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)`, then the
sampling procedure is:
.. math::
\begin{align*}
p &\sim \mathrm{Beta}(\alpha, \beta) \\
X \mid p &\sim \mathrm{Binomial}(n, p)
\end{align*}
It uses :class:`~numpyro.distributions.continuous.Beta` to generate
samples from the Beta distribution and
:class:`~numpyro.distributions.discrete.BinomialProbs` to generate
samples from the Binomial distribution.
:param key: A JAX random number generator key (PRNG state).
:param sample_shape: Desired sample dimensions to prepend to the batch shape.
:return: Integer-valued samples in :math:`\{0, 1, \dots, n\}` drawn from
the Beta-Binomial distribution.
"""
assert key is not None
assert is_prng_key(key)
key_beta, key_binom = random.split(key)
probs = self._beta.sample(key_beta, sample_shape)
return BinomialProbs(total_count=self.total_count, probs=probs).sample(
key_binom
)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)`, then the
log probability mass function is:
.. math::
\ln P(X = k) =
\ln\Gamma(n + 1) - \ln\Gamma(k + 1) - \ln\Gamma(n - k + 1)
+ \ln\mathrm{B}(k + \alpha,\ n - k + \beta)
- \ln\mathrm{B}(\alpha, \beta)
To ensure differentiability, the binomial coefficient is computed using
gamma functions, and the beta-function terms are evaluated with
:func:`~jax.scipy.special.betaln`.
:param value: Number of successes :math:`k \in \{0, 1, \dots, n\}` to score.
:return: Log probability scores evaluated under the Beta-Binomial PMF.
"""
return (
-_log_beta_1(self.total_count - value + 1, value)
+ betaln(
value + self.concentration1,
self.total_count - value + self.concentration0,
)
- betaln(self.concentration0, self.concentration1)
)
@property
def mean(self) -> Array:
r"""If :math:`X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)`, then the
mean is:
.. math::
\mathbb{E}[X] = \frac{n\alpha}{\alpha + \beta}
"""
return self._beta.mean * self.total_count
@property
def variance(self) -> Array:
r"""If :math:`X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)`, then the
variance is:
.. math::
\mathrm{Var}[X] =
\frac{n\,\alpha\beta\,(\alpha + \beta + n)}
{(\alpha + \beta)^{2}\,(\alpha + \beta + 1)}
"""
return (
self._beta.variance
* self.total_count
* (self.concentration0 + self.concentration1 + self.total_count)
)
@constraints.dependent_property(is_discrete=True, event_dim=0)
def support(self) -> Constraint:
r"""The support of the Beta-Binomial distribution is the set of integers
:math:`\{0, 1, \dots, n\}`, where :math:`n` is :attr:`total_count`.
"""
return constraints.integer_interval(0, self.total_count)
[docs]
class BetaNegativeBinomial(Distribution):
r"""
Compound distribution comprising of a beta-negative-binomial pair. The ``probs``
parameter for the :class:`~numpyro.distributions.NegativeBinomialProbs` distribution
is unknown and randomly drawn from a :class:`~numpyro.distributions.Beta` distribution
prior to the negative binomial counting process.
The Beta Negative Binomial is a heavy-tailed discrete distribution useful for modeling
overdispersed count data. It arises as the marginal distribution when integrating out
the success probability in a negative binomial model with a beta prior.
:param numpy.ndarray concentration1: 1st concentration parameter (alpha) for the
Beta distribution.
:param numpy.ndarray concentration0: 2nd concentration parameter (beta) for the
Beta distribution.
:param numpy.ndarray n: positive number of successes parameter for the negative
binomial distribution.
**References**
[1] https://en.wikipedia.org/wiki/Beta_negative_binomial_distribution
[2] https://mc-stan.org/docs/functions-reference/unbounded_discrete_distributions.html#beta-neg-binomial
"""
arg_constraints = {
"concentration1": constraints.positive,
"concentration0": constraints.positive,
"n": constraints.positive,
}
support = constraints.nonnegative_integer
pytree_data_fields = ("concentration1", "concentration0", "n", "_beta")
def __init__(
self,
concentration1: ArrayLike,
concentration0: ArrayLike,
n: ArrayLike,
*,
validate_args: Optional[bool] = None,
):
self.concentration1, self.concentration0, self.n = promote_shapes(
concentration1, concentration0, n
)
batch_shape = lax.broadcast_shapes(
jnp.shape(concentration1), jnp.shape(concentration0), jnp.shape(n)
)
concentration1 = jnp.broadcast_to(concentration1, batch_shape)
concentration0 = jnp.broadcast_to(concentration0, batch_shape)
self._beta = Beta(concentration1, concentration0)
super(BetaNegativeBinomial, self).__init__(
batch_shape, validate_args=validate_args
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
r"""If :math:`X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)`, then the sampling
procedure is:
.. math::
\begin{align*}
p &\sim \mathrm{Beta}(\alpha, \beta) \\
X \mid p &\sim \mathrm{NegativeBinomial}(n, p)
\end{align*}
It uses :class:`~numpyro.distributions.continuous.Beta` to generate samples
from the Beta distribution and
:class:`~numpyro.distributions.discrete.NegativeBinomialProbs` to generate samples
from the Negative Binomial distribution.
"""
assert key is not None
assert is_prng_key(key)
key_beta, key_nb = random.split(key)
probs = self._beta.sample(key_beta, sample_shape)
return NegativeBinomialProbs(total_count=self.n, probs=probs).sample(key_nb)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)`, then the log
probability mass function is:
.. math::
P(X = k) = \binom{n + k - 1}{k} \frac{B(\alpha + k, \beta + n)}{B(\alpha, \beta)}
To ensure differentiability, the binomial coefficient is computed using
gamma functions.
"""
return (
gammaln(self.n + value)
- gammaln(self.n)
- gammaln(value + 1)
+ betaln(self.concentration1 + value, self.concentration0 + self.n)
- betaln(self.concentration1, self.concentration0)
)
@property
def mean(self) -> Array:
r"""If :math:`X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)` and
:math:`\beta > 1`, then the mean is:
.. math::
\mathbb{E}[X] = \frac{n\alpha}{\beta - 1},
otherwise, the its undefined.
"""
return jnp.where(
self.concentration0 > 1,
self.n * self.concentration1 / (self.concentration0 - 1),
jnp.inf,
)
@property
def variance(self) -> Array:
r"""If :math:`X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)` and
:math:`\beta > 2`, then the variance is:
.. math::
\mathrm{Var}[X] =
\frac{n\alpha (n + \beta - 1)(\alpha + \beta - 1)}{(\beta - 1)^2 \cdot (\beta - 2)},
otherwise, the its undefined.
"""
alpha = self.concentration1
beta = self.concentration0
n = self.n
var = (
n
* alpha
* (n + beta - 1)
* (alpha + beta - 1)
/ (jnp.square(beta - 1) * (beta - 2))
)
return jnp.where(beta > 2, var, jnp.inf)
[docs]
class DirichletMultinomial(Distribution):
r"""A Dirichlet-Multinomial compound distribution: the class probabilities
(``probs`` for the :class:`~numpyro.distributions.Multinomial` distribution)
are unknown and randomly drawn from a :class:`~numpyro.distributions.Dirichlet`
distribution prior to a certain number of Categorical trials given by
``total_count``. Marginalizing out the probability vector yields a discrete
distribution over count vectors that is useful for modeling overdispersed
multinomial count data.
The Probability Mass Function (PMF) of the Dirichlet-Multinomial
distribution is defined as:
.. math::
P(X = \mathbf{x} \mid \boldsymbol{\alpha}, n) =
\frac{n!}{\prod_{k=0}^{K-1} x_k!}
\frac{\mathrm{B}(\boldsymbol{\alpha} + \mathbf{x})}
{\mathrm{B}(\boldsymbol{\alpha})}
where :math:`\boldsymbol{\alpha} = (\alpha_0, \alpha_1, \dots, \alpha_{K-1})`
is the concentration vector (:attr:`concentration`), :math:`n` is the number
of trials (:attr:`total_count`),
:math:`\mathrm{B}(\boldsymbol{\alpha}) = \prod_k \Gamma(\alpha_k) /
\Gamma\!\bigl(\sum_k \alpha_k\bigr)` is the multivariate beta function, and
the count vector :math:`\mathbf{x}` satisfies
:math:`\sum_{k=0}^{K-1} x_k = n`.
:param numpy.ndarray concentration: concentration parameter (alpha) for the
Dirichlet distribution.
:param numpy.ndarray total_count: number of Categorical trials.
:param int total_count_max: the maximum number of trials, i.e. `max(total_count)`
"""
arg_constraints = {
"concentration": constraints.independent(constraints.positive, 1),
"total_count": constraints.nonnegative_integer,
}
pytree_data_fields = ("concentration", "_dirichlet")
pytree_aux_fields = ("total_count", "total_count_max")
def __init__(
self,
concentration: ArrayLike,
total_count: ArrayLike = 1,
*,
total_count_max: Optional[int] = None,
validate_args: Optional[bool] = None,
):
if jnp.ndim(concentration) < 1:
raise ValueError(
"`concentration` parameter must be at least one-dimensional."
)
batch_shape = lax.broadcast_shapes(
jnp.shape(concentration)[:-1], jnp.shape(total_count)
)
concentration_shape = batch_shape + jnp.shape(concentration)[-1:]
(self.concentration,) = promote_shapes(concentration, shape=concentration_shape)
(self.total_count,) = promote_shapes(total_count, shape=batch_shape)
self.total_count_max = total_count_max
concentration = jnp.broadcast_to(self.concentration, concentration_shape)
self._dirichlet = Dirichlet(concentration)
super().__init__(
self._dirichlet.batch_shape,
self._dirichlet.event_shape,
validate_args=validate_args,
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
r"""If :math:`X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)`,
then the sampling procedure is:
.. math::
\begin{align*}
\mathbf{p} &\sim \mathrm{Dirichlet}(\boldsymbol{\alpha}) \\
X \mid \mathbf{p} &\sim \mathrm{Multinomial}(n, \mathbf{p})
\end{align*}
It uses :class:`~numpyro.distributions.continuous.Dirichlet` to generate
samples from the Dirichlet distribution and
:class:`~numpyro.distributions.discrete.MultinomialProbs` to generate
samples from the Multinomial distribution.
:param key: A JAX random number generator key (PRNG state).
:param sample_shape: Desired sample dimensions to prepend to the batch shape.
:return: Integer count vectors :math:`\mathbf{x}` with
:math:`\sum_{k=0}^{K-1} x_k =` :attr:`total_count`, drawn from the
Dirichlet-Multinomial distribution.
"""
assert key is not None
assert is_prng_key(key)
key_dirichlet, key_multinom = random.split(key)
probs = self._dirichlet.sample(key_dirichlet, sample_shape)
return MultinomialProbs(
total_count=self.total_count,
probs=probs,
total_count_max=self.total_count_max,
).sample(key_multinom)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)`,
then the log probability mass function is:
.. math::
\ln P(X = \mathbf{x}) =
\ln\Gamma(n + 1) + \ln\Gamma(A) - \ln\Gamma(n + A)
- \sum_{k=0}^{K-1} \left[
\ln\Gamma(x_k + 1) + \ln\Gamma(\alpha_k)
- \ln\Gamma(x_k + \alpha_k)
\right]
where :math:`n` is :attr:`total_count` and
:math:`A = \sum_{k=0}^{K-1} \alpha_k`. To ensure differentiability, the
factorial terms are computed using
:func:`~jax.scipy.special.gammaln`.
:param value: Count vector :math:`\mathbf{x}` whose last dimension has
size :math:`K` and sums to :attr:`total_count`.
:return: Log probability scores evaluated under the
Dirichlet-Multinomial PMF.
"""
alpha = self.concentration
return _log_beta_1(jnp.sum(alpha, -1), jnp.sum(value, -1)) - jnp.sum(
_log_beta_1(alpha, value), -1
)
@property
def mean(self) -> Array:
r"""If :math:`X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)`,
then the mean is:
.. math::
\mathbb{E}[X_k] = n\,\frac{\alpha_k}{A},
\quad k \in \{0, 1, \dots, K-1\}
where :math:`A = \sum_{k=0}^{K-1} \alpha_k`.
"""
return self._dirichlet.mean * jnp.expand_dims(self.total_count, -1)
@property
def variance(self) -> Array:
r"""If :math:`X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)`,
then the variance is:
.. math::
\mathrm{Var}[X_k] =
n\,\frac{\alpha_k}{A}\left(1 - \frac{\alpha_k}{A}\right)
\frac{n + A}{1 + A},
\quad k \in \{0, 1, \dots, K-1\}
where :math:`A = \sum_{k=0}^{K-1} \alpha_k`.
"""
n = jnp.expand_dims(self.total_count, -1)
alpha = self.concentration
alpha_sum = self.concentration.sum(-1, keepdims=True)
alpha_ratio = alpha / alpha_sum
return n * alpha_ratio * (1 - alpha_ratio) * (n + alpha_sum) / (1 + alpha_sum)
@constraints.dependent_property(is_discrete=True, event_dim=1)
def support(self) -> Constraint:
r"""The support of the Dirichlet-Multinomial distribution is the set of
count vectors :math:`\mathbf{x} \in \{0, 1, \dots, n\}^K` whose entries
sum to :attr:`total_count` :math:`n`.
"""
return constraints.multinomial(self.total_count)
[docs]
@classmethod
def infer_shapes(
cls, concentration: tuple[int, ...], total_count: tuple[int, ...] = ()
) -> tuple[tuple[int, ...], tuple[int, ...]]:
batch_shape = lax.broadcast_shapes(concentration[:-1], total_count)
event_shape = concentration[-1:]
return batch_shape, event_shape
[docs]
class GammaPoisson(Distribution):
r"""
Compound distribution comprising of a gamma-poisson pair, also referred to as
a gamma-poisson mixture. The ``rate`` parameter for the
:class:`~numpyro.distributions.Poisson` distribution is unknown and randomly
drawn from a :class:`~numpyro.distributions.Gamma` distribution.
:param numpy.ndarray concentration: shape parameter (alpha) of the Gamma distribution.
:param numpy.ndarray rate: rate parameter (rate) for the Gamma distribution.
"""
arg_constraints = {
"concentration": constraints.positive,
"rate": constraints.positive,
}
support = constraints.nonnegative_integer
pytree_data_fields = ("concentration", "rate", "_gamma")
def __init__(
self,
concentration: ArrayLike,
rate: ArrayLike = 1.0,
*,
validate_args: Optional[bool] = None,
):
self.concentration, self.rate = promote_shapes(concentration, rate)
batch_shape = lax.broadcast_shapes(jnp.shape(concentration), jnp.shape(rate))
# Validate this distribution's own parameters before building the internal
# Gamma, so that an invalid rate is reported against the public class.
super(GammaPoisson, self).__init__(batch_shape, validate_args=validate_args)
self._gamma = Gamma(concentration, rate)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
r"""If :math:`X \sim \mathrm{GammaPoisson}(\alpha, \lambda)`, then the sampling
procedure is:
.. math::
\begin{align*}
\theta &\sim \mathrm{Gamma}(\alpha, \lambda) \\
X \mid \theta &\sim \mathrm{Poisson}(\theta)
\end{align*}
It uses :class:`~numpyro.distributions.continuous.Gamma` to generate samples
from the Gamma distribution and
:class:`~numpyro.distributions.continuous.Poisson` to generate samples from the
Poisson distribution.
"""
assert key is not None
assert is_prng_key(key)
key_gamma, key_poisson = random.split(key)
rate = self._gamma.sample(key_gamma, sample_shape)
return Poisson(rate).sample(key_poisson)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{GammaPoisson}(\alpha, \lambda)`, then the
probability mass function is:
.. math::
p_{X}(k) = \frac{\lambda^\alpha}{(\alpha + k)(1+\lambda)^{\alpha + k}\mathrm{B}(\alpha, k + 1)}
"""
dtype = jnp.result_type(float)
concentration = jnp.array(self.concentration, dtype=dtype)
rate = jnp.array(self.rate, dtype=dtype)
value = jnp.array(value, dtype=dtype)
post_value = concentration + value
return (
-betaln(concentration, value + 1)
- jnp.log(post_value)
+ xlogy(-concentration, 1 + 1 / rate)
- xlog1py(value, rate)
)
@property
def mean(self) -> Array:
r"""If :math:`X \sim \mathrm{GammaPoisson}(\alpha, \lambda)`, then the mean is:
.. math::
\mathbb{E}[X] = \frac{\alpha}{\lambda}
"""
return jnp.asarray(self.concentration / self.rate)
@property
def variance(self) -> Array:
r"""If :math:`X \sim \mathrm{GammaPoisson}(\alpha, \lambda)`, then the variance is:
.. math::
\mathrm{Var}[X] = \frac{\alpha}{\lambda^2}(1 + \lambda)
"""
return jnp.asarray(self.concentration / self.rate * (1 + 1 / self.rate))
[docs]
def cdf(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{GammaPoisson}(\alpha, \lambda)`, then the cumulative
distribution function, for :math:`k = \lfloor x \rfloor \geq 0`, is:
.. math::
F_{X}(x) = \frac{1}{\mathrm{B}(\alpha, k + 1)}
\int_{0}^{\frac{\lambda}{1 + \lambda}} t^{\alpha - 1} (1 - t)^{k} dt
which is the regularized incomplete beta function. The CDF is zero for
:math:`x < 0` and one at :math:`x = \infty`.
This implementation uses :func:`~jax.scipy.special.betainc`, which does not
support gradients with respect to its first argument, so the CDF is not
differentiable with respect to ``concentration``.
"""
rate_fraction = jnp.where(
jnp.isinf(self.rate),
jnp.ones_like(self.rate),
self.rate / (self.rate + 1.0),
)
value = jnp.floor(value)
is_negative = value < 0
is_inf = jnp.isposinf(value)
# betainc returns NaN for b close to the largest float, so clamp huge thresholds.
dtype = jnp.result_type(self.concentration, value, rate_fraction, float)
max_value = jnp.sqrt(jnp.finfo(dtype).max)
safe_value = jnp.where(is_negative | is_inf, 0.0, jnp.minimum(value, max_value))
bt = betainc(self.concentration, safe_value + 1.0, rate_fraction)
return jnp.where(is_negative, 0.0, jnp.where(is_inf, 1.0, bt))
[docs]
def NegativeBinomial(
total_count: ArrayLike,
probs: Optional[ArrayLike] = None,
logits: Optional[ArrayLike] = None,
*,
validate_args: Optional[bool] = None,
) -> GammaPoisson:
r"""Factory function for the Negative Binomial distribution.
:math:`X \sim \mathrm{NB}(r, p)` counts the successes (probability :math:`p` each)
observed before the :math:`r`-th failure of a sequence of Bernoulli trials,
.. math::
P(X = k \mid r, p) = \frac{\Gamma(k + r)}{k!\,\Gamma(r)}\,(1 - p)^{r}\,p^{k},
\qquad k \in \mathbb{N},
with
.. math::
\mathbb{E}[X] = \frac{r p}{1 - p}, \qquad
\operatorname{Var}[X] = \frac{r p}{(1 - p)^2}, \qquad
F(k) = P(X \le k) = I_{1 - p}(r, k + 1),
where :math:`I_x(a, b)` is the regularized incomplete beta function. With
``logits`` :math:`z`, :math:`p = \sigma(z)` and :math:`\mathbb{E}[X] = r e^{z}`.
The Negative Binomial is the Gamma–Poisson mixture
:math:`\lambda \sim \mathrm{Gamma}(r, \tfrac{1 - p}{p}),\ X \mid \lambda \sim
\mathrm{Poisson}(\lambda)`.
.. note::
Both returned classes subclass :class:`GammaPoisson` and sample as
Gamma→Poisson; the cdf is :meth:`GammaPoisson.cdf`.
:class:`NegativeBinomialLogits` evaluates ``log_prob``/``mean``/``variance``
directly in terms of the logits so that :math:`z = -\infty` is exact.
If both ``probs`` and ``logits`` are given, ``probs`` is used and ``logits``
is ignored.
:param total_count: Number of failures :math:`r > 0` at which the Bernoulli trials
stop (need not be an integer).
:param Optional[ArrayLike] probs: Success probability :math:`p` of each trial, by
default None.
:param Optional[ArrayLike] logits: Log-odds :math:`z = \log\frac{p}{1-p}`;
:math:`-\infty` puts all mass at zero. By default None.
:param Optional[bool] validate_args: Whether to validate the parameters, by default None
:return: An instance of :class:`NegativeBinomialProbs` or
:class:`NegativeBinomialLogits` depending on the provided parameters.
:rtype: GammaPoisson
:raises ValueError: If neither :code:`probs` nor :code:`logits` is specified.
"""
if probs is not None:
return NegativeBinomialProbs(total_count, probs, validate_args=validate_args)
elif logits is not None:
return NegativeBinomialLogits(total_count, logits, validate_args=validate_args)
else:
raise ValueError("One of `probs` or `logits` must be specified.")
[docs]
class NegativeBinomialProbs(GammaPoisson):
r"""Negative Binomial distribution parameterized by :code:`total_count` (:math:`r`)
and :code:`probs` (:math:`p`). It is implemented as a
:math:`\displaystyle\mathrm{GammaPoisson}(n, \frac{1}{p} - 1)` distribution.
:param total_count: Number of successful trials (:math:`r`).
:param probs: Probability of success for each trial (:math:`p`).
"""
arg_constraints = {
"total_count": constraints.positive,
"probs": constraints.unit_interval,
}
support = constraints.nonnegative_integer
def __init__(
self,
total_count: ArrayLike,
probs: ArrayLike,
*,
validate_args: Optional[bool] = None,
):
self.total_count, self.probs = promote_shapes(total_count, probs)
concentration = total_count
rate = jnp.divide(1.0, probs) - 1.0
super().__init__(concentration, rate, validate_args=validate_args)
[docs]
class NegativeBinomialLogits(GammaPoisson):
r"""Negative Binomial distribution parameterized by :code:`total_count` (:math:`r`)
and :code:`logits` (:math:`\displaystyle\mathrm{logits}(p)=\log \frac{p}{1-p}`). It
is implemented as a :math:`\mathrm{GammaPoisson}(n, \exp(-\mathrm{logits}(p)))`
distribution.
:param total_count: Number of successful trials.
:param logits: Log-odds parameter (:math:`\ln \frac{p}{1-p}`) in
:math:`[-\infty, \infty)`; :math:`-\infty` puts all mass at zero.
"""
arg_constraints = {
"total_count": constraints.positive,
# +inf is a Gamma rate of zero, which has no normalizer.
"logits": constraints.less_than(float("inf")),
}
support = constraints.nonnegative_integer
def __init__(
self,
total_count: ArrayLike,
logits: ArrayLike,
*,
validate_args: Optional[bool] = None,
):
logits = promote_to_inexact(logits)
self.total_count, self.logits = promote_shapes(total_count, logits)
concentration = total_count
rate = jnp.exp(jnp.negative(logits))
super().__init__(concentration, rate, validate_args=validate_args)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""If :math:`X \sim \mathrm{NegativeBinomial}(r, \mathrm{logits}(p))`, then the log
probability mass function is:
.. math::
\ln P(X = k) = -r \ln(1+\exp(\mathrm{logits}(p)))
- k \ln(1+\exp(-\mathrm{logits}(p)))
- \ln\Gamma(1 + k) - \ln\Gamma(\alpha) + \ln\Gamma(k + \alpha)
"""
# A zero count contributes nothing even where softplus(-logits) is infinite.
log_1mp = jnp.where(value == 0, 0.0, nn.softplus(-self.logits))
return -(
self.total_count * nn.softplus(self.logits)
+ value * log_1mp
+ _log_beta_1(self.total_count, value)
)
@property
def mean(self) -> Array:
# r exp(logits), rather than concentration / rate with rate = exp(-logits),
# whose gradient is 0 * inf at logits = -inf.
return self.total_count * jnp.exp(self.logits)
@property
def variance(self) -> Array:
return self.mean * (1 + jnp.exp(self.logits))
[docs]
class NegativeBinomial2(GammaPoisson):
r"""If :math:`X \sim \mathrm{NegativeBinomial2}(\mu, \alpha)`, then
:math:`X \sim \mathrm{GammaPoisson}(\alpha, \frac{\alpha}{\mu})`.
:param numpy.ndarray mean: mean parameter (:math:`\mu`).
:param numpy.ndarray concentration: concentration parameter (:math:`\alpha`).
"""
arg_constraints = {
"mean": constraints.nonnegative,
"concentration": constraints.positive,
}
support = constraints.nonnegative_integer
pytree_data_fields = ("concentration",)
def __init__(
self,
mean: ArrayLike,
concentration: ArrayLike,
*,
validate_args: Optional[bool] = None,
):
rate = jnp.divide(concentration, mean)
super().__init__(concentration, rate, validate_args=validate_args)
class _HurdleNegativeBinomial2(NegativeBinomial2):
arg_constraints = {
**NegativeBinomial2.arg_constraints,
"mean": constraints.positive,
}
[docs]
def ZeroInflatedNegativeBinomial2(
mean: ArrayLike,
concentration: ArrayLike,
*,
gate: Optional[ArrayLike] = None,
gate_logits: Optional[ArrayLike] = None,
validate_args: Optional[bool] = None,
):
r"""A zero-inflated Negative Binomial distribution (NB2 / mean-dispersion
parameterization).
A zero-inflated :class:`~numpyro.distributions.conjugate.NegativeBinomial2`
mixes a point mass at zero (the *structural* or *excess* zeros) with a
Negative Binomial count distribution, allowing the number of zeros to exceed
what a plain Negative Binomial would produce. With gate :math:`g` (the
probability of a structural zero), mean :math:`\mu` and concentration
:math:`\alpha`, the probability mass function is
.. math::
P(X = 0) = g + (1 - g)\, \mathrm{NB2}(0 \mid \mu, \alpha), \qquad
P(X = k) = (1 - g)\, \mathrm{NB2}(k \mid \mu, \alpha)
\;\text{for } k \geq 1,
where :math:`\mathrm{NB2}(\cdot \mid \mu, \alpha)` is the PMF of the
:class:`~numpyro.distributions.conjugate.NegativeBinomial2` distribution,
.. math::
\mathrm{NB2}(k \mid \mu, \alpha) =
\frac{\Gamma(k + \alpha)}{k!\, \Gamma(\alpha)}
\left(\frac{\alpha}{\alpha + \mu}\right)^{\alpha}
\left(\frac{\mu}{\alpha + \mu}\right)^{k}.
A zero therefore arises either from the structural component (with
probability :math:`g`) or as a sampling zero from the Negative Binomial
component (with probability
:math:`(1 - g)\, \mathrm{NB2}(0 \mid \mu, \alpha)`, where
:math:`\mathrm{NB2}(0 \mid \mu, \alpha) = (\alpha / (\alpha + \mu))^{\alpha}`).
The mean and variance are
.. math::
\mathbb{E}[X] = (1 - g)\, \mu, \qquad
\operatorname{Var}(X) = (1 - g)\, \mu
\left(1 + \frac{\mu}{\alpha} + g\, \mu\right).
Compared with a zero-inflated Poisson, the Negative Binomial component also
accommodates over-dispersion among the non-structural counts (its variance is
:math:`\mu + \mu^2 / \alpha`). For :math:`g = 0` the distribution reduces to
:class:`~numpyro.distributions.conjugate.NegativeBinomial2`.
The gate must be specified either as a probability ``gate`` :math:`= g` or as
logits ``gate_logits`` :math:`= \ell`, with :math:`g = 1 / (1 + e^{-\ell})`.
Exactly one of the two is required, as for
:func:`~numpyro.distributions.discrete.ZeroInflatedDistribution`.
:param numpy.ndarray mean: mean :math:`\mu` of the NegativeBinomial2 component.
:param numpy.ndarray concentration: concentration (dispersion) :math:`\alpha`
of the NegativeBinomial2 component.
:param numpy.ndarray gate: probability of extra (structural) zeros, in
:math:`[0, 1]`.
:param numpy.ndarray gate_logits: logits of the probability of extra
(structural) zeros.
"""
return ZeroInflatedDistribution(
NegativeBinomial2(mean, concentration, validate_args=validate_args),
gate=gate,
gate_logits=gate_logits,
validate_args=validate_args,
)
[docs]
def HurdleNegativeBinomial2(
gate: ArrayLike,
mean: ArrayLike,
concentration: ArrayLike,
*,
validate_args: Optional[bool] = None,
) -> HurdleProbs:
r"""A hurdle Negative Binomial distribution (NB2 / mean-dispersion
parameterization): a two-part model in which structural zeros are produced
by a Bernoulli "hurdle" with probability :math:`g` and positive counts
follow a zero-truncated :math:`\mathrm{NegativeBinomial2}(\mu, \alpha)`.
The hurdle and the magnitude (given a positive count) are conditionally
independent; see :class:`HurdleProbs` for the full mechanism and
assumptions. Compared to a Hurdle Poisson, NB2 accommodates count data
that is over-dispersed (variance greater than the mean).
The probability mass function is
.. math::
P(X = 0) = g, \qquad
P(X = k) = (1 - g) \, \frac{\mathrm{NB2}(k\mid\mu, \alpha)}
{1 - \mathrm{NB2}(0\mid\mu, \alpha)} \;\text{for } k \geq 1,
where :math:`\mathrm{NB2}(\cdot\mid\mu, \alpha)` is the PMF of a Negative Binomial
distribution with mean :math:`\mu` and concentration (dispersion) :math:`\alpha`.
:param ArrayLike gate: probability of a structural zero, :math:`g \in [0, 1]`.
:param ArrayLike mean: mean :math:`\mu > 0` of the underlying NegativeBinomial2.
:param ArrayLike concentration: concentration :math:`\alpha > 0`.
**References:**
1. Mullahy, J. (1986). Specification and testing of some modified count
data models. *Journal of Econometrics*, 33(3), 341-365.
2. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent
Variables with Application to the Demand for Durable Goods.
*Econometrica*, 39(5), 829-844.
"""
return HurdleProbs(
_HurdleNegativeBinomial2(mean, concentration, validate_args=validate_args),
gate,
validate_args=validate_args,
)