# Copyright Contributors to the Pyro project.
# SPDX-License-Identifier: Apache-2.0
import math
from typing import Callable, Optional, Union, cast
import jax
from jax import Array, lax
import jax.numpy as jnp
import jax.random as random
from jax.scipy.special import gammainc, gammaincc, logsumexp
from jax.typing import ArrayLike
from numpyro._typing import NumLike
from numpyro.distributions import constraints
from numpyro.distributions.constraints import Constraint
from numpyro.distributions.continuous import (
Cauchy,
Gamma,
Laplace,
Logistic,
Normal,
SoftLaplace,
StudentT,
)
from numpyro.distributions.distribution import Distribution
from numpyro.distributions.util import (
clamp_probs,
lazy_property,
promote_shapes,
validate_sample,
)
from numpyro.util import is_prng_key
def _at_bound(
fn: Callable[[Array], Array], bound: Array, inside: Array, limit: ArrayLike
) -> Array:
"""``fn(bound)``, replaced by ``limit`` where ``bound`` is infinite.
``fn`` is evaluated at ``inside`` there, so its infinite derivative at an infinite
bound cannot reach the gradient as ``0 * inf``. ``inside`` must be a point where
``fn`` is differentiable: for a CDF use ``loc + scale`` (StudentT's CDF has a nan
derivative at ``loc``); for a density, any point inside the support.
"""
unbounded = jnp.isinf(bound)
return jnp.where(unbounded, limit, fn(jnp.where(unbounded, inside, bound)))
[docs]
class LeftTruncatedDistribution(Distribution):
r"""A symmetric location-scale base distribution :math:`f` truncated from below at ``low``.
.. math::
p(x \mid a) = \frac{f(x)}{1 - F(a)}, \qquad x \geq a,
where :math:`F` is the cdf of the base distribution and :math:`a` is ``low``.
:param base_dist: one of :class:`~numpyro.distributions.continuous.Cauchy`,
:class:`~numpyro.distributions.continuous.Laplace`,
:class:`~numpyro.distributions.continuous.Logistic`,
:class:`~numpyro.distributions.continuous.Normal`,
:class:`~numpyro.distributions.continuous.SoftLaplace` or
:class:`~numpyro.distributions.continuous.StudentT` instance.
:param low: the value at which the base distribution is truncated from below.
.. note::
``mean`` and ``variance`` are only computed for a ``Normal`` base; a ``Cauchy``
base returns ``nan`` and any other base raises ``NotImplementedError``.
"""
# [-inf, inf): -inf truncates nothing; +inf would leave an empty support.
arg_constraints = {"low": constraints.less_than(float("inf"))}
reparametrized_params = ["low"]
supported_types = (Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT)
pytree_data_fields = ("base_dist", "low", "_support")
_support: constraints.Constraint
def __init__(
self,
base_dist: Union[Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT],
low: ArrayLike = 0.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types), (
f"{type(base_dist).__name__} is not supported by this class; for a Gamma "
"base distribution use numpyro.distributions.TruncatedGamma."
)
assert base_dist.support is constraints.real, (
"The base distribution should be univariate and have real support."
)
batch_shape = lax.broadcast_shapes(base_dist.batch_shape, jnp.shape(low))
self.base_dist: Union[
Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT
] = jax.tree.map(lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist)
(self.low,) = promote_shapes(low, shape=batch_shape)
self._support = constraints.greater_than_eq(cast(NumLike, low))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _tail_prob_at_low(self):
# if low < loc, returns cdf(low); otherwise returns 1 - cdf(low)
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
return _at_bound(
lambda x: self.base_dist.cdf(loc - sign * (loc - x)),
self.low,
loc + self.base_dist.scale,
0.0,
)
@lazy_property
def _tail_prob_at_high(self):
# if low < loc, returns cdf(high) = 1; otherwise returns 1 - cdf(high) = 0
return jnp.where(self.low <= self.base_dist.loc, 1.0, 0.0)
@lazy_property
def _prob_at_low(self) -> Array:
# Density at the bound, which is zero at an infinite bound.
return _at_bound(
lambda x: jnp.exp(self.log_prob(x)), self.low, self.base_dist.loc, 0.0
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
ppf = (1 - sign) * loc + sign * self.base_dist.icdf(
(1 - q) * self._tail_prob_at_low + q * self._tail_prob_at_high
)
return jnp.where(jnp.less(q, 0), jnp.nan, ppf)
[docs]
def cdf(self, value: ArrayLike) -> Array:
# For left truncated distribution: CDF(x) = (F(x) - F(low)) / (1 - F(low))
# where F is the base distribution CDF.
# Translating low into the tail probability T(low) = 1 - F(low) (which we
# get by reflecting low through loc) makes the formula stable when the
# truncation point is in the upper tail, where F(low) rounds to 1.
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
tail_prob_value = self.base_dist.cdf(loc - sign * (loc - value))
truncated_cdf = (tail_prob_value - self._tail_prob_at_low) / (
self._tail_prob_at_high - self._tail_prob_at_low
)
# Clamp to [0, 1] and handle values below the truncation point
result = jnp.where(
jnp.less(value, self.low), 0.0, jnp.clip(truncated_cdf, 0.0, 1.0)
)
return result
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
sign = jnp.where(self.base_dist.loc >= self.low, 1.0, -1.0)
return self.base_dist.log_prob(value) - jnp.log(
sign * (self._tail_prob_at_high - self._tail_prob_at_low)
)
@property
def mean(self) -> Array:
if isinstance(self.base_dist, Normal):
return self.base_dist.loc + self._prob_at_low * self.base_dist.scale**2
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("mean only available for Normal and Cauchy")
@property
def variance(self) -> Array:
if isinstance(self.base_dist, Normal):
loc = self.base_dist.loc
low_prob = self._prob_at_low
return (self.base_dist.scale**2) * (
1
+ jnp.where(jnp.isinf(self.low), 0.0, self.low - loc) * low_prob
- (low_prob * self.base_dist.scale) ** 2
)
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("variance only available for Normal and Cauchy")
[docs]
class RightTruncatedDistribution(Distribution):
r"""A symmetric location-scale base distribution :math:`f` truncated from above at ``high``.
.. math::
p(x \mid b) = \frac{f(x)}{F(b)}, \qquad x \leq b,
where :math:`F` is the cdf of the base distribution and :math:`b` is ``high``.
:param base_dist: one of :class:`~numpyro.distributions.continuous.Cauchy`,
:class:`~numpyro.distributions.continuous.Laplace`,
:class:`~numpyro.distributions.continuous.Logistic`,
:class:`~numpyro.distributions.continuous.Normal`,
:class:`~numpyro.distributions.continuous.SoftLaplace` or
:class:`~numpyro.distributions.continuous.StudentT` instance.
:param high: the value at which the base distribution is truncated from above.
.. note::
``mean`` and ``variance`` are only computed for a ``Normal`` base; a ``Cauchy``
base returns ``nan`` and any other base raises ``NotImplementedError``.
"""
# (-inf, inf]: +inf truncates nothing; -inf would leave an empty support.
arg_constraints = {"high": constraints.greater_than(-float("inf"))}
reparametrized_params = ["high"]
supported_types = (Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT)
pytree_data_fields = ("base_dist", "high", "_support")
_support: constraints.Constraint
def __init__(
self,
base_dist: Union[Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT],
high: ArrayLike = 0.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types), (
f"{type(base_dist).__name__} is not supported by this class; for a Gamma "
"base distribution use numpyro.distributions.TruncatedGamma."
)
assert base_dist.support is constraints.real, (
"The base distribution should be univariate and have real support."
)
batch_shape = lax.broadcast_shapes(base_dist.batch_shape, jnp.shape(high))
self.base_dist: Union[
Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT
] = jax.tree.map(lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist)
(self.high,) = promote_shapes(high, shape=batch_shape)
self._support = constraints.less_than_eq(cast(NumLike, high))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _cdf_at_high(self) -> Array:
safe = self.base_dist.loc + self.base_dist.scale
return _at_bound(self.base_dist.cdf, self.high, safe, 1.0)
@lazy_property
def _prob_at_high(self) -> Array:
# Density at the bound, which is zero at an infinite bound.
return _at_bound(
lambda x: jnp.exp(self.log_prob(x)), self.high, self.base_dist.loc, 0.0
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
ppf = self.base_dist.icdf(q * self._cdf_at_high)
return jnp.where(jnp.greater(q, 1), jnp.nan, ppf)
[docs]
def cdf(self, value: ArrayLike) -> Array:
# For right truncated distribution: CDF(x) = F(x) / F(high)
# where F is the base distribution CDF
base_cdf_value = self.base_dist.cdf(value)
base_cdf_high = self._cdf_at_high
# Handle the case where value > high (should be 1)
# and value <= high (should be the truncated CDF)
truncated_cdf = base_cdf_value / base_cdf_high
# Clamp to [0, 1] and handle values above the truncation point
result = jnp.where(
jnp.greater(value, self.high), 1.0, jnp.clip(truncated_cdf, 0.0, 1.0)
)
return result
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
return self.base_dist.log_prob(value) - jnp.log(self._cdf_at_high)
@property
def mean(self) -> Array:
if isinstance(self.base_dist, Normal):
return self.base_dist.loc - self._prob_at_high * self.base_dist.scale**2
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("mean only available for Normal and Cauchy")
@property
def variance(self) -> Array:
if isinstance(self.base_dist, Normal):
loc = self.base_dist.loc
high_prob = self._prob_at_high
return (self.base_dist.scale**2) * (
1
- jnp.where(jnp.isinf(self.high), 0.0, self.high - loc) * high_prob
- (high_prob * self.base_dist.scale) ** 2
)
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("variance only available for Normal and Cauchy")
[docs]
class TwoSidedTruncatedDistribution(Distribution):
r"""A symmetric location-scale base distribution :math:`f` truncated to ``[low, high]``.
.. math::
p(x \mid a, b) = \frac{f(x)}{F(b) - F(a)}, \qquad a \leq x \leq b,
where :math:`F` is the cdf of the base distribution, :math:`a` is ``low`` and
:math:`b` is ``high``.
:param base_dist: one of :class:`~numpyro.distributions.continuous.Cauchy`,
:class:`~numpyro.distributions.continuous.Laplace`,
:class:`~numpyro.distributions.continuous.Logistic`,
:class:`~numpyro.distributions.continuous.Normal`,
:class:`~numpyro.distributions.continuous.SoftLaplace` or
:class:`~numpyro.distributions.continuous.StudentT` instance.
:param low: the lower truncation point.
:param high: the upper truncation point.
.. note::
``mean`` and ``variance`` are only computed for a ``Normal`` base; a ``Cauchy``
base returns ``nan`` and any other base raises ``NotImplementedError``.
"""
arg_constraints = {
"low": constraints.dependent(is_discrete=False, event_dim=0),
"high": constraints.dependent(is_discrete=False, event_dim=0),
}
reparametrized_params = ["low", "high"]
supported_types = (Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT)
pytree_data_fields = ("base_dist", "low", "high", "_support")
_support: constraints.Constraint
def __init__(
self,
base_dist: Union[Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT],
low: ArrayLike = 0.0,
high: ArrayLike = 1.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types), (
f"{type(base_dist).__name__} is not supported by this class; for a Gamma "
"base distribution use numpyro.distributions.TruncatedGamma."
)
assert base_dist.support is constraints.real, (
"The base distribution should be univariate and have real support."
)
batch_shape = lax.broadcast_shapes(
base_dist.batch_shape, jnp.shape(low), jnp.shape(high)
)
self.base_dist: Union[
Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT
] = jax.tree.map(lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist)
(self.low,) = promote_shapes(low, shape=batch_shape)
(self.high,) = promote_shapes(high, shape=batch_shape)
self._support = constraints.interval(cast(NumLike, low), cast(NumLike, high))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _tail_prob_at_low(self) -> Array:
# if low < loc, returns cdf(low); otherwise returns 1 - cdf(low)
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
return _at_bound(
lambda x: self.base_dist.cdf(loc - sign * (loc - x)),
self.low,
loc + self.base_dist.scale,
0.0,
)
@lazy_property
def _tail_prob_at_high(self) -> Array:
# if low < loc, returns cdf(high); otherwise returns 1 - cdf(high)
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
return _at_bound(
lambda x: self.base_dist.cdf(loc - sign * (loc - x)),
self.high,
loc + self.base_dist.scale,
jnp.where(sign > 0, 1.0, 0.0),
)
@lazy_property
def _prob_at_low(self) -> Array:
# Density at the bound, which is zero at an infinite bound. The fallback point
# must lie inside the support, since log_prob validates its input.
inside = jnp.clip(self.base_dist.loc, self.low, self.high)
return _at_bound(lambda x: jnp.exp(self.log_prob(x)), self.low, inside, 0.0)
@lazy_property
def _prob_at_high(self) -> Array:
inside = jnp.clip(self.base_dist.loc, self.low, self.high)
return _at_bound(lambda x: jnp.exp(self.log_prob(x)), self.high, inside, 0.0)
@lazy_property
def _log_diff_tail_probs(self) -> Array:
# use log_cdf method, if available, to avoid inf's in log_prob
# fall back to cdf, if log_cdf not available
log_cdf = getattr(self.base_dist, "log_cdf", None)
if callable(log_cdf):
loc = self.base_dist.loc
# when the interval lies in the upper tail (low >= loc), reflect
# both endpoints through loc and use the accurate lower-tail
# log_cdf of the reflected values: log_cdf(low) - log_cdf(high)
# would otherwise lose all precision, making log_prob +inf.
reflect = self.low >= loc
p_first = jnp.where(reflect, 2 * loc - self.low, self.high)
p_second = jnp.where(reflect, 2 * loc - self.high, self.low)
# An infinite bound lands in p_first as +inf (log_cdf 0) or in p_second
# as -inf (log_cdf -inf, with a nan derivative); see _at_bound.
safe = loc + self.base_dist.scale
log_cdf_first = _at_bound(log_cdf, p_first, safe, 0.0)
log_cdf_second = _at_bound(log_cdf, p_second, safe, -jnp.inf)
return logsumexp(
a=jnp.stack([log_cdf_first, log_cdf_second], axis=-1),
axis=-1,
b=jnp.array([1, -1]), # subtract second from first
)
else:
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
return jnp.log(sign * (self._tail_prob_at_high - self._tail_prob_at_low))
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
# NB: we use a more numerically stable formula for a symmetric base distribution
# A = icdf(cdf(low) + (cdf(high) - cdf(low)) * q) = icdf[(1 - q) * cdf(low) + q * cdf(high)]
# will suffer by precision issues when low is large;
# If low < loc:
# A = icdf[(1 - q) * cdf(low) + q * cdf(high)]
# Else
# A = 2 * loc - icdf[(1 - q) * cdf(2*loc-low)) + q * cdf(2*loc - high)]
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
ppf = (1 - sign) * loc + sign * self.base_dist.icdf(
clamp_probs((1 - q) * self._tail_prob_at_low + q * self._tail_prob_at_high)
)
return jnp.where(
jnp.logical_or(jnp.less(q, 0), jnp.greater(q, 1)), jnp.nan, ppf
)
[docs]
def cdf(self, value: ArrayLike) -> Array:
# For two-sided truncated distribution: CDF(x) = (F(x) - F(low)) / (F(high) - F(low))
# where F is the base distribution CDF.
# When the interval lies in the upper tail (low >= loc), both the
# numerator and the denominator are expressed in terms of reflected
# tail probabilities to avoid 0 / 0 from F(low) rounding to 1.
loc = self.base_dist.loc
sign = jnp.where(loc >= self.low, 1.0, -1.0)
tail_prob_value = self.base_dist.cdf(loc - sign * (loc - value))
truncated_cdf = (tail_prob_value - self._tail_prob_at_low) / (
self._tail_prob_at_high - self._tail_prob_at_low
)
# Handle values outside the truncation interval
result = jnp.where(
jnp.less(value, self.low),
0.0,
jnp.where(
jnp.greater(value, self.high), 1.0, jnp.clip(truncated_cdf, 0.0, 1.0)
),
)
return result
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
# NB: we use a more numerically stable formula for a symmetric base distribution
# if low < loc
# cdf(high) - cdf(low) = as-is
# if low > loc
# cdf(high) - cdf(low) = cdf(2 * loc - low) - cdf(2 * loc - high)
return self.base_dist.log_prob(value) - self._log_diff_tail_probs
@property
def mean(self) -> Array:
if isinstance(self.base_dist, Normal):
low_prob, high_prob = self._prob_at_low, self._prob_at_high
return self.base_dist.loc + (low_prob - high_prob) * self.base_dist.scale**2
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("mean only available for Normal and Cauchy")
@property
def variance(self) -> Array:
if isinstance(self.base_dist, Normal):
loc = self.base_dist.loc
low_prob, high_prob = self._prob_at_low, self._prob_at_high
return (self.base_dist.scale**2) * (
1
+ jnp.where(jnp.isinf(self.low), 0.0, self.low - loc) * low_prob
- jnp.where(jnp.isinf(self.high), 0.0, self.high - loc) * high_prob
- ((low_prob - high_prob) * self.base_dist.scale) ** 2
)
elif isinstance(self.base_dist, Cauchy):
return jnp.full(self.batch_shape, jnp.nan)
else:
raise NotImplementedError("variance only available for Normal and Cauchy")
[docs]
def TruncatedDistribution(
base_dist: Union[Cauchy, Laplace, Logistic, Normal, SoftLaplace, StudentT],
low: Optional[ArrayLike] = None,
high: Optional[ArrayLike] = None,
*,
validate_args: Optional[bool] = None,
):
r"""Truncate a symmetric location-scale distribution to ``[low, high]``.
If the base distribution has density :math:`f` and cdf :math:`F`, the truncated
density is
.. math::
p(x \mid a, b) = \frac{f(x)}{F(b) - F(a)}, \qquad a \leq x \leq b,
where :math:`a` is ``low`` and :math:`b` is ``high``; an omitted bound
contributes :math:`F(a) = 0` or :math:`F(b) = 1`. The cdf and inverse cdf are
.. math::
F_{a,b}(x) = \frac{F(x) - F(a)}{F(b) - F(a)}, \qquad
F_{a,b}^{-1}(q) = F^{-1}\big(F(a) + q\,[F(b) - F(a)]\big),
and samples are drawn by inverse-cdf sampling.
Depending on which bounds are given this returns ``base_dist`` itself (neither),
a :class:`LeftTruncatedDistribution` (``low`` only), a
:class:`RightTruncatedDistribution` (``high`` only) or a
:class:`TwoSidedTruncatedDistribution` (both).
:param base_dist: The base distribution to be truncated. This should be a univariate
distribution. Currently, only the following distributions are supported:
Cauchy, Laplace, Logistic, Normal, SoftLaplace, and StudentT.
:param low: the value which is used to truncate the base distribution from below.
Setting this parameter to None to not truncate from below. ``-inf`` entries
are accepted too (e.g. per-observation bounds where some are absent), but a
site with an infinite bound can only be observed, not sampled as a latent:
the bijector of its support is undefined there. Use ``None`` for a latent
site.
:param high: the value which is used to truncate the base distribution from above.
Setting this parameter to None to not truncate from above; ``+inf`` entries
are accepted with the same caveat as ``low``.
.. note::
``mean`` and ``variance`` are available in closed form only for a ``Normal``
base; a ``Cauchy`` base returns ``nan`` and any other base raises
``NotImplementedError``.
**Example:**
.. doctest::
>>> from numpyro import distributions as dist
>>> d = dist.TruncatedDistribution(dist.Laplace(0.0, 1.0), low=-1.0, high=2.0)
>>> type(d).__name__
'TwoSidedTruncatedDistribution'
>>> lower_only = dist.TruncatedDistribution(dist.Laplace(0.0, 1.0), low=-1.0)
>>> type(lower_only).__name__
'LeftTruncatedDistribution'
"""
if high is None:
if low is None:
return base_dist
else:
return LeftTruncatedDistribution(
base_dist, low=low, validate_args=validate_args
)
elif low is None:
return RightTruncatedDistribution(
base_dist, high=high, validate_args=validate_args
)
else:
return TwoSidedTruncatedDistribution(
base_dist, low=low, high=high, validate_args=validate_args
)
[docs]
def TruncatedCauchy(
loc: ArrayLike = 0.0,
scale: ArrayLike = 1.0,
*,
low: Optional[ArrayLike] = None,
high: Optional[ArrayLike] = None,
validate_args: Optional[bool] = None,
):
r"""A :class:`~numpyro.distributions.continuous.Cauchy` distribution truncated
to ``[low, high]``.
With location :math:`\mu`, scale :math:`\gamma`, and bounds :math:`a` (``low``)
and :math:`b` (``high``), the density is
.. math::
p(x \mid \mu, \gamma, a, b) = \frac{1}{
\gamma \left[1 + \left(\frac{x - \mu}{\gamma}\right)^2\right]
\left[\arctan\frac{b - \mu}{\gamma} - \arctan\frac{a - \mu}{\gamma}\right]
}, \qquad a \leq x \leq b,
which follows from the Cauchy cdf
:math:`F(x) = \frac{1}{2} + \frac{1}{\pi}\arctan\frac{x - \mu}{\gamma}`; an omitted
bound contributes :math:`\arctan(\pm\infty) = \pm\pi/2`. The cdf is
.. math::
P(X \leq x) = \frac{
\arctan\frac{x - \mu}{\gamma} - \arctan\frac{a - \mu}{\gamma}
}{
\arctan\frac{b - \mu}{\gamma} - \arctan\frac{a - \mu}{\gamma}
}.
This is :func:`TruncatedDistribution` applied to ``Cauchy(loc, scale)``, so it
returns a :class:`LeftTruncatedDistribution`, :class:`RightTruncatedDistribution`
or :class:`TwoSidedTruncatedDistribution` depending on which bounds are given,
or the plain ``Cauchy`` when neither is.
:param loc: location :math:`\mu` of the base Cauchy distribution.
:param scale: scale :math:`\gamma > 0` of the base Cauchy distribution.
:param low: lower truncation point, or None to not truncate from below.
:param high: upper truncation point, or None to not truncate from above.
.. note::
``mean`` and ``variance`` return ``nan``: a one-sided truncated Cauchy has no
finite moments, and the closed-form moments of the two-sided case are not
implemented.
"""
return TruncatedDistribution(
Cauchy(loc, scale), low=low, high=high, validate_args=validate_args
)
[docs]
def TruncatedNormal(
loc: ArrayLike = 0.0,
scale: ArrayLike = 1.0,
*,
low: Optional[ArrayLike] = None,
high: Optional[ArrayLike] = None,
validate_args: Optional[bool] = None,
):
r"""A :class:`~numpyro.distributions.continuous.Normal` distribution truncated
to ``[low, high]``.
With :math:`\alpha = (a - \mu) / \sigma` and :math:`\beta = (b - \mu) / \sigma`
for bounds :math:`a` (``low``) and :math:`b` (``high``), and
:math:`Z = \Phi(\beta) - \Phi(\alpha)`, the density is
.. math::
p(x \mid \mu, \sigma, a, b) = \frac{1}{\sigma Z}\,
\phi\!\left(\frac{x - \mu}{\sigma}\right), \qquad a \leq x \leq b,
where :math:`\phi` and :math:`\Phi` are the standard normal pdf and cdf. An
omitted bound contributes :math:`\alpha = -\infty` or :math:`\beta = \infty`, with
:math:`\phi(\pm\infty) = 0`, :math:`\alpha\,\phi(\alpha) \to 0`,
:math:`\Phi(-\infty) = 0` and :math:`\Phi(\infty) = 1`. The mean and variance are
.. math::
\mathbb{E}[X] = \mu + \sigma\,\frac{\phi(\alpha) - \phi(\beta)}{Z}, \qquad
\operatorname{Var}[X] = \sigma^2 \left[
1 + \frac{\alpha\,\phi(\alpha) - \beta\,\phi(\beta)}{Z}
- \left(\frac{\phi(\alpha) - \phi(\beta)}{Z}\right)^2
\right].
This is :func:`TruncatedDistribution` applied to ``Normal(loc, scale)``, so it
returns a :class:`LeftTruncatedDistribution`, :class:`RightTruncatedDistribution`
or :class:`TwoSidedTruncatedDistribution` depending on which bounds are given,
or the plain ``Normal`` when neither is.
:param loc: location :math:`\mu` of the base Normal distribution.
:param scale: scale :math:`\sigma > 0` of the base Normal distribution.
:param low: lower truncation point, or None to not truncate from below.
:param high: upper truncation point, or None to not truncate from above.
**Example:**
.. doctest::
>>> from numpyro import distributions as dist
>>> d = dist.TruncatedNormal(0.0, 1.0, low=-1.0, high=2.0)
>>> type(d).__name__
'TwoSidedTruncatedDistribution'
>>> positive = dist.TruncatedNormal(0.0, 1.0, low=0.0)
>>> type(positive).__name__
'LeftTruncatedDistribution'
"""
return TruncatedDistribution(
Normal(loc, scale), low=low, high=high, validate_args=validate_args
)
def _safe_log_normalizer(normalizer: ArrayLike) -> Array:
"""Log of a truncation normalizer, kept finite when the normalizer underflows.
Callers pair this with a ``jnp.where`` selecting ``-inf`` wherever the normalizer
is zero; taking the log of the clamped value keeps that branch's gradient finite
rather than ``nan``.
"""
return jnp.log(jnp.where(jnp.greater(normalizer, 0.0), normalizer, 1.0))
def _truncated_log_prob(
base_log_prob: ArrayLike, normalizer: ArrayLike, log_normalizer: ArrayLike
) -> Array:
"""Renormalized log density, guarding the underflowed case.
Once the retained probability underflows to zero, ``jnp.log`` hands back ``-inf``
and the subtraction would make ``log_prob`` ``+inf`` — attracting a gradient-based
sampler rather than repelling it. Selecting ``-inf`` instead also makes the
gradient zero there, which is the honest answer for a density that is
identically zero across the region.
``cdf``, ``mean`` and ``variance`` return ``nan`` in the same regime rather than
``-inf``: a density that is identically zero still has a well defined log density,
but conditioning on an event of zero probability leaves its distribution function
and moments undefined.
"""
return jnp.where(
jnp.greater(normalizer, 0.0),
jnp.subtract(base_log_prob, log_normalizer),
-jnp.inf,
)
def _nan_if_degenerate(value: ArrayLike, normalizer: ArrayLike) -> Array:
"""Mask a moment or probability that is undefined because no mass is retained."""
return jnp.where(jnp.greater(normalizer, 0.0), value, jnp.nan)
def _bisection_steps() -> int:
"""Bisection iterations needed to bracket the root tightly enough for Newton.
Each step halves the bracket, so ``-log2(eps)`` steps reduce it by the working
precision's worth of factors. The Newton step in :func:`_icdf_by_bisection`
supplies the remaining digits, so no margin beyond that is useful — measured
accuracy is unchanged from 20 steps upward and limited by the cdf itself.
"""
return int(-math.log2(jnp.finfo(jnp.result_type(float)).eps))
def _bracket_above(
cdf_fn: Callable,
q: ArrayLike,
low: ArrayLike,
scale: ArrayLike,
shape: tuple[int, ...],
) -> Array:
"""Grow an upper bound from ``low`` until the cdf covers ``q``.
Used for distributions truncated only from below, whose support has no upper end
to bisect against. The offset doubles each step, so the bound reaches ``2**n``
scale lengths in ``n`` steps.
"""
dtype = jnp.result_type(float)
low = jnp.broadcast_to(low, shape).astype(dtype)
high = jnp.broadcast_to(low + scale, shape).astype(dtype)
def body(_, high):
return jnp.where(jnp.less(cdf_fn(high), q), low + 2.0 * (high - low), high)
return lax.fori_loop(0, 64, body, high)
def _icdf_by_bisection(
cdf_fn: Callable,
pdf_fn: Callable,
q: ArrayLike,
low: ArrayLike,
high: ArrayLike,
shape: tuple[int, ...],
) -> Array:
"""Invert a monotone cdf on ``[low, high]`` by bisection.
Used in place of an inverse incomplete gamma: ``tfp.math.igammainv`` and
``igammacinv`` return ``+inf`` once the tail probability they are asked to invert
falls below roughly ``3e-8`` — an algorithm tolerance rather than a dtype limit,
identical in single and double precision — which puts a draw outside the support
whenever the retained mass is small. Bisecting the cdf has no such floor, costs a
fixed number of incomplete gamma evaluations, and differentiates through
``cdf_fn``.
"""
dtype = jnp.result_type(float)
bounds = (
jnp.broadcast_to(low, shape).astype(dtype),
jnp.broadcast_to(high, shape).astype(dtype),
)
def body(_, bounds):
lower, upper = bounds
mid = 0.5 * (lower + upper)
go_right = jnp.less(cdf_fn(mid), q)
return (jnp.where(go_right, mid, lower), jnp.where(go_right, upper, mid))
lower, upper = lax.fori_loop(0, _bisection_steps(), body, bounds)
x = lax.stop_gradient(0.5 * (lower + upper))
# Bisection branches on comparisons, so it is piecewise constant in the parameters
# and carries no derivative. One Newton step taken from the detached root restores
# the implicit-function derivative, dx/dtheta = -(dF/dtheta) / f(x), without moving
# the value: the residual is already zero to the bracket's precision.
density = pdf_fn(x)
positive = jnp.greater(density, 0.0)
safe_density = jnp.where(positive, density, 1.0)
correction = (cdf_fn(x) - q) / safe_density
return x - jnp.where(positive, correction, 0.0)
[docs]
class LeftTruncatedGamma(Distribution):
r"""A :class:`~numpyro.distributions.continuous.Gamma` distribution truncated
from below at ``low``.
.. math::
f(x \mid \alpha, \lambda, a) = \frac{
\mathrm{Gamma}(x \mid \alpha, \lambda)
}{
Q(\alpha, \lambda a)
}, \qquad x \geq a,
where :math:`Q(\alpha, z)` is the regularized upper incomplete gamma function
(:func:`~jax.scipy.special.gammaincc`). Taking the normalizer from the upper tail
keeps it accurate however far into the tail ``low`` sits.
:param base_dist: a :class:`~numpyro.distributions.continuous.Gamma` instance.
:param low: the value at which the base distribution is truncated from below.
.. note::
``icdf`` inverts the cdf by bisection rather than calling an inverse incomplete
gamma. The latter saturates below a tail probability of roughly ``3e-8`` — an
algorithm tolerance, identical in single and double precision — which would
return draws outside the support whenever the retained mass is small. A Newton
step from the bracketed root supplies the implicit derivative, so ``icdf`` and
``sample`` stay differentiable. The cost is a fixed number of incomplete gamma
evaluations, roughly three to five times a single inverse; ``log_prob`` is
unaffected.
Where the normalizer underflows to zero, ``log_prob`` returns ``-inf`` rather
than ``+inf`` and ``cdf``, ``mean`` and ``variance`` return ``nan``. Finally,
``variance`` is computed as ``E[X^2] - E[X]^2``, which cancels badly in single
precision when the interval is narrow relative to its distance from the origin
— ``Gamma(2, 1e-4)`` on ``[100, 101]`` is out by 70% — so enable
``jax_enable_x64`` for such configurations.
"""
arg_constraints = {"low": constraints.greater_than_eq(0.0)}
reparametrized_params = ["low"]
_support: constraints.Constraint
supported_types = (Gamma,)
pytree_data_fields = ("base_dist", "low", "_support")
def __init__(
self,
base_dist: Gamma,
low: ArrayLike = 0.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types)
batch_shape = lax.broadcast_shapes(base_dist.batch_shape, jnp.shape(low))
self.base_dist: Gamma = jax.tree.map(
lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist
)
(self.low,) = promote_shapes(low, shape=batch_shape)
self._support = constraints.greater_than_eq(cast(NumLike, low))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _normalizer(self):
return gammaincc(self.base_dist.concentration, self.base_dist.rate * self.low)
@lazy_property
def _log_normalizer(self):
return _safe_log_normalizer(self._normalizer)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
# The support is unbounded above, so bracket by doubling before bisecting.
scale = (self.base_dist.concentration + 1.0) / self.base_dist.rate
shape = lax.broadcast_shapes(jnp.shape(q), self.batch_shape)
high = _bracket_above(self.cdf, q, self.low, scale, shape)
x = _icdf_by_bisection(self.cdf, self._pdf, q, self.low, high, shape)
invalid = jnp.logical_or(
jnp.logical_or(jnp.less(q, 0), jnp.greater(q, 1)),
jnp.less_equal(self._normalizer, 0.0),
)
x = jnp.where(invalid, jnp.nan, x)
# q == 1 is legitimately infinite here: the support is unbounded above.
return jnp.where(jnp.greater_equal(q, 1.0), jnp.inf, x)
[docs]
def cdf(self, value: ArrayLike) -> Array:
sf = gammaincc(self.base_dist.concentration, self.base_dist.rate * value)
cdf = jnp.where(
jnp.less(value, self.low),
0.0,
jnp.clip(1 - sf / self._normalizer, 0.0, 1.0),
)
return jnp.where(jnp.greater(self._normalizer, 0.0), cdf, jnp.nan)
def _pdf(self, value: ArrayLike) -> Array:
"""Density without support validation, for the Newton step in ``icdf``."""
return jnp.exp(
_truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
return _truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
@property
def mean(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
mean = (concentration / rate) * (
gammaincc(concentration + 1, rate * self.low) / self._normalizer
)
return _nan_if_degenerate(mean, self._normalizer)
@property
def variance(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
second_moment = (concentration * (concentration + 1) / rate**2) * (
gammaincc(concentration + 2, rate * self.low) / self._normalizer
)
return _nan_if_degenerate(second_moment - self.mean**2, self._normalizer)
[docs]
class RightTruncatedGamma(Distribution):
r"""A :class:`~numpyro.distributions.continuous.Gamma` distribution truncated
from above at ``high``.
.. math::
f(x \mid \alpha, \lambda, b) = \frac{
\mathrm{Gamma}(x \mid \alpha, \lambda)
}{
P(\alpha, \lambda b)
}, \qquad 0 < x \leq b,
where :math:`P(\alpha, z)` is the regularized lower incomplete gamma function
(:func:`~jax.scipy.special.gammainc`).
The support is closed at zero, so ``log_prob(0.)`` is ``+inf`` when
``concentration < 1``, where the density genuinely diverges. The base
:class:`~numpyro.distributions.continuous.Gamma` has an open support and masks that
point instead; matching it would need a half-open interval constraint, which does
not exist yet (:func:`~numpyro.distributions.constraints.open_interval` would also
wrongly exclude ``high``).
:param base_dist: a :class:`~numpyro.distributions.continuous.Gamma` instance.
:param high: the value at which the base distribution is truncated from above.
.. note::
``icdf`` inverts the cdf by bisection rather than calling an inverse incomplete
gamma. The latter saturates below a tail probability of roughly ``3e-8`` — an
algorithm tolerance, identical in single and double precision — which would
return draws outside the support whenever the retained mass is small. A Newton
step from the bracketed root supplies the implicit derivative, so ``icdf`` and
``sample`` stay differentiable. The cost is a fixed number of incomplete gamma
evaluations, roughly three to five times a single inverse; ``log_prob`` is
unaffected.
Where the normalizer underflows to zero, ``log_prob`` returns ``-inf`` rather
than ``+inf`` and ``cdf``, ``mean`` and ``variance`` return ``nan``. Finally,
``variance`` is computed as ``E[X^2] - E[X]^2``, which cancels badly in single
precision when the interval is narrow relative to its distance from the origin
— ``Gamma(2, 1e-4)`` on ``[100, 101]`` is out by 70% — so enable
``jax_enable_x64`` for such configurations.
"""
arg_constraints = {"high": constraints.positive}
reparametrized_params = ["high"]
_support: constraints.Constraint
supported_types = (Gamma,)
pytree_data_fields = ("base_dist", "high", "_support")
def __init__(
self,
base_dist: Gamma,
high: ArrayLike = 1.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types)
batch_shape = lax.broadcast_shapes(base_dist.batch_shape, jnp.shape(high))
self.base_dist: Gamma = jax.tree.map(
lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist
)
(self.high,) = promote_shapes(high, shape=batch_shape)
self._support = constraints.interval(0.0, cast(NumLike, high))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _normalizer(self):
return gammainc(self.base_dist.concentration, self.base_dist.rate * self.high)
@lazy_property
def _log_normalizer(self):
return _safe_log_normalizer(self._normalizer)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
shape = lax.broadcast_shapes(jnp.shape(q), self.batch_shape)
x = _icdf_by_bisection(
self.cdf, self._pdf, q, jnp.zeros_like(self.high), self.high, shape
)
invalid = jnp.logical_or(
jnp.logical_or(jnp.less(q, 0), jnp.greater(q, 1)),
jnp.less_equal(self._normalizer, 0.0),
)
return jnp.where(invalid, jnp.nan, x)
[docs]
def cdf(self, value: ArrayLike) -> Array:
cdf = gammainc(self.base_dist.concentration, self.base_dist.rate * value)
cdf = jnp.where(
jnp.greater(value, self.high),
1.0,
jnp.clip(cdf / self._normalizer, 0.0, 1.0),
)
return jnp.where(jnp.greater(self._normalizer, 0.0), cdf, jnp.nan)
def _pdf(self, value: ArrayLike) -> Array:
"""Density without support validation, for the Newton step in ``icdf``."""
return jnp.exp(
_truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
return _truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
@property
def mean(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
mean = (concentration / rate) * (
gammainc(concentration + 1, rate * self.high) / self._normalizer
)
return _nan_if_degenerate(mean, self._normalizer)
@property
def variance(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
second_moment = (concentration * (concentration + 1) / rate**2) * (
gammainc(concentration + 2, rate * self.high) / self._normalizer
)
return _nan_if_degenerate(second_moment - self.mean**2, self._normalizer)
[docs]
class TwoSidedTruncatedGamma(Distribution):
r"""A :class:`~numpyro.distributions.continuous.Gamma` distribution truncated to
the interval ``[low, high]``.
.. math::
f(x \mid \alpha, \lambda, a, b) = \frac{
\mathrm{Gamma}(x \mid \alpha, \lambda)
}{
Z(\alpha, \lambda, a, b)
}, \qquad a \leq x \leq b,
with normalizer :math:`Z = P(\alpha, \lambda b) - P(\alpha, \lambda a)`.
Written that way the normalizer loses all of its significant digits when the
interval sits far out in the right tail, where both terms are within rounding
distance of one; for ``Gamma(2, 1)`` on ``[30, 40]`` in single precision the
difference is exactly zero, which would make ``log_prob`` infinite. This class
therefore uses the equivalent upper-tail form
:math:`Z = Q(\alpha, \lambda a) - Q(\alpha, \lambda b)` whenever the interval lies
above the median of the base distribution, and switches ``cdf``, ``mean`` and
``variance`` to match.
When ``low`` is zero the support is closed there, so ``log_prob(0.)`` is ``+inf``
for ``concentration < 1``; see :class:`RightTruncatedGamma` for why this differs
from the base :class:`~numpyro.distributions.continuous.Gamma`.
:param base_dist: a :class:`~numpyro.distributions.continuous.Gamma` instance.
:param low: the value at which the base distribution is truncated from below.
:param high: the value at which the base distribution is truncated from above.
.. note::
``icdf`` inverts the cdf by bisection rather than calling an inverse incomplete
gamma. The latter saturates below a tail probability of roughly ``3e-8`` — an
algorithm tolerance, identical in single and double precision — which would
return draws outside the support whenever the retained mass is small. A Newton
step from the bracketed root supplies the implicit derivative, so ``icdf`` and
``sample`` stay differentiable. The cost is a fixed number of incomplete gamma
evaluations, roughly three to five times a single inverse; ``log_prob`` is
unaffected.
Where the normalizer underflows to zero, ``log_prob`` returns ``-inf`` rather
than ``+inf`` and ``cdf``, ``mean`` and ``variance`` return ``nan``. Finally,
``variance`` is computed as ``E[X^2] - E[X]^2``, which cancels badly in single
precision when the interval is narrow relative to its distance from the origin
— ``Gamma(2, 1e-4)`` on ``[100, 101]`` is out by 70% — so enable
``jax_enable_x64`` for such configurations.
"""
arg_constraints = {
"low": constraints.dependent(is_discrete=False, event_dim=0),
"high": constraints.dependent(is_discrete=False, event_dim=0),
}
reparametrized_params = ["low", "high"]
_support: constraints.Constraint
supported_types = (Gamma,)
pytree_data_fields = ("base_dist", "low", "high", "_support")
def __init__(
self,
base_dist: Gamma,
low: ArrayLike = 0.0,
high: ArrayLike = 1.0,
*,
validate_args: Optional[bool] = None,
):
assert isinstance(base_dist, self.supported_types)
batch_shape = lax.broadcast_shapes(
base_dist.batch_shape, jnp.shape(low), jnp.shape(high)
)
self.base_dist: Gamma = jax.tree.map(
lambda p: promote_shapes(p, shape=batch_shape)[0], base_dist
)
(self.low,) = promote_shapes(low, shape=batch_shape)
(self.high,) = promote_shapes(high, shape=batch_shape)
self._support = constraints.interval(cast(NumLike, low), cast(NumLike, high))
super().__init__(batch_shape, validate_args=validate_args)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
@lazy_property
def _cdf_at_low(self):
return gammainc(self.base_dist.concentration, self.base_dist.rate * self.low)
@lazy_property
def _cdf_at_high(self):
return gammainc(self.base_dist.concentration, self.base_dist.rate * self.high)
@lazy_property
def _sf_at_low(self):
return gammaincc(self.base_dist.concentration, self.base_dist.rate * self.low)
@lazy_property
def _sf_at_high(self):
return gammaincc(self.base_dist.concentration, self.base_dist.rate * self.high)
@lazy_property
def _use_upper_tail(self):
# The interval lies above the median of the base distribution, so both lower
# tail probabilities are close to one and their difference cancels.
return jnp.greater(self._cdf_at_low, 0.5)
@lazy_property
def _normalizer(self):
return jnp.where(
self._use_upper_tail,
self._sf_at_low - self._sf_at_high,
self._cdf_at_high - self._cdf_at_low,
)
@lazy_property
def _log_normalizer(self):
return _safe_log_normalizer(self._normalizer)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
dtype = jnp.result_type(float)
finfo = jnp.finfo(dtype)
minval = finfo.tiny
u = random.uniform(key, shape=sample_shape + self.batch_shape, minval=minval)
return self.icdf(u)
[docs]
def icdf(self, q: ArrayLike) -> Array:
shape = lax.broadcast_shapes(jnp.shape(q), self.batch_shape)
x = _icdf_by_bisection(self.cdf, self._pdf, q, self.low, self.high, shape)
invalid = jnp.logical_or(
jnp.logical_or(jnp.less(q, 0), jnp.greater(q, 1)),
jnp.less_equal(self._normalizer, 0.0),
)
return jnp.where(invalid, jnp.nan, x)
[docs]
def cdf(self, value: ArrayLike) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
truncated_cdf = jnp.where(
self._use_upper_tail,
(self._sf_at_low - gammaincc(concentration, rate * value))
/ self._normalizer,
(gammainc(concentration, rate * value) - self._cdf_at_low)
/ self._normalizer,
)
cdf = jnp.where(
jnp.less(value, self.low),
0.0,
jnp.where(
jnp.greater(value, self.high),
1.0,
jnp.clip(truncated_cdf, 0.0, 1.0),
),
)
return jnp.where(jnp.greater(self._normalizer, 0.0), cdf, jnp.nan)
def _pdf(self, value: ArrayLike) -> Array:
"""Density without support validation, for the Newton step in ``icdf``."""
return jnp.exp(
_truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
return _truncated_log_prob(
self.base_dist.log_prob(value), self._normalizer, self._log_normalizer
)
def _partial_moment(self, order: int) -> Array:
"""The integral of ``x**order`` over the interval, up to the falling factorial.
This is the same incomplete gamma difference as the normalizer, but evaluated
at ``concentration + order``. The tail switch must therefore be decided afresh:
``Gamma(alpha + k)`` has a larger median than ``Gamma(alpha)``, so an interval
sitting above the median of the base distribution can fall deep into the
*lower* tail at the shifted order, where the upper-tail form is the one that
cancels. Reusing the order-zero branch there collapses the difference to zero
and yields a negative variance.
"""
rate = self.base_dist.rate
shifted = self.base_dist.concentration + order
use_upper_tail = jnp.greater(gammainc(shifted, rate * self.low), 0.5)
return jnp.where(
use_upper_tail,
gammaincc(shifted, rate * self.low) - gammaincc(shifted, rate * self.high),
gammainc(shifted, rate * self.high) - gammainc(shifted, rate * self.low),
)
@property
def mean(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
mean = (concentration / rate) * (self._partial_moment(1) / self._normalizer)
return _nan_if_degenerate(mean, self._normalizer)
@property
def variance(self) -> Array:
concentration, rate = self.base_dist.concentration, self.base_dist.rate
second_moment = (concentration * (concentration + 1) / rate**2) * (
self._partial_moment(2) / self._normalizer
)
return _nan_if_degenerate(second_moment - self.mean**2, self._normalizer)
[docs]
def TruncatedGamma(
concentration: ArrayLike = 1.0,
rate: ArrayLike = 1.0,
*,
low: Optional[ArrayLike] = None,
high: Optional[ArrayLike] = None,
validate_args: Optional[bool] = None,
):
r"""A :class:`~numpyro.distributions.continuous.Gamma` distribution truncated
to ``[low, high]``.
With the base density
.. math::
\mathrm{Gamma}(x \mid \alpha, \lambda) =
\frac{\lambda^\alpha}{\Gamma(\alpha)}\, x^{\alpha - 1} e^{-\lambda x},
\qquad x > 0,
and bounds :math:`a` (``low``) and :math:`b` (``high``), the truncated density is
.. math::
p(x \mid \alpha, \lambda, a, b) = \frac{
\mathrm{Gamma}(x \mid \alpha, \lambda)
}{
P(\alpha, \lambda b) - P(\alpha, \lambda a)
}, \qquad a \leq x \leq b,
where :math:`P(\alpha, z)` is the regularized lower incomplete gamma function
(:func:`~jax.scipy.special.gammainc`); an omitted bound contributes
:math:`P(\alpha, 0) = 0` or :math:`P(\alpha, \infty) = 1`.
Depending on which bounds are given this returns the plain ``Gamma`` (neither), a
:class:`LeftTruncatedGamma` (``low`` only), a :class:`RightTruncatedGamma`
(``high`` only) or a :class:`TwoSidedTruncatedGamma` (both). See those classes
for how the normalizer is evaluated in the tails and for the ``icdf`` algorithm.
:param concentration: concentration parameter :math:`\alpha` of the base
:class:`~numpyro.distributions.continuous.Gamma` distribution.
:param rate: rate parameter :math:`\lambda` of the base distribution.
:param low: the value which is used to truncate the base distribution from
below. Setting this parameter to None to not truncate from below.
:param high: the value which is used to truncate the base distribution from
above. Setting this parameter to None to not truncate from above.
**Example:**
.. doctest::
>>> from jax import numpy as jnp
>>> from numpyro import distributions as dist
>>> d = dist.TruncatedGamma(2.0, 1.0, low=0.5, high=3.0)
>>> log_prob = d.log_prob(jnp.array([1.0, 2.0]))
>>> lower_bounded = dist.TruncatedGamma(2.0, 1.0, low=0.5)
"""
base_dist = Gamma(concentration, rate)
if high is None:
if low is None:
return base_dist
return LeftTruncatedGamma(base_dist, low=low, validate_args=validate_args)
elif low is None:
return RightTruncatedGamma(base_dist, high=high, validate_args=validate_args)
else:
return TwoSidedTruncatedGamma(
base_dist, low=low, high=high, validate_args=validate_args
)
[docs]
class TruncatedPolyaGamma(Distribution):
r"""An approximation of the Polya-Gamma distribution :math:`\mathrm{PG}(1, 0)`
restricted to :math:`[0, 2.5]`.
:math:`X \sim \mathrm{PG}(1, 0)` is defined by the infinite convolution of
exponential variates
.. math::
X = \frac{1}{2\pi^2} \sum_{k=1}^{\infty} \frac{g_k}{(k - 1/2)^2},
\qquad g_k \overset{\text{iid}}{\sim} \mathrm{Gamma}(1, 1),
so that :math:`\mathbb{E}[e^{-tX}] = 1 / \cosh\!\big(\sqrt{t/2}\big)` and
:math:`\mathbb{E}[X] = 1/4`. Its density has the alternating series representation
.. math::
p(x) = \sum_{n=0}^{\infty} (-1)^n \frac{2n + 1}{\sqrt{2\pi x^3}}
\exp\!\left(-\frac{(2n + 1)^2}{8x}\right), \qquad x > 0.
:math:`\mathrm{PG}(1, 0)` is the mixing distribution in the Pólya-Gamma
augmentation of logistic models (see reference 1); the Gibbs conditional there
is the tilted :math:`\mathrm{PG}(1, \psi)`.
:param batch_shape: batch shape of the distribution.
.. note::
``sample`` and ``log_prob`` are both series truncations:
* ``sample`` keeps the first ``num_gamma_variates`` (class attribute, 8)
terms of the Gamma series and clips the result at ``truncation_point``
(2.5). The discarded terms have expected value
:math:`\frac{1}{2\pi^2}\sum_{k > 8} (k - 1/2)^{-2} \approx 0.0063`, so the
sampler mean is about :math:`0.244` rather than :math:`1/4`.
* ``log_prob`` evaluates the first ``num_log_prob_terms`` (class attribute,
7) terms of the alternating series. The discarded tail is alternating and
decreasing on the support, so the partial sum is positive and an upper
bound on the density. The truncation error of the partial sum is below
:math:`10^{-6}` for :math:`x < 1.39` (float32 rounding in the alternating
sum adds up to about :math:`10^{-5}`), about :math:`5 \times 10^{-3}` at
:math:`x = 2` and about :math:`0.7` at :math:`x = 2.5`, where the density
is :math:`2.8 \times 10^{-5}`. The density is not renormalized to the
support: the mass of :math:`\mathrm{PG}(1, 0)` above :math:`2.5` is
:math:`5.6 \times 10^{-6}`.
``mean`` and ``variance`` are not implemented.
**References:**
1. Polson, N. G., Scott, J. G., & Windle, J. (2013). Bayesian inference for
logistic models using Pólya-Gamma latent variables. *Journal of the American
Statistical Association*, 108(504), 1339-1349.
2. Devroye, L. (2009). On exact simulation algorithms for some distributions
related to Jacobi theta functions. *Statistics & Probability Letters*,
79(21), 2251-2259.
"""
truncation_point = 2.5
num_log_prob_terms = 7
num_gamma_variates = 8
assert num_log_prob_terms % 2 == 1
arg_constraints = {}
support = constraints.interval(0.0, truncation_point)
def __init__(
self, batch_shape: tuple[int, ...] = (), *, validate_args: Optional[bool] = None
):
super(TruncatedPolyaGamma, self).__init__(
batch_shape, validate_args=validate_args
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
denom = jnp.square(jnp.arange(0.5, self.num_gamma_variates))
x = random.gamma(
key, jnp.ones(self.batch_shape + sample_shape + (self.num_gamma_variates,))
)
x = jnp.sum(x / denom, axis=-1)
return jnp.clip(x * (0.5 / jnp.pi**2), None, self.truncation_point)
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
value = jnp.expand_dims(value, -1)
all_indices = jnp.arange(0, self.num_log_prob_terms)
two_n_plus_one = 2.0 * all_indices + 1.0
log_terms = (
jnp.log(two_n_plus_one)
- 1.5 * jnp.log(value)
- 0.125 * jnp.square(two_n_plus_one) / value
)
even_terms = jnp.take(log_terms, all_indices[::2], axis=-1)
odd_terms = jnp.take(log_terms, all_indices[1::2], axis=-1)
sum_even = jnp.exp(logsumexp(even_terms, axis=-1))
sum_odd = jnp.exp(logsumexp(odd_terms, axis=-1))
return jnp.log(sum_even - sum_odd) - 0.5 * jnp.log(2.0 * jnp.pi)
[docs]
class DoublyTruncatedPowerLaw(Distribution):
r"""Power law distribution with :math:`\alpha` index, and lower and upper bounds.
We can define the power law distribution as,
.. math::
f(x; \alpha, a, b) = \frac{x^{\alpha}}{Z(\alpha, a, b)},
\qquad a \leq x \leq b,
where, :math:`a` and :math:`b` are the lower and upper bounds respectively,
with :math:`0 \leq a < b` (and :math:`a > 0` when :math:`\alpha \leq -1`,
otherwise :math:`Z` diverges), and :math:`Z(\alpha, a, b)` is the normalization
constant. It is defined as,
.. math::
Z(\alpha, a, b) = \begin{cases}
\log(b) - \log(a) & \text{if } \alpha = -1, \\
\frac{b^{1 + \alpha} - a^{1 + \alpha}}{1 + \alpha} & \text{otherwise}.
\end{cases}
The cdf is
.. math::
F(x) = \begin{cases}
\dfrac{\log(x / a)}{\log(b / a)} & \text{if } \alpha = -1, \\
\dfrac{x^{1 + \alpha} - a^{1 + \alpha}}{b^{1 + \alpha} - a^{1 + \alpha}}
& \text{otherwise},
\end{cases}
and the quantile function is
.. math::
F^{-1}(q) = \begin{cases}
a \, (b / a)^{q} & \text{if } \alpha = -1, \\
\big(a^{1 + \alpha} + q \, [b^{1 + \alpha} - a^{1 + \alpha}]\big)
^{1 / (1 + \alpha)} & \text{otherwise}.
\end{cases}
Samples are drawn by inverse-cdf sampling. The raw moments are
.. math::
\mathbb{E}[X^k] = \begin{cases}
\dfrac{\log(b / a)}{Z(\alpha, a, b)} & \text{if } 1 + \alpha + k = 0, \\
\dfrac{1}{Z(\alpha, a, b)} \cdot
\dfrac{b^{1 + \alpha + k} - a^{1 + \alpha + k}}{1 + \alpha + k}
& \text{otherwise}.
\end{cases}
:param alpha: index :math:`\alpha` of the power law distribution
:param low: lower bound :math:`a` of the distribution
:param high: upper bound :math:`b` of the distribution
.. note::
The :math:`\alpha = -1` branch is selected by exact floating-point equality.
``log_prob``, ``cdf`` and ``icdf`` carry custom JVP rules; at exactly
:math:`\alpha = -1` the :math:`\alpha`-derivative is approximated by the
average of the :math:`\alpha \ne -1` closed form evaluated at
:math:`\alpha \pm 10^{-3}`. ``cdf`` is clipped to :math:`[0, 1]`. ``mean``
and ``variance`` are not implemented (use the moment formula above).
"""
arg_constraints = {
"alpha": constraints.real,
"low": constraints.greater_than_eq(0),
"high": constraints.greater_than(0),
}
reparametrized_params = ["alpha", "low", "high"]
pytree_data_fields = ("alpha", "low", "high", "_support")
_support: constraints.Constraint
def __init__(
self,
alpha: ArrayLike,
low: ArrayLike,
high: ArrayLike,
*,
validate_args: Optional[bool] = None,
):
self.alpha, self.low, self.high = promote_shapes(alpha, low, high)
self._support = constraints.interval(cast(NumLike, low), cast(NumLike, high))
batch_shape = lax.broadcast_shapes(
jnp.shape(alpha), jnp.shape(low), jnp.shape(high)
)
super(DoublyTruncatedPowerLaw, self).__init__(
batch_shape=batch_shape, validate_args=validate_args
)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
r"""Log probability density for :math:`a \leq x \leq b`.
For :math:`\alpha \ne -1`:
.. math::
\log\left(\frac{(\alpha + 1)x^\alpha}{b^{\alpha + 1} - a^{\alpha + 1}}\right)
For :math:`\alpha = -1`:
.. math::
-\log(x) - \log\left(\log(b) - \log(a)\right)
Derivations are calculated by Wolfram Alpha via the Jacobian matrix accordingly.
"""
@jax.custom_jvp
def f(x: ArrayLike, alpha: ArrayLike, low: ArrayLike, high: ArrayLike) -> Array:
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
# eq_neg1_alpha = jnp.where(~neq_neg1_mask, alpha, -1.0)
def neq_neg1_fn() -> Array:
one_more_alpha = 1.0 + neq_neg1_alpha
return jnp.log(
jnp.power(x, neq_neg1_alpha)
* (one_more_alpha)
/ (jnp.power(high, one_more_alpha) - jnp.power(low, one_more_alpha))
)
def eq_neg1_fn() -> Array:
return -jnp.log(x) - jnp.log(jnp.log(high) - jnp.log(low))
return jnp.where(neq_neg1_mask, neq_neg1_fn(), eq_neg1_fn())
@f.defjvp
def f_jvp(
primals: tuple[Array, Array, Array, Array],
tangents: tuple[Array, Array, Array, Array],
) -> tuple[Array, Array]:
x, alpha, low, high = primals
x_t, alpha_t, low_t, high_t = tangents
log_low = jnp.log(low)
log_high = jnp.log(high)
log_x = jnp.log(x)
# Mask and alpha values
delta_eq_neg1 = 10e-4
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
eq_neg1_alpha = jnp.where(jnp.not_equal(alpha, 0.0), alpha, -1.0)
primal_out = f(*primals)
# Alpha tangent with approximation
# Variable part for all values alpha unequal -1
def alpha_tangent_variable(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
return jnp.reciprocal(one_more_alpha) + (
low_pow_one_more_alpha * log_low
- high_pow_one_more_alpha * log_high
) / (high_pow_one_more_alpha - low_pow_one_more_alpha)
# Alpha tangent
alpha_tangent = jnp.where(
neq_neg1_mask,
log_x + alpha_tangent_variable(neq_neg1_alpha),
# Approximate derivative with right and lefthand approximation
log_x
+ (
alpha_tangent_variable(alpha - delta_eq_neg1)
+ alpha_tangent_variable(alpha + delta_eq_neg1)
)
* 0.5,
)
# High and low tangents for alpha unequal -1
one_more_alpha = 1.0 + neq_neg1_alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
change_sq = jnp.square(high_pow_one_more_alpha - low_pow_one_more_alpha)
low_tangent_neq_neg1_common = (
jnp.square(one_more_alpha) * jnp.power(x, neq_neg1_alpha) / change_sq
)
low_tangent_neq_neg1 = low_tangent_neq_neg1_common * jnp.power(
low, neq_neg1_alpha
)
high_tangent_neq_neg1 = low_tangent_neq_neg1_common * jnp.power(
high, neq_neg1_alpha
)
# High and low tangents for alpha equal -1
low_tangent_eq_neg1_common = jnp.power(x, eq_neg1_alpha) / jnp.square(
log_high - log_low
)
low_tangent_eq_neg1 = low_tangent_eq_neg1_common / low
high_tangent_eq_neg1 = -low_tangent_eq_neg1_common / high
# High and low tangents
low_tangent = jnp.where(
neq_neg1_mask, low_tangent_neq_neg1, low_tangent_eq_neg1
)
high_tangent = jnp.where(
neq_neg1_mask, high_tangent_neq_neg1, high_tangent_eq_neg1
)
# Final tangents
tangent_out = (
alpha / x * x_t
+ alpha_tangent * alpha_t
+ low_tangent * low_t
+ high_tangent * high_t
)
return primal_out, tangent_out
return f(value, self.alpha, self.low, self.high)
[docs]
def cdf(self, value: ArrayLike) -> Array:
r"""Cumulative distribution function for :math:`a \leq x \leq b`.
For :math:`\alpha \ne -1`:
.. math::
\frac{x^{\alpha + 1} - a^{\alpha + 1}}{b^{\alpha + 1} - a^{\alpha + 1}}
For :math:`\alpha = -1`:
.. math::
\frac{\log(x) - \log(a)}{\log(b) - \log(a)}
Derivations are calculated by Wolfram Alpha via the Jacobian matrix accordingly.
"""
@jax.custom_jvp
def f(x: ArrayLike, alpha: ArrayLike, low: ArrayLike, high: ArrayLike) -> Array:
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
def cdf_when_alpha_neq_neg1() -> Array:
one_more_alpha = 1.0 + neq_neg1_alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
return (jnp.power(x, one_more_alpha) - low_pow_one_more_alpha) / (
jnp.power(high, one_more_alpha) - low_pow_one_more_alpha
)
def cdf_when_alpha_eq_neg1() -> Array:
return jnp.log(x / low) / jnp.log(high / low)
cdf_val = jnp.where(
neq_neg1_mask,
cdf_when_alpha_neq_neg1(),
cdf_when_alpha_eq_neg1(),
)
return jnp.clip(cdf_val, 0.0, 1.0)
@f.defjvp
def f_jvp(
primals: tuple[Array, Array, Array, Array],
tangents: tuple[Array, Array, Array, Array],
) -> tuple[Array, Array]:
x, alpha, low, high = primals
x_t, alpha_t, low_t, high_t = tangents
log_low = jnp.log(low)
log_high = jnp.log(high)
log_x = jnp.log(x)
delta_eq_neg1 = 10e-4
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
# Calculate primal
primal_out = f(*primals)
# Tangents for alpha not equals -1
def x_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
return (one_more_alpha * jnp.power(x, alpha)) / (
jnp.power(high, one_more_alpha) - jnp.power(low, one_more_alpha)
)
def alpha_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
x_pow_one_more_alpha = jnp.power(x, one_more_alpha)
term1 = (
x_pow_one_more_alpha * log_x - low_pow_one_more_alpha * log_low
) / (high_pow_one_more_alpha - low_pow_one_more_alpha)
term2 = (
(x_pow_one_more_alpha - low_pow_one_more_alpha)
* (
high_pow_one_more_alpha * log_high
- low_pow_one_more_alpha * log_low
)
) / jnp.square(high_pow_one_more_alpha - low_pow_one_more_alpha)
return term1 - term2
def low_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
x_pow_one_more_alpha = jnp.power(x, one_more_alpha)
change = high_pow_one_more_alpha - low_pow_one_more_alpha
term2 = one_more_alpha * jnp.power(low, alpha) / change
term1 = term2 * (x_pow_one_more_alpha - low_pow_one_more_alpha) / change
return term1 - term2
def high_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
x_pow_one_more_alpha = jnp.power(x, one_more_alpha)
return -(
one_more_alpha
* jnp.power(high, alpha)
* (x_pow_one_more_alpha - low_pow_one_more_alpha)
) / jnp.square(high_pow_one_more_alpha - low_pow_one_more_alpha)
# Tangents for alpha equals -1
def x_eq_neg1() -> Array:
return jnp.reciprocal(x * (log_high - log_low))
def low_eq_neg1() -> Array:
return (log_x - log_low) / (
jnp.square(log_high - log_low) * low
) - jnp.reciprocal((log_high - log_low) * low)
def high_eq_neg1() -> Array:
return -(log_x - log_low) / (jnp.square(log_high - log_low) * high)
# Including approximation for alpha = -1
tangent_out = (
jnp.where(neq_neg1_mask, x_neq_neg1(neq_neg1_alpha), x_eq_neg1()) * x_t
+ jnp.where(
neq_neg1_mask,
alpha_neq_neg1(neq_neg1_alpha),
(
alpha_neq_neg1(alpha - delta_eq_neg1)
+ alpha_neq_neg1(alpha + delta_eq_neg1)
)
* 0.5,
)
* alpha_t
+ jnp.where(neq_neg1_mask, low_neq_neg1(neq_neg1_alpha), low_eq_neg1())
* low_t
+ jnp.where(
neq_neg1_mask, high_neq_neg1(neq_neg1_alpha), high_eq_neg1()
)
* high_t
)
return primal_out, tangent_out
return f(value, self.alpha, self.low, self.high)
[docs]
def icdf(self, q: ArrayLike) -> Array:
r"""Inverse cumulative distribution function for :math:`0 \leq q \leq 1`.
For :math:`\alpha = -1`:
.. math::
a \left(\frac{b}{a}\right)^{q}
For :math:`\alpha \ne -1`:
.. math::
\left(a^{1 + \alpha} + q (b^{1 + \alpha} - a^{1 + \alpha})\right)^{\frac{1}{1 + \alpha}}
Derivations are calculated by Wolfram Alpha via the Jacobian matrix accordingly.
"""
@jax.custom_jvp
def f(q: ArrayLike, alpha: ArrayLike, low: ArrayLike, high: ArrayLike) -> Array:
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
def icdf_alpha_neq_neg1() -> Array:
one_more_alpha = 1.0 + neq_neg1_alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
return jnp.power(
low_pow_one_more_alpha
+ q * (high_pow_one_more_alpha - low_pow_one_more_alpha),
jnp.reciprocal(one_more_alpha),
)
def icdf_alpha_eq_neg1() -> Array:
return jnp.power(high / low, q) * low
icdf_val = jnp.where(
neq_neg1_mask,
icdf_alpha_neq_neg1(),
icdf_alpha_eq_neg1(),
)
return icdf_val
@f.defjvp
def f_jvp(
primals: tuple[Array, Array, Array, Array],
tangents: tuple[Array, Array, Array, Array],
) -> tuple[Array, Array]:
x, alpha, low, high = primals
x_t, alpha_t, low_t, high_t = tangents
log_low = jnp.log(low)
log_high = jnp.log(high)
high_over_low = jnp.divide(high, low)
delta_eq_neg1 = 10e-4
neq_neg1_mask = jnp.not_equal(alpha, -1.0)
neq_neg1_alpha = jnp.where(neq_neg1_mask, alpha, 0.0)
primal_out = f(*primals)
# Tangents for alpha not equal -1
def x_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
change = high_pow_one_more_alpha - low_pow_one_more_alpha
return (
change
* jnp.power(
low_pow_one_more_alpha + x * change,
jnp.reciprocal(one_more_alpha) - 1,
)
) / one_more_alpha
def alpha_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
factor0 = low_pow_one_more_alpha + x * (
high_pow_one_more_alpha - low_pow_one_more_alpha
)
term1 = jnp.power(factor0, jnp.reciprocal(one_more_alpha))
term2 = (
low_pow_one_more_alpha * log_low
+ x
* (
high_pow_one_more_alpha * log_high
- low_pow_one_more_alpha * log_low
)
) / (one_more_alpha * factor0)
term3 = jnp.log(factor0) / jnp.square(one_more_alpha)
return term1 * (term2 - term3)
def low_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
return (
(1.0 - x)
* jnp.power(low, alpha)
* jnp.power(
low_pow_one_more_alpha
+ x * (high_pow_one_more_alpha - low_pow_one_more_alpha),
jnp.reciprocal(one_more_alpha) - 1,
)
)
def high_neq_neg1(alpha: ArrayLike) -> Array:
one_more_alpha = 1.0 + alpha
low_pow_one_more_alpha = jnp.power(low, one_more_alpha)
high_pow_one_more_alpha = jnp.power(high, one_more_alpha)
return (
x
* jnp.power(high, alpha)
* jnp.power(
low_pow_one_more_alpha
+ x * (high_pow_one_more_alpha - low_pow_one_more_alpha),
jnp.reciprocal(one_more_alpha) - 1,
)
)
# Tangents for alpha equals -1
def dx_eq_neg1() -> Array:
return low * jnp.power(high_over_low, x) * (log_high - log_low)
def low_eq_neg1() -> Array:
return (
jnp.power(high_over_low, x)
- (high * x * jnp.power(high_over_low, x - 1)) / low
)
def high_eq_neg1() -> Array:
return x * jnp.power(high_over_low, x - 1)
# Including approximation for alpha = -1 \
tangent_out = (
jnp.where(neq_neg1_mask, x_neq_neg1(neq_neg1_alpha), dx_eq_neg1()) * x_t
+ jnp.where(
neq_neg1_mask,
alpha_neq_neg1(neq_neg1_alpha),
(
alpha_neq_neg1(alpha - delta_eq_neg1)
+ alpha_neq_neg1(alpha + delta_eq_neg1)
)
* 0.5,
)
* alpha_t
+ jnp.where(neq_neg1_mask, low_neq_neg1(neq_neg1_alpha), low_eq_neg1())
* low_t
+ jnp.where(
neq_neg1_mask, high_neq_neg1(neq_neg1_alpha), high_eq_neg1()
)
* high_t
)
return primal_out, tangent_out
return f(q, self.alpha, self.low, self.high)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
u = random.uniform(key, sample_shape + self.batch_shape)
samples = self.icdf(u)
return samples
[docs]
class LowerTruncatedPowerLaw(Distribution):
r"""Lower truncated power law distribution with :math:`\alpha` index.
We can define the power law distribution as,
.. math::
f(x; \alpha, a) = (-\alpha-1)a^{-\alpha - 1}x^{\alpha},
\qquad x > a > 0, \qquad \alpha < -1,
where, :math:`a` is the lower bound, so that
.. math::
\log f(x; \alpha, a) = \alpha \log x + \log(-\alpha - 1)
- (1 + \alpha) \log a.
The cdf of the distribution is given by,
.. math::
F(x; \alpha, a) = 1 - \left(\frac{x}{a}\right)^{1+\alpha},
and the quantile function by
.. math::
F^{-1}(q; \alpha, a) = a \, (1 - q)^{1 / (1 + \alpha)},
which is used for inverse-cdf sampling. The k-th moment of the distribution is
given by,
.. math::
E[X^k] = \begin{cases}
\frac{-\alpha-1}{-\alpha-1-k}a^k & \text{if } k < -\alpha-1, \\
\infty & \text{otherwise}.
\end{cases}
This is the same law as
:class:`~numpyro.distributions.continuous.Pareto` with ``scale`` :math:`= a`
and ``alpha`` :math:`= -\alpha - 1`.
:param alpha: index :math:`\alpha < -1` of the power law distribution
:param low: lower bound :math:`a > 0` of the distribution
.. note::
``cdf`` returns :math:`0` for :math:`x \leq a`; ``icdf`` returns ``nan``
outside :math:`[0, 1]`. ``mean`` and ``variance`` are not implemented even
though the moment formula above is available.
"""
arg_constraints = {
"alpha": constraints.less_than(-1.0),
"low": constraints.greater_than(0.0),
}
reparametrized_params = ["alpha", "low"]
pytree_data_fields = ("alpha", "low", "_support")
_support: constraints.Constraint
def __init__(
self, alpha: ArrayLike, low: ArrayLike, *, validate_args: Optional[bool] = None
):
self.alpha, self.low = promote_shapes(alpha, low)
batch_shape = lax.broadcast_shapes(jnp.shape(alpha), jnp.shape(low))
self._support = constraints.greater_than(cast(NumLike, low))
super(LowerTruncatedPowerLaw, self).__init__(
batch_shape=batch_shape, validate_args=validate_args
)
@constraints.dependent_property(is_discrete=False, event_dim=0)
def support(self) -> Constraint:
return self._support
[docs]
@validate_sample
def log_prob(self, value: ArrayLike) -> Array:
one_more_alpha = 1.0 + self.alpha
return (
self.alpha * jnp.log(value)
+ jnp.log(-one_more_alpha)
- one_more_alpha * jnp.log(self.low)
)
[docs]
def cdf(self, value: ArrayLike) -> Array:
cdf_val = jnp.where(
jnp.less_equal(value, self.low),
jnp.zeros_like(value),
1.0 - jnp.power(value / self.low, 1.0 + self.alpha),
)
return cdf_val
[docs]
def icdf(self, q: ArrayLike) -> Array:
nan_mask = jnp.logical_or(jnp.isnan(q), jnp.less(q, 0.0))
nan_mask = jnp.logical_or(nan_mask, jnp.greater(q, 1.0))
return jnp.where(
nan_mask,
jnp.nan,
self.low * jnp.power(1.0 - q, jnp.reciprocal(1.0 + self.alpha)),
)
[docs]
def sample(
self, key: Optional[jax.Array], sample_shape: tuple[int, ...] = ()
) -> Array:
assert is_prng_key(key)
assert key is not None
u = random.uniform(key, sample_shape + self.batch_shape)
samples = self.icdf(u)
return samples