Distributions

Base Distribution

Distribution

class Distribution(batch_shape: tuple[int, ...] = (), event_shape: tuple[int, ...] = (), *, validate_args: bool | None = None)[source]

Bases: object

Base class for probability distributions in NumPyro. The design largely follows from torch.distributions.

Parameters:
  • batch_shape – The batch shape for the distribution. This designates independent (possibly non-identical) dimensions of a sample from the distribution. This is fixed for a distribution instance and is inferred from the shape of the distribution parameters.

  • event_shape – The event shape for the distribution. This designates the dependent dimensions of a sample from the distribution. These are collapsed when we evaluate the log probability density of a batch of samples using .log_prob.

  • validate_args – Whether to enable validation of distribution parameters and arguments to .log_prob method.

This class defines no density of its own; what every subclass honors is the batch/event contract. An instance with batch_shape \(B\) and event_shape \(E\) represents a family \(\{p_b : b \in B\}\) of densities (or mass functions) on \(\mathbb{R}^{E}\), one per batch index \(b\). In terms of this family:

  • sample(key, sample_shape=S) returns \(x\) of shape \(S + B + E\) where, for every \(s \in S\) and \(b \in B\), \(x_{s,b} \sim p_b\) independently.

  • log_prob(x) returns an array of shape \(\mathrm{broadcast}(x.\mathrm{shape}[:-|E|], B)\) with entries \(\log p_b(x_{\ldots,b})\); event dimensions are never broadcast and are summed over inside the density.

  • to_event(k) (returning Independent) moves the \(k\) rightmost batch dimensions into the event, so that \(\log p(x) = \sum_{i} \log p_{b,i}(x_{b,i})\) over the moved indices.

  • expand(B') (returning ExpandedDistribution, or self when \(B' = B\)) broadcasts \(p_b\) to the larger batch shape \(B'\); mask(m) (returning MaskedDistribution, or self when m is True) replaces \(\log p_b\) by \(0\) where \(m_b\) is False.

  • support is a Constraint describing the set on which \(p_b\) is positive; arg_constraints gives the domain of each parameter and drives validate_args and, unless a subclass sets pytree_data_fields, the pytree flattening of the instance.

  • has_rsample is by default True iff the set of reparametrized_params equals the set of arg_constraints keys, in which case rsample returns a pathwise-differentiable draw; wrapper distributions delegate to their base.

Note

sample, log_prob, mean, variance, mode, cdf, icdf, entropy and enumerate_support raise NotImplementedError unless a subclass defines them.

As an example:

>>> import jax.numpy as jnp
>>> import numpyro.distributions as dist
>>> d = dist.Dirichlet(jnp.ones((2, 3, 4)))
>>> d.batch_shape
(2, 3)
>>> d.event_shape
(4,)
arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ()
pytree_aux_fields: tuple[str, ...] = ('_batch_shape', '_event_shape')
property support: Constraint | None

The support of this distribution. Subclasses can override this as a class attribute or as a property.

has_enumerate_support: bool = False
reparametrized_params: list[str] = []
classmethod gather_pytree_data_fields() → tuple[str, ...][source]
classmethod gather_pytree_aux_fields() → tuple[str, ...][source]
tree_flatten() → tuple[tuple[Any, ...], tuple[Any, ...]][source]
classmethod tree_unflatten(aux_data: tuple[Any, ...], params: tuple[Any, ...]) → Distribution[source]
static set_default_validate_args(value: bool) → None[source]
get_args() → dict[str, Any][source]

Get arguments of the distribution.

validate_args(strict: bool = True) → None[source]

Validate the arguments of the distribution.

Parameters:

strict – Require strict validation, raising an error if the function is called inside jitted code.

property batch_shape: tuple[int, ...]

Returns the shape over which the distribution parameters are batched.

Returns:

batch shape of the distribution.

Return type:

tuple[int, …]

property event_shape: tuple[int, ...]

Returns the shape of a single sample from the distribution without batching.

Returns:

event shape of the distribution.

Return type:

tuple[int, …]

property event_dim: int
Returns:

Number of dimensions of individual events.

Return type:

int

property has_rsample: bool
rsample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]
shape(sample_shape: tuple[int, ...] = ()) → tuple[int, ...][source]

The tensor shape of samples from this distribution.

Samples are of shape:

d.shape(sample_shape) == sample_shape + d.batch_shape + d.event_shape
Parameters:

sample_shape (tuple) – the size of the iid batch to be drawn from the distribution.

Returns:

shape of samples.

Return type:

tuple

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

sample_with_intermediates(key: Array | None, sample_shape: tuple[int, ...] = ()) → tuple[Array | ndarray | bool | number | bool | int | float | complex, list[Any]][source]

Same as sample except that any intermediate computations are returned (useful for TransformedDistribution).

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

property mode: Array

Mode of the distribution.

to_event(reinterpreted_batch_ndims: int | None = None) → Distribution[source]

Interpret the rightmost reinterpreted_batch_ndims batch dimensions as dependent event dimensions.

Parameters:

reinterpreted_batch_ndims – Number of rightmost batch dims to interpret as event dims.

Returns:

An instance of Independent distribution.

Return type:

numpyro.distributions.distribution.Independent

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

entropy() → Array[source]

Returns the entropy of the distribution.

expand(batch_shape: Sequence[int]) → Distribution[source]

Returns a new ExpandedDistribution instance with batch dimensions expanded to batch_shape.

Parameters:

batch_shape (tuple) – batch shape to expand to.

Returns:

an instance of ExpandedDistribution.

Return type:

ExpandedDistribution

expand_by(sample_shape: Sequence[int]) → Distribution[source]

Expands a distribution by adding sample_shape to the left side of its batch_shape. To expand internal dims of self.batch_shape from 1 to something larger, use expand() instead.

Parameters:

sample_shape (tuple) – The size of the iid batch to be drawn from the distribution.

Returns:

An expanded version of this distribution.

Return type:

ExpandedDistribution

mask(mask: Array) → MaskedDistribution[source]

Masks a distribution by a boolean or boolean-valued array that is broadcastable to the distributions Distribution.batch_shape .

Parameters:

mask (bool or jnp.ndarray) – A boolean or boolean valued array (True includes a site, False excludes a site).

Returns:

A masked copy of this distribution.

Return type:

MaskedDistribution

Example:

>>> from jax import random
>>> import jax.numpy as jnp
>>> import numpyro
>>> import numpyro.distributions as dist
>>> from numpyro.distributions import constraints
>>> from numpyro.infer import SVI, Trace_ELBO

>>> def model(data, m):
...     f = numpyro.sample("latent_fairness", dist.Beta(1, 1))
...     with numpyro.plate("N", data.shape[0]):
...         # only take into account the values selected by the mask
...         masked_dist = dist.Bernoulli(f).mask(m)
...         numpyro.sample("obs", masked_dist, obs=data)


>>> def guide(data, m):
...     alpha_q = numpyro.param("alpha_q", 5., constraint=constraints.positive)
...     beta_q = numpyro.param("beta_q", 5., constraint=constraints.positive)
...     numpyro.sample("latent_fairness", dist.Beta(alpha_q, beta_q))


>>> data = jnp.concatenate([jnp.ones(5), jnp.zeros(5)])
>>> # select values equal to one
>>> masked_array = jnp.where(data == 1, True, False)
>>> optimizer = numpyro.optim.Adam(step_size=0.05)
>>> svi = SVI(model, guide, optimizer, loss=Trace_ELBO())
>>> svi_result = svi.run(random.key(0), 300, data, masked_array)
>>> params = svi_result.params
>>> # inferred_mean is closer to 1
>>> inferred_mean = params["alpha_q"] / (params["alpha_q"] + params["beta_q"])
classmethod infer_shapes(*args: Any, **kwargs: Any) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

property is_discrete: bool

ExpandedDistribution

class ExpandedDistribution(base_dist: Distribution, batch_shape: tuple[int, ...] = ())[source]

Bases: Distribution

Broadcasts the batch shape of a distribution to a larger batch_shape.

If the base distribution has batch shape \(B_0\) (densities \(p_{b_0}\)) and the target batch shape is \(B \supseteq B_0\) under NumPy broadcasting, the expanded distribution has density \(p_b = p_{\pi(b)}\) where \(\pi: B \to B_0\) maps each batch index to the base index it broadcasts from. Consequently

\[\log p(x)_b = \log p_{\pi(b)}(x_b), \qquad \mathbb{E}[X_b] = \mathbb{E}[X_{\pi(b)}], \qquad \operatorname{Var}[X_b] = \operatorname{Var}[X_{\pi(b)}],\]

and entropy broadcasts the same way. Samples are independent draws for every expanded batch index (not tiled copies of one base draw): \(x_b \sim p_{\pi(b)}\) independently over \(b \in B\).

Parameters:
  • base_dist – The distribution to expand.

  • batch_shape – The target batch shape; must be broadcastable from base_dist.batch_shape.

Raises:

ValueError – if base_dist.batch_shape cannot be broadcast to batch_shape.

Note

New leading batch dimensions are recorded as _expanded_sizes and size-1 base dimensions that are widened as _interstitial_sizes. sample draws sample_shape + expanded + interstitial independent base samples and transposes the interstitial axes into place. log_prob is the base log density broadcast to broadcast(batch_shape, value.shape[:-event_dim]); the value itself is passed to the base unchanged. Expanding an ExpandedDistribution flattens it to its inner base distribution. The constructor takes no validate_args and log_prob performs no sample validation. support, has_rsample and has_enumerate_support are those of the base distribution. Usually constructed via Distribution.expand().

arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ('base_dist',)
pytree_aux_fields: tuple[str, ...] = ('_expanded_sizes', '_interstitial_sizes', 'has_enumerate_support')
base_dist: Distribution
property has_rsample: bool
rsample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample_with_intermediates(key: Array | None, sample_shape: tuple[int, ...] = ()) → tuple[Array | ndarray | bool | number | bool | int | float | complex, list[Array | ndarray | bool | number | bool | int | float | complex]][source]

Same as sample except that any intermediate computations are returned (useful for TransformedDistribution).

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

entropy() → Array[source]

Returns the entropy of the distribution.

FoldedDistribution

class FoldedDistribution(base_dist: Distribution, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Equivalent to TransformedDistribution(base_dist, AbsTransform()), but additionally supports log_prob() .

If \(X\) has density \(p_X\), then \(Y = |X|\) has density

\[p_Y(y) = p_X(y) + p_X(-y), \qquad y \ge 0,\]

so log_prob() computes \(\log p_Y(y) = \operatorname{logsumexp}\{\log p_X(y), \log p_X(-y)\}\).

Parameters:

base_dist (Distribution) – A univariate continuous distribution to reflect.

support = Positive(lower_bound=0.0)
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

ImproperUniform

class ImproperUniform(support: constraints.Constraint, batch_shape: tuple[int, ...], event_shape: tuple[int, ...], *, validate_args: bool | None = None)[source]

Bases: Distribution

A helper distribution with zero log_prob() over the support domain.

The density is flat on the support \(\mathcal{S}\),

\[p(x) \propto 1, \qquad \log p(x) = 0 \quad \text{for } x \in \mathcal{S},\]

and is improper: it does not integrate to one, so it only contributes a constant to the joint log density of a model. This makes it useful as a flat prior whose posterior is determined by the likelihood and by the support constraint alone. When validate_args is enabled, values outside the support get \(\log p(x) = -\infty\) (the check is reduced over the event dimensions, so a single invalid event entry rejects the whole event).

Note

sample method is not implemented for this distribution. In autoguide and mcmc, initial parameters for improper sites are derived from init_to_uniform or init_to_value strategies.

Usage:

>>> from numpyro import sample
>>> from numpyro.distributions import ImproperUniform, Normal, constraints
>>>
>>> def model():
...     # ordered vector with length 10
...     x = sample('x', ImproperUniform(constraints.ordered_vector, (), event_shape=(10,)))
...
...     # real matrix with shape (3, 4)
...     y = sample('y', ImproperUniform(constraints.real, (), event_shape=(3, 4)))
...
...     # a shape-(6, 8) batch of length-5 vectors greater than 3
...     z = sample('z', ImproperUniform(constraints.greater_than(3), (6, 8), event_shape=(5,)))

If you want to set improper prior over all values greater than a, where a is another random variable, you might use

>>> def model():
...     a = sample('a', Normal(0, 1))
...     x = sample('x', ImproperUniform(constraints.greater_than(a), (), event_shape=()))

or if you want to reparameterize it

>>> from numpyro.distributions import TransformedDistribution, transforms
>>> from numpyro.handlers import reparam
>>> from numpyro.infer.reparam import TransformReparam
>>>
>>> def model():
...     a = sample('a', Normal(0, 1))
...     with reparam(config={'x': TransformReparam()}):
...         x = sample('x',
...                    TransformedDistribution(ImproperUniform(constraints.positive, (), ()),
...                                            transforms.AffineTransform(a, 1)))
Parameters:
  • support (Constraint) – the support of this distribution.

  • batch_shape (tuple) – batch shape of this distribution. It is usually safe to set batch_shape=().

  • event_shape (tuple) – event shape of this distribution.

arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ('support',)
support: Constraint = Dependent()
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

Independent

class Independent(base_dist: Distribution, reinterpreted_batch_ndims: int, *, validate_args: bool | None = None)[source]

Bases: Distribution

Reinterprets batch dimensions of a distribution as event dims by shifting the batch-event dim boundary further to the left.

If the base distribution has density \(p_{\text{base}}\) with batch shape \((b_1, \ldots, b_n)\) and \(k\) is reinterpreted_batch_ndims, the resulting distribution has batch shape \((b_1, \ldots, b_{n-k})\), event shape \((b_{n-k+1}, \ldots, b_n)\) followed by the base event shape, and density

\[\log p(x) = \sum_{i_1=1}^{b_{n-k+1}} \cdots \sum_{i_k=1}^{b_n} \log p_{\text{base}}\big(x_{i_1, \ldots, i_k}\big),\]

i.e. the reinterpreted components are treated as independent and their log densities are summed. The entropy sums the same way, while mean and variance are unchanged elementwise. The support becomes constraints.independent(base_dist.support, k).

From a practical standpoint, this is useful when changing the result of log_prob(). For example, a univariate Normal distribution can be interpreted as a multivariate Normal with diagonal covariance:

>>> import numpyro.distributions as dist
>>> normal = dist.Normal(jnp.zeros(3), jnp.ones(3))
>>> [normal.batch_shape, normal.event_shape]
[(3,), ()]
>>> diag_normal = dist.Independent(normal, 1)
>>> [diag_normal.batch_shape, diag_normal.event_shape]
[(), (3,)]
Parameters:
  • base_dist (numpyro.distribution.Distribution) – a distribution instance.

  • reinterpreted_batch_ndims (int) – the number of batch dims to reinterpret as event dims.

arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ('base_dist',)
pytree_aux_fields: tuple[str, ...] = ('reinterpreted_batch_ndims', 'has_enumerate_support')
base_dist: Distribution
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

property has_rsample: bool
rsample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

sample_with_intermediates(key: Array | None, sample_shape: tuple[int, ...] = ()) → tuple[Array | ndarray | bool | number | bool | int | float | complex, list[Any]][source]

Same as sample except that any intermediate computations are returned (useful for TransformedDistribution).

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

expand(batch_shape: Sequence[int]) → Distribution[source]

Returns a new ExpandedDistribution instance with batch dimensions expanded to batch_shape.

Parameters:

batch_shape (tuple) – batch shape to expand to.

Returns:

an instance of ExpandedDistribution.

Return type:

ExpandedDistribution

entropy() → Array[source]

Returns the entropy of the distribution.

MaskedDistribution

class MaskedDistribution(base_dist: Distribution, mask: bool | Array)[source]

Bases: Distribution

Masks a distribution by a boolean array that is broadcastable to the distribution’s Distribution.batch_shape. In the special case mask is False, computation of log_prob() , is skipped, and constant zero values are returned instead.

With a boolean mask \(m\) broadcastable to the batch shape,

\[\begin{split}\log p(x)_b = \begin{cases} \log p_{\text{base}}(x_b) & m_b = \text{True} \\ 0 & m_b = \text{False}, \end{cases}\end{split}\]

i.e. masked-out batch entries contribute a likelihood factor of \(1\). This is the standard device for missing or padded observations: the joint density of the kept entries is unchanged while the rest are marginalized out of the likelihood.

Parameters:

mask (jnp.ndarray or bool) – A boolean or boolean-valued array.

Note

When mask is False, log_prob returns zeros of the broadcast batch shape without evaluating the base distribution; when mask is True it returns the base log_prob unchanged. Otherwise masked-out values are first replaced by support.feasible_like(value) so the base density never sees out-of-support entries (avoiding nan gradients; falls back to the raw value when feasible_like is unavailable), and the result is where(mask, base_log_prob, 0). The intermediates argument is accepted but not forwarded to the base. sample, mean, variance, support and enumerate_support are those of the base distribution; the mask does not affect them. A non-scalar mask broadcasts the base distribution to broadcast(mask.shape, base.batch_shape). Usually constructed via Distribution.mask().

arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ('base_dist', '_mask')
pytree_aux_fields: tuple[str, ...] = ('_mask', 'has_enumerate_support')
base_dist: Distribution
property has_rsample: bool
rsample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

tree_flatten() → tuple[tuple[Any, ...], tuple[Any, ...]][source]
classmethod tree_unflatten(aux_data: tuple[Any, ...], params: tuple[Any, ...]) → MaskedDistribution[source]

TransformedDistribution

class TransformedDistribution(base_distribution: Distribution, transforms: Transform | list[Transform], *, validate_args: bool | None = None)[source]

Bases: Distribution

Returns a distribution instance obtained as a result of applying a sequence of transforms to a base distribution. For an example, see LogNormal and HalfNormal.

If \(X \sim p_X\) and \(Y = g_m \circ \cdots \circ g_1(X)\) for bijective transforms \(g_1, \ldots, g_m\), the change-of-variables formula gives

\[\log p_Y(y) = \log p_X(x_0) - \sum_{i=1}^{m} \log\left|\det J_{g_i}(x_{i-1})\right|, \qquad x_m = y, \quad x_{i-1} = g_i^{-1}(x_i),\]

where \(J_{g_i}\) is the Jacobian of \(g_i\). For univariate transforms the cdf is \(F_Y(y) = F_X(g^{-1}(y))\) when the composition \(g\) is increasing and \(1 - F_X(g^{-1}(y))\) when it is decreasing, with the direction given by the product of the transforms’ sign attributes; icdf applies the same rule.

Note

sample applies the transforms in list order; log_prob inverts them in reverse order and subtracts each log_abs_det_jacobian, summed over the event dimensions that the transform treats as batch dimensions. sample_with_intermediates() records the input of every transform so that log_prob(value, intermediates) can skip the inverses. Nesting a TransformedDistribution flattens its transforms into the list; the base distribution is expanded and its batch dimensions reinterpreted as event dimensions as needed to match the domain of the composed transform. The support is the codomain of the last transform, lifted with constraints.independent over any extra event dimensions; mean and variance are not implemented.

Parameters:
  • base_distribution – the base distribution over which to apply transforms.

  • transforms – a single transform or a list of transforms.

  • validate_args – Whether to enable validation of distribution parameters and arguments to .log_prob method. If enabled, a ValueError is also raised when the support of the base distribution is known to extend beyond the domain of the first transform. Only the bounds are compared, so end points are not checked.

arg_constraints: dict[str, Any] = {}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'transforms')
transforms: list[Transform]
base_dist: Distribution
validate_args(strict: bool = True) → None[source]

Validate the arguments of the distribution.

Parameters:

strict – Require strict validation, raising an error if the function is called inside jitted code.

property has_rsample: bool
rsample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

sample_with_intermediates(key: Array | None, sample_shape: tuple[int, ...] = ()) → tuple[Array | ndarray | bool | number | bool | int | float | complex, list[Any]][source]

Same as sample except that any intermediate computations are returned (useful for TransformedDistribution).

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

Delta

class Delta(v: ArrayLike = 0.0, log_density: ArrayLike = 0.0, event_dim: int = 0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Degenerate distribution that places all of its mass on a single point v, optionally reweighted by an additive log_density term.

Writing \(v\) for the support point and \(c\) for the log_density offset, the log density is

\[\begin{split}\log p(x) = \log c + \begin{cases} 0 & \text{if } x = v, \\ -\infty & \text{otherwise,} \end{cases}\end{split}\]

so with the default log_density = 0 the distribution reduces to the Dirac delta \(\delta(x - v)\). The log_density term does not move the support; it only shifts the log density by a constant, which is useful for representing deterministic values while tracking an accompanying log-weight (for example a change-of-variables Jacobian). When event_dim > 0 the trailing dimensions of v are treated as event dimensions and the per-element indicators are summed over them.

Parameters:
  • v (numpy.ndarray) – The support point on which all mass is placed.

  • log_density (numpy.ndarray) – An additive offset applied to the log density, broadcast to the batch shape.

  • event_dim (int) – The number of trailing dimensions of v to treat as event dimensions.

arg_constraints: dict[str, Any] = {'log_density': Real(), 'v': Dependent()}
reparametrized_params: list[str] = ['v', 'log_density']
property support: Constraint

Support of the distribution.

The support is the real line (extended to event_dim event dimensions), even though all probability mass is concentrated at v.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Draw samples from the distribution.

Sampling is deterministic: every draw equals the support point \(v\), broadcast to sample_shape + batch_shape + event_shape. The PRNG key is therefore unused.

Parameters:
  • key – A JAX PRNG key (unused).

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Samples that are all equal to v.

Return type:

ArrayLike

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array | ndarray | bool | number | bool | int | float | complex[source]

Calculate the log density.

\[\begin{split}\log p(x) = \log c + \sum_{\text{event}} \begin{cases} 0 & \text{if } x = v, \\ -\infty & \text{otherwise,} \end{cases}\end{split}\]

where \(c\) is log_density. Elementwise indicators are summed over the event dimensions before the log_density offset is added, so any coordinate differing from v yields \(-\infty\).

Parameters:

value – Values at which to evaluate the log density.

Returns:

Log density.

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

\[E[X] = v\]
property variance: Array

Variance of the distribution.

Because all mass sits on the single point v, the variance is zero.

\[\operatorname{Var}(X) = 0\]
entropy() → Array[source]

Entropy of the distribution.

\[H(X) = -\log c\]

where \(c\) is log_density; with the default log_density = 0 the point mass has zero entropy.

Unit

class Unit(log_factor: ArrayLike, *, validate_args: bool = False)[source]

Bases: Distribution

Trivial nonnormalized distribution representing the unit type.

The unit type has a single value with no data, i.e. value.size == 0. Writing \(c\) for log_factor, the unnormalized log density at that value is

\[\log p(\varnothing) = c,\]

so the distribution contributes the constant \(c\) to the joint log density. The batch shape is jnp.shape(log_factor) and the event shape is (0,); sample() returns an empty array of that shape, and log_prob() ignores the contents of value and broadcasts log_factor against its batch dimensions.

This is used for numpyro.factor() statements.

Parameters:

log_factor (numpy.ndarray) – A possibly batched log probability factor.

arg_constraints: dict[str, Any] = {'log_factor': Real()}
support = Real()
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array | ndarray | bool | number | bool | int | float | complex[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

Continuous Distributions

AsymmetricLaplace

class AsymmetricLaplace(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, asymmetry: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Asymmetric Laplace distribution on \(\mathbb{R}\) with location \(\mu\), scale \(\sigma > 0\) and asymmetry \(\kappa > 0\). It generalizes Laplace by using different exponential decay rates on either side of the location: the left and right scales are \(\sigma \kappa\) and \(\sigma / \kappa\), so \(\kappa = 1\) recovers Laplace while larger \(\kappa\) puts more spread (and more mass) below \(\mu\).

The Probability Density Function (PDF) of the Asymmetric Laplace distribution is defined as:

\[\begin{split}f(x ; \mu, \sigma, \kappa) = \frac{\kappa}{\sigma (1 + \kappa^2)} \begin{cases} \exp\left(-\displaystyle\frac{|x - \mu|}{\sigma \kappa}\right) & x < \mu, \\ \exp\left(-\kappa \displaystyle\frac{|x - \mu|}{\sigma}\right) & x \geq \mu, \end{cases}\end{split}\]

where \(\mu\) is loc (the mode), \(\sigma\) is scale and \(\kappa\) is asymmetry. The probability mass below \(\mu\) is \(\kappa^2 / (1 + \kappa^2)\), the mean is \(\mu + \sigma (1 / \kappa - \kappa)\) and the variance is \(\sigma^2 (\kappa^2 + \kappa^{-2})\). A draw can be represented as \(\mu - \sigma \kappa \, U + (\sigma / \kappa) \, V\) with independent \(U, V \sim \mathrm{Exponential}(1)\).

Parameters:
  • loc – Location \(\mu \in \mathbb{R}\) (the mode). Defaults to 0.0.

  • scale – Scale \(\sigma > 0\). Defaults to 1.0.

  • asymmetry – Asymmetry \(\kappa > 0\); 1.0 gives the symmetric Laplace distribution. Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'asymmetry': Positive(lower_bound=0.0), 'loc': Real(), 'scale': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['loc', 'scale', 'asymmetry']
support = Real()
left_scale()[source]

Scale of the exponential decay below loc, \(\sigma \kappa\).

right_scale()[source]

Scale of the exponential decay above loc, \(\sigma / \kappa\).

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array[source]

Evaluate the log probability density function at value:

\[\begin{split}\ln f(x ; \mu, \sigma, \kappa) = -\frac{|x - \mu|}{s(x)} - \ln\!\left(\sigma \kappa + \frac{\sigma}{\kappa}\right), \qquad s(x) = \begin{cases} \sigma \kappa & x < \mu, \\ \sigma / \kappa & x \geq \mu. \end{cases}\end{split}\]
Parameters:
  • value – Real-valued point \(x\) at which to evaluate the log PDF.

  • intermediates – Not used.

Returns:

Log probability density evaluated under the asymmetric Laplace distribution.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the scale-mixture representation \(X = \mu - \sigma \kappa \, U + (\sigma / \kappa) \, V\) with independent \(U, V \sim \mathrm{Exponential}(1)\) drawn from exponential().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the asymmetric Laplace distribution.

property mean: Array

Mean of the asymmetric Laplace distribution:

\[\mathbb{E}[X] = \mu + \sigma \left(\frac{1}{\kappa} - \kappa\right)\]
property variance: Array

Variance of the asymmetric Laplace distribution:

\[\mathrm{Var}(X) = \sigma^2 \left(\kappa^2 + \kappa^{-2}\right)\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the asymmetric Laplace distribution:

\[\begin{split}F(x ; \mu, \sigma, \kappa) = \begin{cases} \displaystyle\frac{\kappa^2}{1 + \kappa^2} \exp\left(-\displaystyle\frac{|x - \mu|}{\sigma \kappa}\right) & x < \mu, \\ 1 - \displaystyle\frac{1}{1 + \kappa^2} \exp\left(-\displaystyle\frac{|x - \mu|}{\sigma / \kappa}\right) & x \geq \mu. \end{cases}\end{split}\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the asymmetric Laplace distribution. With \(t = \kappa^2 / (1 + \kappa^2)\),

\[\begin{split}F^{-1}(q ; \mu, \sigma, \kappa) = \begin{cases} \mu + \sigma \kappa \ln(q / t) & q \leq t, \\ \mu - \displaystyle\frac{\sigma}{\kappa} \ln\!\bigl((1 + \kappa^2) (1 - q)\bigr) & q > t. \end{cases}\end{split}\]
Parameters:

q – Quantile(s) in \([0, 1]\).

Returns:

Quantile values \(x\) such that \(F(x) = q\).

AsymmetricLaplaceQuantile

class AsymmetricLaplaceQuantile(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, quantile: Array | ndarray | bool | number | bool | int | float | complex = 0.5, *, validate_args: bool | None = None)[source]

Bases: Distribution

An alternative parameterization of AsymmetricLaplace commonly applied in Bayesian quantile regression.

Instead of the asymmetry parameter employed by AsymmetricLaplace, to define the balance between left- versus right-hand sides of the distribution, this class utilizes a quantile parameter, which describes the proportion of probability density that falls to the left-hand side of the distribution.

The scale parameter is also interpreted slightly differently than in AsymmetricLaplace. When loc=0 and scale=1, AsymmetricLaplace(0,1,1) is equivalent to Laplace(0,1), while AsymmetricLaplaceQuantile(0,1,0.5) is equivalent to Laplace(0,2).

Equivalently, this is an AsymmetricLaplace with asymmetry \(\kappa = \sqrt{q / (1 - q)}\) and scale \(\sigma' = \sigma \kappa / q\), under which loc is exactly the \(q\)-th quantile. The Probability Density Function (PDF) is the standard asymmetric-Laplace form used in Bayesian quantile regression [1]:

\[f(x ; \mu, \sigma, q) = \frac{q (1 - q)}{\sigma} \exp\left(-\frac{\rho_q(x - \mu)}{\sigma}\right), \qquad \rho_q(u) = u \left(q - \mathbb{1}[u < 0]\right),\]

where \(q\) is quantile, so the density decays at rate \((1 - q) / \sigma\) below \(\mu\) and \(q / \sigma\) above it.

References:

  1. Yu, K. and Moyeed, R. A. (2001). Bayesian quantile regression. Statistics & Probability Letters, 54(4), 437-447.

Parameters:
  • loc – Location \(\mu \in \mathbb{R}\); exactly the \(q\)-th quantile of the distribution. Defaults to 0.0.

  • scale – Scale \(\sigma > 0\). Note AsymmetricLaplaceQuantile(0, 1, 0.5) is equivalent to Laplace(0, 2). Defaults to 1.0.

  • quantile – Quantile \(q \in (0, 1)\); the proportion of probability mass below loc. Defaults to 0.5.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'loc': Real(), 'quantile': OpenInterval(lower_bound=0.0, upper_bound=1.0), 'scale': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['loc', 'scale', 'quantile']
support = Real()
pytree_data_fields: tuple[str, ...] = ('loc', 'scale', 'quantile', '_ald')
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x ; \mu, \sigma, q) = -\frac{\rho_q(x - \mu)}{\sigma} + \ln\!\frac{q (1 - q)}{\sigma}, \qquad \rho_q(u) = u \left(q - \mathbb{1}[u < 0]\right)\]
Parameters:
  • value – Real-valued point \(x\) at which to evaluate the log PDF.

  • intermediates – Not used.

Returns:

Log probability density evaluated under the asymmetric Laplace quantile distribution.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples by delegating to the equivalent AsymmetricLaplace representation with asymmetry \(\kappa = \sqrt{q / (1 - q)}\) and scale \(\sigma \kappa / q\).

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the asymmetric Laplace quantile distribution.

property mean: Array

Mean of the asymmetric Laplace quantile distribution, delegated to the equivalent AsymmetricLaplace representation:

\[\mathbb{E}[X] = \mu + \frac{\sigma (1 - 2 q)}{q (1 - q)}\]
property variance: Array

Variance of the asymmetric Laplace quantile distribution, delegated to the equivalent AsymmetricLaplace representation:

\[\mathrm{Var}(X) = \frac{\sigma^2 (1 - 2 q + 2 q^2)}{q^2 (1 - q)^2}\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the asymmetric Laplace quantile distribution, delegated to the equivalent AsymmetricLaplace representation:

\[\begin{split}F(x ; \mu, \sigma, q) = \begin{cases} q \, \exp\left(\displaystyle\frac{(1 - q) (x - \mu)}{\sigma}\right) & x < \mu, \\ 1 - (1 - q) \exp\left(-\displaystyle\frac{q (x - \mu)}{\sigma}\right) & x \geq \mu. \end{cases}\end{split}\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the asymmetric Laplace quantile distribution, delegated to the equivalent AsymmetricLaplace representation:

\[\begin{split}F^{-1}(q ; \mu, \sigma, q_0) = \begin{cases} \mu + \displaystyle\frac{\sigma}{1 - q_0} \ln\!\left(\frac{q}{q_0}\right) & q \leq q_0, \\ \mu - \displaystyle\frac{\sigma}{q_0} \ln\!\left(\frac{1 - q}{1 - q_0}\right) & q > q_0. \end{cases}\end{split}\]

where \(q_0\) is quantile.

Parameters:

q – Quantile(s) in \([0, 1]\).

Returns:

Quantile values \(x\) such that \(F(x) = q\).

Beta

class Beta(concentration1: Array | ndarray | bool | number | bool | int | float | complex, concentration0: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Beta distribution parameterized by concentration parameters alpha (concentration1) and beta (concentration0), on the unit interval \([0,1]\).

The probability density function (PDF) is defined as:

\[f(x; \alpha, \beta) = \frac{x^{\alpha - 1} (1 - x)^{\beta - 1}}{\text{B}(\alpha, \beta)}\]

Where, \(x \in [0, 1]\), \(\alpha > 0\), \(\beta > 0\), and \(\text{B}(\alpha, \beta)\) is the Beta function.

Parameters:
  • concentration1 (ArrayLike) – Alpha parameter (1st shape parameter).

  • concentration0 (ArrayLike) – Beta parameter (2nd shape parameter).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'concentration0': Positive(lower_bound=0.0), 'concentration1': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['concentration1', 'concentration0']
support = UnitInterval(lower_bound=0.0, upper_bound=1.0)
pytree_data_fields: tuple[str, ...] = ('concentration0', 'concentration1', '_dirichlet')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples from the distribution using the underlying Dirichlet implementation.

Since a \(\mathrm{Beta}(\alpha, \beta)\) distribution is equivalent to a 2-category \(\mathrm{Dirichlet}(\alpha, \beta)\), this method samples from the Dirichlet and slices the first component.

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Beta distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

To avoid NaN gradients at the boundaries \(x=0\) or \(x=1\), this implementation masks boundary values with a safe constant (0.5) during the differentiation path. The forward pass value is then corrected using stop_gradient() to ensure numerical stability without sacrificing accuracy.

Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

property mean: Array

Calculates the analytical mean.

\[E[X] = \frac{\alpha}{\alpha + \beta}\]
property variance: Array

Calculates the analytical variance.

\[Var(X) = \frac{\alpha \beta}{(\alpha + \beta)^2 (\alpha + \beta + 1)}\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function using the regularized incomplete beta function.

\[I_x(\alpha, \beta) = \frac{\text{B}(x; \alpha, \beta)}{\text{B}(\alpha, \beta)}\]
Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

entropy() → Array[source]

Entropy of the Beta distribution.

\[H(X) = \ln \text{B}(\alpha, \beta) - (\alpha - 1)\psi(\alpha) - (\beta - 1)\psi(\beta) + (\alpha + \beta - 2)\psi(\alpha + \beta)\]

where \(\psi\) is the digamma function.

BetaProportion

class BetaProportion(mean: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Beta

Beta distribution reparameterized in terms of a mean (mean) and a precision (concentration).

Given mean \(\mu\) and precision \(\phi\), the standard Beta parameters are derived as:

\[\alpha = \mu \phi, \quad \beta = (1 - \mu) \phi\]

The resulting PDF is:

\[f(x; \mu, \phi) = \frac{x^{\mu\phi - 1} (1 - x)^{(1 - \mu)\phi - 1}}{\text{B}(\mu\phi, (1 - \mu)\phi)}\]

Reference

Ferrari, Silvia, and Francisco Cribari-Neto. “Beta regression for modelling rates and proportions.” Journal of Applied Statistics 31.7 (2004): 799-815.

Parameters:
  • mean (ArrayLike) – Mean of the distribution, restricted to the open interval (0, 1).

  • concentration (ArrayLike) – Precision parameter (\(\phi\)), must be positive.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'mean': OpenInterval(lower_bound=0.0, upper_bound=1.0)}
reparametrized_params: list[str] = ['mean', 'concentration']
support = UnitInterval(lower_bound=0.0, upper_bound=1.0)
pytree_data_fields: tuple[str, ...] = ('concentration',)

CAR

class CAR(loc: Array | ndarray | bool | number | bool | int | float | complex, correlation: Array | ndarray | bool | number | bool | int | float | complex, conditional_precision: Array | ndarray | bool | number | bool | int | float | complex, adj_matrix: Array | ndarray | bool | number | bool | int | float | complex | scipy.sparse.spmatrix, *, is_sparse: bool = False, validate_args: bool | None = None)[source]

Bases: Distribution

The Conditional Autoregressive (CAR) distribution is a multivariate normal whose precision matrix is structured by an adjacency matrix. It is commonly used as a prior for areal spatial data.

Let \(W\) be adj_matrix, let \(n_i = \sum_j W_{ij}\), and define \(D = \operatorname{diag}(n_1, \ldots, n_N)\). With \(\rho\) denoting correlation and \(\tau\) denoting conditional_precision, the precision matrix is

\[Q = \tau (D - \rho W).\]

Therefore, for \(x, \mu \in \mathbb{R}^N\), with \(\mu\) denoting loc, the density is

\[p(x) = \frac{|Q|^{1/2}}{(2\pi)^{N/2}} \exp\left(-\frac{1}{2}(x-\mu)^\top Q(x-\mu)\right).\]

If \(W\) has a zero diagonal, the corresponding full conditional is

\[x_i \mid x_{-i} \sim \mathcal{N}\left( \mu_i + \frac{\rho}{n_i}\sum_j W_{ij}(x_j-\mu_j), \frac{1}{\tau n_i}\right).\]

Here \(n_i\) is the weighted row sum; it equals the number of neighbors only for a binary adjacency matrix. Let \(\lambda_{\min}\) and \(\lambda_{\max}\) be the extreme eigenvalues of \(D^{-1/2} W D^{-1/2}\). Then \(Q\) is positive definite exactly when \(\rho\lambda_i < 1\) for every eigenvalue, which for \(\lambda_{\min} < 0 < \lambda_{\max}\) is the interval

\[\frac{1}{\lambda_{\min}} < \rho < \frac{1}{\lambda_{\max}}.\]

For symmetric, nonnegative \(W\) with positive row sums, \(\lambda_{\max}=1\) and \(\lambda_{\min}\geq -1\), with equality exactly when some connected component is bipartite; a zero diagonal also gives \(\lambda_{\min}<0\). Thus \(|\rho| < 1\) is always sufficient, but it can exclude admissible negative values. This class restricts correlation to \((-1, 1)\).

log_prob computes the log determinant without factorizing \(Q\). If \(\lambda_1,\ldots,\lambda_N\) are the eigenvalues above, it uses the identity [2]

\[\log |Q| = N\log\tau + \sum_i\log n_i + \sum_i\log(1-\rho\lambda_i).\]

With a NumPy or SciPy sparse adjacency matrix, log_prob computes the eigenvalues with NumPy on the host; when the distribution is constructed inside a traced function, as in a model, they enter the compiled computation as constants. With a JAX adjacency matrix, the eigendecomposition remains in the traced graph and is recomputed on each evaluation; JAX adjacency inputs are therefore supported but not recommended.

When validation is enabled, symmetry and positive row sums are checked by assertions for NumPy and SciPy sparse inputs. JAX adjacency inputs are not validated. Nonnegative weights and a zero diagonal are the caller’s responsibility. With is_sparse=True, the adjacency matrix is stored in SciPy CSR format and converted to JAX BCOO for the quadratic form in log_prob. The normalized adjacency is nevertheless densified on the host for NumPy eigenvalue computation, and precision_matrix and sampling are dense. Thus, is_sparse=True does not provide fully sparse inference. This mode accepts only two-dimensional NumPy or SciPy sparse adjacency inputs.

Parameters:
  • loc (float or ndarray) – mean of the multivariate normal

  • correlation (float) – autoregression parameter. At zero, sites are independent with variances \(1/(\tau n_i)\), which need not be identical. The value one is the excluded intrinsic-CAR boundary; this class implements the proper CAR distribution and also permits negative correlations.

  • conditional_precision (float) – positive multiplier \(\tau\) of the conditional precision, so that \(\operatorname{Var}(x_i \mid x_{-i}) = 1/(\tau n_i)\) when the adjacency diagonal is zero

  • adj_matrix (ndarray or scipy.sparse.csr_matrix) – symmetric, nonnegative weight matrix \(W\) with zero diagonal and positive row sums, shape (..., N, N) (two-dimensional only when is_sparse=True). The standard CAR uses a binary matrix (one for neighboring sites, zero otherwise). A jax.numpy.ndarray is supported but not recommended (see above).

  • is_sparse (bool) – whether to use a sparse form of adj_matrix in calculations (must be True if adj_matrix is a scipy.sparse.spmatrix)

Example

CAR.log_prob agrees with a multivariate normal constructed from the precision matrix above:

>>> import jax.numpy as jnp
>>> import numpy as np
>>> from numpyro.distributions import CAR, MultivariateNormal
>>> loc = jnp.zeros(3)
>>> adjacency = np.array([[0.0, 1.0, 1.0],
...                       [1.0, 0.0, 1.0],
...                       [1.0, 1.0, 0.0]])
>>> rho, tau = 0.4, 2.0
>>> degree = adjacency.sum(axis=-1)
>>> precision = tau * (jnp.diag(degree) - rho * adjacency)
>>> car = CAR(loc, rho, tau, adjacency)
>>> normal = MultivariateNormal(loc, precision_matrix=precision)
>>> value = jnp.array([0.2, -0.1, 0.3])
>>> bool(jnp.allclose(car.log_prob(value), normal.log_prob(value)))
True

References

[1] Besag, J. (1974). Spatial interaction and the statistical analysis of lattice systems. Journal of the Royal Statistical Society: Series B, 36(2), 192–225. https://doi.org/10.1111/j.2517-6161.1974.tb00999.x

[2] Jin, X., Carlin, B. P., and Banerjee, S. (2005). Generalized hierarchical multivariate CAR models for areal data. Biometrics, 61(4), 950–961. https://doi.org/10.1111/j.1541-0420.2005.00359.x

arg_constraints: dict[str, Any] = {'adj_matrix': Dependent(), 'conditional_precision': Positive(lower_bound=0.0), 'correlation': OpenInterval(lower_bound=-1, upper_bound=1), 'loc': RealVector(Real(), 1)}
support = RealVector(Real(), 1)
reparametrized_params: list[str] = ['loc', 'correlation', 'conditional_precision', 'adj_matrix']
pytree_aux_fields: tuple[str, ...] = ('is_sparse', 'adj_matrix')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

precision_matrix()[source]
classmethod infer_shapes(loc, correlation, conditional_precision, adj_matrix)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

tree_flatten()[source]
classmethod tree_unflatten(aux_data, params)[source]

Cauchy

class Cauchy(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Cauchy distribution parameterized by location (loc) and scale (scale).

The probability density function (PDF) is defined as:

\[f(x; x_0, \gamma) = \frac{1}{\pi \gamma \left[1 + \left(\frac{x - x_0}{\gamma}\right)^2\right]}\]

where \(x \in \mathbb{R}\), \(x_0 \in \mathbb{R}\) is the location, and \(\gamma > 0\) is the scale. The Cauchy distribution has no finite mean or variance.

Parameters:
  • loc (ArrayLike) – Location parameter (\(x_0\)).

  • scale (ArrayLike) – Scale parameter (\(\gamma\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples using the inverse CDF method via cauchy().

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Cauchy distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; x_0, \gamma) = -\log(\pi) - \log(\gamma) - \log\!\left[1 + \left(\frac{x - x_0}{\gamma}\right)^2\right]\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

property mean: Array

The mean of the Cauchy distribution is undefined.

Returns NaN for all batch elements.

property variance: Array

The variance of the Cauchy distribution is undefined.

Returns NaN for all batch elements.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function.

\[F(x; x_0, \gamma) = \frac{1}{\pi}\arctan\!\left(\frac{x - x_0}{\gamma}\right) + \frac{1}{2}\]
Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; x_0, \gamma) = x_0 + \gamma \tan\!\left[\pi\!\left(q - \frac{1}{2}\right)\right]\]
Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

entropy() → Array[source]

Entropy of the Cauchy distribution.

\[H(X) = \log(4\pi\gamma)\]

Chi2

class Chi2(df: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Gamma

A chi-square continuous random variable, parameterized by the degrees of freedom \(k\).

The Probability Density Function (PDF) of the chi-square distribution with \(k\) degrees of freedom is defined as:

\[f(x; k) = \frac{x^{k/2 - 1} e^{-x/2}}{2^{k/2}\,\Gamma(k/2)}, \quad x > 0\]

Where, \(k\) represents the degrees of freedom (df), \(\Gamma(\cdot)\) is the gamma function, and \(x\) is the observed value. The support domain is \(x \in (0, \infty)\).

The chi-square distribution is a special case of the Gamma distribution:

\[\chi^2(k) \equiv \mathrm{Gamma}(k/2,\; 1/2)\]

so this class inherits sampling, log-probability, mean, variance, and entropy implementations from Gamma.

Parameters:
  • df – Degrees of freedom parameter \(k > 0\) (df).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'df': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['df']

CirculantNormal

class CirculantNormal(loc: Array | ndarray | bool | number | bool | int | float | complex, covariance_row: Array | ndarray | bool | number | bool | int | float | complex | None = None, covariance_rfft: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Multivariate normal distribution with covariance matrix \(\mathbf{C}\) that is positive-definite and circulant [1], i.e., has periodic boundary conditions. The density of a sample \(\mathbf{x}\in\mathbb{R}^n\) is the standard multivariate normal density

\[p\left(\mathbf{x}\mid\boldsymbol{\mu},\mathbf{C}\right) = \frac{\left(\mathrm{det}\,\mathbf{C}\right)^{-1/2}}{\left(2\pi\right)^{n / 2}} \exp\left(-\frac{1}{2}\left(\mathbf{x}-\boldsymbol{\mu}\right)^\intercal \mathbf{C}^{-1}\left(\mathbf{x}-\boldsymbol{\mu}\right)\right),\]

where \(\mathrm{det}\) denotes the determinant and \(^\intercal\) the transpose. Circulant matrices can be diagnolized efficiently using the discrete Fourier transform [1], allowing the log likelihood to be evaluated in \(n \log n\) time for \(n\) observations [2].

Concretely, let \(\mathbf{c}\) be the first row of \(\mathbf{C}\) and

\[\lambda_k = \sum_{j=0}^{n-1} c_j e^{-2\pi i jk/n}, \qquad k = 0, \ldots, n-1,\]

its discrete Fourier transform. The \(\lambda_k\) are the eigenvalues of \(\mathbf{C}\); they are real and satisfy \(\lambda_k = \lambda_{n-k}\) because \(\mathbf{C}\) is symmetric, and covariance_rfft holds \(\lambda_0, \ldots, \lambda_{\lfloor n/2 \rfloor}\). With the DFT matrix \(\mathbf{F}\) and \(\mathbf{\Lambda} = \mathrm{diag}(\boldsymbol\lambda)\), \(\mathbf{C} = \tfrac{1}{n}\mathbf{F}^{*}\mathbf{\Lambda}\mathbf{F}\) and, writing \(\hat{\mathbf{z}} = \mathbf{F}(\mathbf{x} - \boldsymbol\mu)\) for the DFT of the centered value, the log density is

\[\log p(\mathbf{x} \mid \boldsymbol\mu, \mathbf{C}) = -\frac{n}{2}\log 2\pi - \frac{1}{2}\sum_{k=0}^{n-1}\log\lambda_k - \frac{1}{2n}\sum_{k=0}^{n-1}\frac{|\hat z_k|^2}{\lambda_k}.\]

\(\mathbf{C}\) is positive definite if and only if \(\lambda_k > 0\) for all \(k\) (positive_definite_circulant_vector checks that rfft(covariance_row) is real — the row is symmetric — and non-negative up to a tolerance of 10 * eps). The moments are \(\mathbb{E}[\mathbf{X}] = \boldsymbol\mu\) and \(\operatorname{Cov}[\mathbf{X}] = \mathbf{C}\) (covariance_matrix) with marginal \(\operatorname{Var}[X_j] = c_0\) (variance), and the entropy is

\[H(\mathbf{X}) = \frac{n}{2}\log(2\pi e) + \frac{1}{2}\sum_{k=0}^{n-1}\log\lambda_k.\]
Parameters:
  • loc – Mean of the distribution \(\boldsymbol{\mu}\).

  • covariance_row – First row of the circulant covariance matrix \(\boldsymbol{C}\). Because of periodic boundary conditions, the covariance matrix is fully determined by its first row (see jax.scipy.linalg.toeplitz() for further details).

  • covariance_rfft – Real part of the real fast Fourier transform of covariance_row, the first row of the circulant covariance matrix \(\boldsymbol{C}\).

Note

This class is a TransformedDistribution whose base is a diagonal normal over the \(n\) packed real FFT coefficients, with variances \(n\lambda_0\) (DC), \(n\lambda_{n/2}\) (Nyquist, even \(n\) only) and \(n\lambda_k/2\) for both the real and imaginary parts of the remaining frequencies, followed by PackRealFastFourierCoefficientsTransform, the inverse RealFastFourierTransform and a shift by loc. Hence sample costs one inverse FFT and log_prob one FFT plus the Jacobian terms. covariance_rfft is taken as the real part of rfft(covariance_row).

References:

  1. Wikipedia. (n.d.). Circulant matrix. Retrieved March 6, 2025, from https://en.wikipedia.org/wiki/Circulant_matrix

  2. Wood, A. T. A., & Chan, G. (1994). Simulation of Stationary Gaussian Processes in \(\left[0, 1\right]^d\). Journal of Computational and Graphical Statistics, 3(4), 409–432. https://doi.org/10.1080/10618600.1994.10474655

arg_constraints: dict[str, Any] = {'covariance_rfft': IndependentConstraint(Positive(lower_bound=0.0), 1), 'covariance_row': PositiveDefiniteCirculantVector(), 'loc': RealVector(Real(), 1)}
support = RealVector(Real(), 1)
property mean: Array

Mean of the distribution.

covariance_row() → Array[source]
covariance_matrix() → Array[source]
variance() → Array[source]

Variance of the distribution.

classmethod infer_shapes(loc: tuple[int, ...] = (), covariance_row: tuple[int, ...] | None = None, covariance_rfft: tuple[int, ...] | None = None)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

entropy() → Array[source]

Returns the entropy of the distribution.

Dagum

class Dagum(concentration: Array | ndarray | bool | number | bool | int | float | complex, sharpness: Array | ndarray | bool | number | bool | int | float | complex, scale: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Dagum distribution (also known as the Mielke Beta-Kappa distribution).

A continuous distribution with support on the positive real line, commonly used to model income and wealth. This implementation follows the notation of the Wikipedia entry, using \(p\) for concentration, \(a\) for sharpness and \(b\) for scale. See https://en.wikipedia.org/wiki/Dagum_distribution.

The Probability Density Function (PDF), in terms of concentration (\(p > 0\)), sharpness (\(a > 0\)) and scale (\(b > 0\)), is

\[f(x ; p, a, b) = \frac{a p}{x} \left(\frac{(x/b)^{a p}}{\left((x/b)^{a} + 1\right)^{p + 1}}\right), \quad x > 0\]

and the corresponding Cumulative Distribution Function (CDF) is

\[F(x ; p, a, b) = \left(1 + \left(\frac{b}{x}\right)^{a}\right)^{-p}\]

where \(p > 0\) is the concentration (concentration), \(a > 0\) is the sharpness (sharpness) and \(b > 0\) is the scale (scale).

References:

  1. Wikipedia. (n.d.). Dagum distribution. Retrieved March 31, 2025, from https://en.wikipedia.org/wiki/Dagum_distribution

Parameters:
  • concentration – Concentration parameter \(p > 0\) (called p in the Wikipedia entry).

  • sharpness – Sharpness parameter \(a > 0\) (called a in the Wikipedia entry).

  • scale – Scale parameter \(b > 0\) (called b in the Wikipedia entry).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'scale': Positive(lower_bound=0.0), 'sharpness': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
reparametrized_params: list[str] = ['concentration', 'sharpness', 'scale']
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

\[\ln f(x ; p, a, b) = \ln a + \ln p - \ln x + a p \ln\left(\frac{x}{b}\right) - (p + 1) \ln\!\left(\left(\frac{x}{b}\right)^{a} + 1\right)\]
Parameters:

value – Positive point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the Dagum distribution.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Dagum distribution:

\[F(x ; p, a, b) = \left(1 + \left(\frac{b}{x}\right)^{a}\right)^{-p}\]
Parameters:

value – Positive point \(x\) at which to evaluate the CDF.

Returns:

Probability that a Dagum random variable is at most value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse Cumulative Distribution Function (quantile function), the inverse of cdf():

\[F^{-1}(q ; p, a, b) = b\,\left(q^{-1/p} - 1\right)^{-1/a}\]
Parameters:

q – Quantile level \(q \in (0, 1)\).

Returns:

The value \(x\) such that \(F(x) = q\).

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples by inverse-transform sampling: draw \(U \sim \mathrm{Uniform}(0, 1)\) and return \(F^{-1}(U)\), where \(F^{-1}\) is icdf().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Positive samples from the Dagum distribution.

property mean: Array

Mean of the Dagum distribution, finite only when \(a > 1\):

\[\mathbb{E}[X] = b\,p\,\mathrm{B}\!\left(1 - \frac{1}{a},\; p + \frac{1}{a}\right), \quad a > 1\]

where \(\mathrm{B}\) is the Beta function; the mean is \(+\infty\) when \(a \le 1\).

property variance: Array

Variance of the Dagum distribution, finite only when \(a > 2\):

\[\mathrm{Var}[X] = b^{2}\,p\,\mathrm{B}\!\left(1 - \frac{2}{a},\; p + \frac{2}{a}\right) - \left(\mathbb{E}[X]\right)^{2}, \quad a > 2\]

where \(\mathrm{B}\) is the Beta function; the variance is \(+\infty\) when \(a \le 2\).

Dirichlet

class Dirichlet(concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Dirichlet distribution parameterized by concentration (concentration).

The probability density function (PDF) is defined as:

\[f(\mathbf{x}; \boldsymbol{\alpha}) = \frac{\Gamma(\alpha_0)}{\prod_{i=1}^{K}\Gamma(\alpha_i)} \prod_{i=1}^{K}x_i^{\alpha_i-1},\]

where \(\alpha_0 = \sum_{i=1}^{K}\alpha_i\), each concentration parameter satisfies \(\alpha_i > 0\), and \(\mathbf{x}\) lies on the probability simplex in \(\mathbb{R}^{K}\):

\[x_i \geq 0, \qquad \sum_{i=1}^{K}x_i = 1.\]
Parameters:
  • concentration (ArrayLike) – Positive concentration parameters. The final dimension determines the event size (\(\alpha\))

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'concentration': IndependentConstraint(Positive(lower_bound=0.0), 1)}
reparametrized_params: list[str] = ['concentration']
support = Simplex()
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples using dirichlet().

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Dirichlet distribution of shape sample_shape + batch_shape + event_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(\mathbf{x}; \boldsymbol{\alpha}) = \log\Gamma(\alpha_0) - \sum_{i=1}^{K}\log\Gamma(\alpha_i) + \sum_{i=1}^{K}(\alpha_i - 1)\log x_i.\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

property mean: Array

Calculates the mean of the Dirichlet distribution per element.

\[\mathbb{E}[X_i] = \frac{\alpha_i}{\alpha_0},\]

where \(\alpha_0 = \sum_{j=1}^K\alpha_j\),

property variance: Array

Calculates the variance of the Dirichlet distribution.

\[\mathrm{Var}(X_i) = \frac{\alpha_i(\alpha_0-\alpha_i)} {\alpha_0^2(\alpha_0+1)},\]

where \(\alpha_0 = \sum_{j=1}^K\alpha_j\)

classmethod infer_shapes(concentration)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

entropy() → Array[source]

Entropy of the Dirichlet distribution.

\[H(X) = \sum_{i=1}^{K} \ln \Gamma(\alpha_i) - \ln \Gamma(\alpha_0) + (\alpha_0-K)\psi(\alpha_0) - \sum_{i=1}^{K}(\alpha_i-1)\psi(\alpha_i),\]

where \(\alpha_0 = \sum_{i=1}^{K}\alpha_i\), \(B(\boldsymbol{\alpha})\) is the multivariate beta function, and \(\psi\) is the digamma function.

EulerMaruyama

class EulerMaruyama(t: Array | ndarray | bool | number | bool | int | float | complex, sde_fn: Callable[[Array, Array], tuple[Array, Array]], init_dist: Distribution, *, validate_args: bool | None = None)[source]

Bases: Distribution

Euler–Maruyama method is a method for the approximate numerical solution of a stochastic differential equation (SDE)

\[dX_t = f(X_t, t)\, dt + g(X_t, t)\, dW_t\]

On a discrete time grid \(t_0 < t_1 < \cdots < t_N\) with step sizes \(\Delta t_k = t_{k+1} - t_k\), the method approximates the solution by

\[X_{k+1} = X_k + \Delta t_k\, f(X_k, t_k) + \sqrt{\Delta t_k}\, g(X_k, t_k)\, \varepsilon_k, \qquad \varepsilon_k \sim \mathcal{N}(0, 1),\]

with \(X_0 \sim\) init_dist. Each transition is therefore Gaussian, and the joint density of the path \(x_0, \ldots, x_N\) factorizes as

\[p(x_0, \ldots, x_N) = p_0(x_0) \prod_{k=0}^{N-1} \mathcal{N}\!\left(x_{k+1};\; x_k + \Delta t_k\, f(x_k, t_k),\; \Delta t_k\, g(x_k, t_k)^2\right),\]

where \(p_0\) is the density of init_dist. The diffusion coefficient \(g\) is the per-coordinate scale of independent Gaussian noise.

Parameters:
  • t (ndarray) – discretized time

  • sde_fn (callable) – function returning the drift and diffusion coefficients of SDE

  • init_dist (Distribution) – Distribution for initial values.

References

[1] https://en.wikipedia.org/wiki/Euler-Maruyama_method

arg_constraints: dict[str, Any] = {'t': OrderedVector()}
pytree_data_fields: tuple[str, ...] = ('t', 'init_dist')
pytree_aux_fields: tuple[str, ...] = ('sde_fn',)
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

Exponential

class Exponential(rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Exponential distribution parameterized by rate (rate).

The probability density function (PDF) is defined as:

\[f(x; \lambda) = \lambda e^{-\lambda x}\]

where \(x \geq 0\) and \(\lambda > 0\) is the rate parameter.

Parameters:
  • rate (ArrayLike) – Rate parameter (\(\lambda\)), the inverse of the mean.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

reparametrized_params: list[str] = ['rate']
arg_constraints: dict[str, Any] = {'rate': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples by scaling standard exponential draws by the inverse rate: \(X = E / \lambda\), where \(E \sim \mathrm{Exp}(1)\).

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Exponential distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; \lambda) = \log \lambda - \lambda x\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

property mean: Array

Calculates the analytical mean.

\[E[X] = \frac{1}{\lambda}\]
property variance: Array

Calculates the analytical variance.

\[\mathrm{Var}(X) = \frac{1}{\lambda^2}\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function.

\[F(x; \lambda) = 1 - e^{-\lambda x}\]
Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; \lambda) = -\frac{\ln(1 - q)}{\lambda}\]
Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

entropy() → Array[source]

Entropy of the Exponential distribution.

\[H(X) = 1 - \ln \lambda\]

Gamma

class Gamma(concentration: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Implementation of the Gamma distribution, \(\mathrm{Gamma}(\alpha, \lambda)\), where, \(\alpha\) is the concentration and \(\lambda\) is the rate.

Parameters:
  • concentration (ArrayLike) – concentration parameter \(\alpha\) (also known as shape parameter).

  • rate (ArrayLike) – rate parameter \(\lambda\) (inverse scale parameter).

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'rate': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
reparametrized_params: list[str] = ['concentration', 'rate']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Method to generate samples \(X \sim \mathrm{Gamma}(\alpha, \lambda)\). It uses gamma() under the hood to generate samples.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[f_X(x\mid \alpha, \lambda) = \frac{\lambda^{\alpha} x^{\alpha - 1} e^{-\lambda x}}{\Gamma(\alpha)}, \quad x > 0\]

It uses gammaln() to compute the logarithm of the gamma function.

property mean: Array

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[\mathbb{E}[X] = \frac{\alpha}{\lambda}\]
property variance: Array

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[\mathrm{Var}(X) = \frac{\alpha}{\lambda^2}\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[F_X(x \mid \alpha, \lambda) = \frac{1}{\Gamma(\alpha)} \gamma\left(\alpha, \lambda x\right)\]

where, \(\gamma(\cdot,\cdot)\) is the lower incomplete gamma function. This method uses regularized incomplete gamma function, which is implemented as gammainc().

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[F^{-1}_X(q \mid \alpha, \lambda) = \frac{1}{\lambda} \gamma^{-1}\left(\alpha, q \Gamma(\alpha)\right)\]

where, \(\gamma^{-1}(\cdot,\cdot)\) is the inverse of the lower incomplete gamma function. This method uses regularized incomplete gamma inverse function, which is implemented as gammaincinv().

entropy() → Array[source]

If \(X \sim \mathrm{Gamma}(\alpha, \lambda)\), then

\[H[X] = \alpha - \ln(\lambda) + \ln\Gamma(\alpha) + (1 - \alpha) \psi(\alpha)\]

where, \(\psi(\cdot)\) is the digamma function. This methods uses which is implemented as digamma().

GaussianCopula

class GaussianCopula(marginal_dist: Distribution, correlation_matrix: Array | ndarray | bool | number | bool | int | float | complex | None = None, correlation_cholesky: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Couple continuous univariate marginals with a Gaussian copula.

Let \(F_i\) and \(f_i\) denote the CDF and density of the \(i\)-th marginal, and let \(\Phi\) be the standard normal CDF. For a positive definite correlation matrix \(R\), samples are constructed as

\[Z \sim \mathcal{N}(0, R), \qquad X_i = F_i^{-1}(\Phi(Z_i)).\]

For interior points with \(0 < F_i(x_i) < 1\), write \(z_i = \Phi^{-1}(F_i(x_i))\). The joint density is

\[p(x) = \frac{\exp\left[-\frac{1}{2}z^\top(R^{-1}-I)z\right]} {\sqrt{\det R}} \prod_{i=1}^D f_i(x_i),\]

or equivalently

\[\log p(x) = -\frac{1}{2}\log\det R -\frac{1}{2}z^\top(R^{-1}-I)z + \sum_{i=1}^D \log f_i(x_i).\]

The support is the Cartesian product of the marginal supports. Each coordinate retains its marginal mean and variance, when these moments exist. In particular, \(R=I\) gives independent marginals. The matrix \(R\) describes correlation in the latent normal variables; it generally differs from the Pearson correlation of \(X\) after the nonlinear marginal transformations.

When present, the final batch axis of marginal_dist supplies the event coordinates and must broadcast to \(D\), the dimension of the correlation matrix. The remaining batch axes broadcast with those of the correlation parameters. Scalar marginals are shared across all \(D\) event coordinates. The marginal distribution must implement cdf and icdf as well as log_prob.

Note

log_prob clamps marginal CDF values away from zero and one before taking normal quantiles, so the formula above describes the mathematical density rather than exact numerical behavior at boundaries or in extreme tails.

References

[1] An Introduction to Copulas, second edition, Roger B. Nelsen (2006) https://doi.org/10.1007/0-387-28678-0

Parameters:
  • marginal_dist (Distribution) – Continuous univariate distribution whose final batch axis is to be coupled.

  • correlation_matrix (array_like) – Latent normal correlation matrix \(R\). Specify exactly one of this or correlation_cholesky.

  • correlation_cholesky (array_like) – Lower triangular correlation Cholesky factor \(L\), where \(R = LL^\top\).

arg_constraints: dict[str, Any] = {'correlation_cholesky': CorrCholesky(), 'correlation_matrix': CorrMatrix()}
reparametrized_params: list[str] = ['correlation_matrix', 'correlation_cholesky']
pytree_data_fields: tuple[str, ...] = ('marginal_dist', 'base_dist')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

correlation_matrix() → Array[source]
correlation_cholesky() → Array[source]

GaussianCopulaBeta

class GaussianCopulaBeta(concentration1: Array | ndarray | bool | number | bool | int | float | complex, concentration0: Array | ndarray | bool | number | bool | int | float | complex, correlation_matrix: Array | ndarray | bool | number | bool | int | float | complex | None = None, correlation_cholesky: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool = False)[source]

Bases: GaussianCopula

Gaussian copula with beta marginals on \([0,1]^D\).

Write \(\alpha_i = \text{concentration1}_i > 0\) and \(\beta_i = \text{concentration0}_i > 0\). Each marginal has density

\[f_i(x_i) = \frac{x_i^{\alpha_i-1}(1-x_i)^{\beta_i-1}} {B(\alpha_i,\beta_i)}, \qquad 0 < x_i < 1,\]

where \(B\) is the beta function. Substituting these densities and their CDFs into GaussianCopula gives the joint density and sampling construction. The coordinate-wise moments are

\[\mathbb{E}[X_i] = \frac{\alpha_i}{\alpha_i+\beta_i}, \qquad \operatorname{Var}(X_i) = \frac{\alpha_i\beta_i} {(\alpha_i+\beta_i)^2(\alpha_i+\beta_i+1)}.\]

The correlation parameters describe the latent normal variables, rather than the Pearson correlation of the beta variables. Batch-shape broadcasting and the CDF clamping in log_prob are inherited from GaussianCopula.

References

[1] SciPy beta distribution reference https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.beta.html

Parameters:
  • concentration1 (array_like) – Positive first beta shape parameter \(\alpha\).

  • concentration0 (array_like) – Positive second beta shape parameter \(\beta\).

  • correlation_matrix (array_like) – Latent normal correlation matrix \(R\). Specify exactly one of this or correlation_cholesky.

  • correlation_cholesky (array_like) – Lower triangular correlation Cholesky factor \(L\), where \(R = LL^\top\).

arg_constraints: dict[str, Any] = {'concentration0': Positive(lower_bound=0.0), 'concentration1': Positive(lower_bound=0.0), 'correlation_cholesky': CorrCholesky(), 'correlation_matrix': CorrMatrix()}
support = IndependentConstraint(UnitInterval(lower_bound=0.0, upper_bound=1.0), 1)
pytree_data_fields: tuple[str, ...] = ('concentration1', 'concentration0')

GaussianRandomWalk

class GaussianRandomWalk(scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, num_steps: int = 1, *, validate_args: bool | None = None)[source]

Bases: Distribution

Gaussian random walk distribution parameterized by scale (scale) and the number of steps (num_steps).

A Gaussian random walk \(\mathbf{X} = (X_0, \ldots, X_{n-1})\) of length \(n\) (given by num_steps) starts at \(X_0\) and evolves through independent Normal increments:

\[X_0 \sim \mathcal{N}(0, \sigma^2), \qquad X_t - X_{t-1} \sim \mathcal{N}(0, \sigma^2), \quad t = 1, \ldots, n - 1,\]

where \(\sigma > 0\) is the scale. The joint probability density function over \(\mathbb{R}^n\) is

\[p(\mathbf{x}) = f(x_0; 0, \sigma) \prod_{t=1}^{n-1} f(x_t - x_{t-1}; 0, \sigma),\]

where \(f(\cdot; \mu, \sigma)\) denotes the univariate Normal density with mean \(\mu\) and standard deviation \(\sigma\).

Parameters:
  • scale (ArrayLike) – Scale parameter (\(\sigma\)), the standard deviation of the initial position and of each increment.

  • num_steps (int) – Number of steps (\(n\)), i.e. the length of the event vector.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'scale': Positive(lower_bound=0.0)}
support = RealVector(Real(), 1)
reparametrized_params: list[str] = ['scale']
pytree_aux_fields: tuple[str, ...] = ('num_steps',)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples as the cumulative sum of standard Normal draws.

\[X_t = \sigma \sum_{s=0}^{t} \epsilon_s, \qquad \epsilon_s \sim \mathcal{N}(0, 1).\]
Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Gaussian random walk of shape sample_shape + batch_shape + event_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the joint probability density function.

\[\log p(\mathbf{x}) = \log f(x_0; 0, \sigma) + \sum_{t=1}^{n-1} \log f(x_t - x_{t-1}; 0, \sigma),\]

where \(f(\cdot; \mu, \sigma)\) is the univariate Normal density.

Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

property mean: Array

Calculates the analytical mean of the Gaussian random walk.

\[\mathbb{E}[X_t] = 0, \qquad t = 0, \ldots, n - 1.\]
property variance: Array

Calculates the analytical variance of the Gaussian random walk.

The variance grows linearly with the step index:

\[\mathrm{Var}(X_t) = (t + 1) \sigma^2, \qquad t = 0, \ldots, n - 1.\]

GaussianStateSpace

class GaussianStateSpace(num_steps: int, transition_matrix: ndarray | Array, covariance_matrix: Array | None = None, precision_matrix: Array | None = None, scale_tril: Array | None = None, initial_value: ndarray | Array | None = None, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Joint distribution of a linear Gaussian state sequence.

For a fixed initial state \(\mathbf{z}_0 \in \mathbb{R}^d\), a transition matrix \(\mathbf{A} \in \mathbb{R}^{d \times d}\), and independent innovations with covariance \(\mathbf{Q}\), the states evolve according to

\[\mathbf{z}_t = \mathbf{A}\mathbf{z}_{t-1} + \boldsymbol{\epsilon}_t, \qquad \boldsymbol{\epsilon}_t \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}), \qquad t = 1, \ldots, T.\]

A sample contains \((\mathbf{z}_1, \ldots, \mathbf{z}_T)\) and has event shape (num_steps, d). The deterministic initial state is not included in the sample. The support is \(\mathbb{R}^{T \times d}\), and the joint density is

\[p(\mathbf{z}_{1:T} \mid \mathbf{z}_0) = \prod_{t=1}^{T} \mathcal{N} (\mathbf{z}_t; \mathbf{A}\mathbf{z}_{t-1}, \mathbf{Q}).\]

Sampling applies RecursiveLinearTransform to independent multivariate Normal innovations. log_prob recovers those innovations as \(\mathbf{z}_t - \mathbf{A}\mathbf{z}_{t-1}\) and sums their log densities over time. The transformation has unit Jacobian determinant. This distribution describes the states themselves; it does not include an observation model or marginalize latent states.

The marginal mean and covariance at step \(t\) are

\[\begin{split}\mathbb{E}[\mathbf{z}_t] &= \mathbf{A}^t\mathbf{z}_0, \\ \mathbf{P}_t &= \mathbf{A}\mathbf{P}_{t-1}\mathbf{A}^{\mathsf{T}} + \mathbf{Q}, \qquad \mathbf{P}_0 = \mathbf{0}.\end{split}\]

variance returns the diagonal of each \(\mathbf{P}_t\), with shape batch_shape + (num_steps, d). In contrast, covariance_matrix, precision_matrix, and scale_tril describe the innovation noise, not the covariance of the state sequence. With \(\mathbf{A}=\mathbf{I}\), this is a multivariate Gaussian random walk.

Specify exactly one of covariance_matrix, precision_matrix, or scale_tril. These matrices may have leading batch dimensions, but the transition matrix must be two-dimensional and is shared across the batch.

Parameters:
  • num_steps – Positive number of sampled steps \(T\).

  • transition_matrix – Square transition matrix \(\mathbf{A}\) of shape (d, d), shared across time.

  • covariance_matrix – Positive-definite innovation covariance \(\mathbf{Q}\), of shape (..., d, d), shared across time.

  • precision_matrix – Inverse innovation covariance \(\mathbf{Q}^{-1}\), of shape (..., d, d).

  • scale_tril – Lower-triangular Cholesky factor \(\mathbf{L}\) such that \(\mathbf{Q}=\mathbf{L}\mathbf{L}^{\mathsf{T}}\), of shape (..., d, d).

  • initial_value – Deterministic initial state \(\mathbf{z}_0\), of shape (..., d). Defaults to zero when None.

  • validate_args – Whether to validate input constraints, defaults to None.

Example:

Two independent position/velocity trajectories with different initial positions share the same transition and innovation covariance:

>>> from jax import random
>>> import jax.numpy as jnp
>>> from numpyro import distributions as dist
>>> process = dist.GaussianStateSpace(
...     num_steps=3,
...     transition_matrix=jnp.array([[1., 1.], [0., 1.]]),
...     scale_tril=0.1 * jnp.eye(2),
...     initial_value=jnp.array([[0., 1.], [10., 1.]]),
... )
>>> process.batch_shape, process.event_shape
((2,), (3, 2))
>>> process.mean[0].tolist()
[[1.0, 1.0], [2.0, 1.0], [3.0, 1.0]]
>>> paths = process.sample(random.key(0), sample_shape=(4,))
>>> paths.shape
(4, 2, 3, 2)
>>> process.log_prob(paths).shape
(4, 2)
arg_constraints: dict[str, Any] = {'covariance_matrix': PositiveDefinite(), 'initial_value': RealVector(Real(), 1), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky(), 'transition_matrix': RealMatrix(Real(), 2)}
support = RealMatrix(Real(), 2)
pytree_data_fields: tuple[str, ...] = ('transition_matrix', '_initial_value', 'scale_tril')
pytree_aux_fields: tuple[str, ...] = ('num_steps',)
property initial_value: Array
property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

covariance_matrix()[source]
precision_matrix()[source]

Gompertz

class Gompertz(concentration: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Gompertz Distribution.

The Gompertz distribution is a distribution with support on the positive real line that is closely related to the Gumbel distribution. This implementation follows the notation used in the Wikipedia entry for the Gompertz distribution. See https://en.wikipedia.org/wiki/Gompertz_distribution.

However, we call the parameter “eta” a concentration parameter and the parameter “b” a rate parameter (as opposed to scale parameter as in wikipedia description.)

The Probability Density Function (PDF), in terms of concentration (\(\eta > 0\)) and rate (\(b > 0\)), is

\[f(x ; \eta, b) = b\,\eta\,\exp\!\left(\eta + b x - \eta e^{b x}\right), \quad x > 0\]

and the corresponding Cumulative Distribution Function (CDF) is

\[F(x ; \eta, b) = 1 - \exp\!\left\{ -\eta \left[ e^{b x} - 1 \right] \right\}\]

where \(\eta > 0\) is the concentration (concentration) and \(b > 0\) is the rate (rate).

Parameters:
  • concentration – Concentration parameter \(\eta > 0\) (called eta in the Wikipedia entry). Broadcasts against rate.

  • rate – Rate parameter \(b > 0\) (called b in the Wikipedia entry). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'rate': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
reparametrized_params: list[str] = ['concentration', 'rate']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples by inverse-transform sampling: draw \(U \sim \mathrm{Uniform}(0, 1)\) and return \(F^{-1}(U)\), where \(F^{-1}\) is icdf().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Positive samples from the Gompertz distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

\[\ln f(x ; \eta, b) = \ln \eta + \ln b + b x - \eta \left( e^{b x} - 1 \right)\]
Parameters:

value – Positive point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the Gompertz distribution.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Gompertz distribution:

\[F(x ; \eta, b) = 1 - \exp\!\left\{ -\eta \left( e^{b x} - 1 \right) \right\}\]
Parameters:

value – Positive point \(x\) at which to evaluate the CDF.

Returns:

Probability that a Gompertz random variable is at most value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse Cumulative Distribution Function (quantile function), the inverse of cdf():

\[F^{-1}(q ; \eta, b) = \frac{1}{b} \ln\!\left( 1 - \frac{\ln(1 - q)}{\eta} \right)\]
Parameters:

q – Quantile level \(q \in [0, 1)\).

Returns:

The value \(x\) such that \(F(x) = q\).

property mean: Array

Mean of the Gompertz distribution:

\[\mathbb{E}[X] = -\frac{1}{b}\, e^{\eta}\, \mathrm{Ei}(-\eta)\]

where \(\mathrm{Ei}\) is the exponential integral, evaluated with expi().

Gumbel

class Gumbel(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

The Gumbel (maximum) distribution, a continuous real-valued distribution parameterized by location \(\mu\) and scale \(\beta > 0\). It is the limiting distribution of the maximum of a large number of i.i.d. samples from an exponential-tailed distribution.

The Probability Density Function (PDF) is:

\[f(x \mid \mu, \beta) = \frac{1}{\beta} \exp\!\left( -\frac{x - \mu}{\beta} - \exp\!\left(-\frac{x - \mu}{\beta}\right) \right), \quad x \in \mathbb{R}\]

where \(\mu \in \mathbb{R}\) is the location (loc) and \(\beta > 0\) is the scale (scale).

Parameters:
  • loc – Location parameter \(\mu \in \mathbb{R}\). Defaults to 0.0.

  • scale – Scale parameter \(\beta > 0\). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Gumbel distribution via the location-scale transform \(X = \mu + \beta Z\), where \(Z \sim \mathrm{Gumbel}(0, 1)\) is drawn from gumbel().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the Gumbel distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

Letting \(z = (x - \mu)/\beta\),

\[\ln f(x \mid \mu, \beta) = -z - e^{-z} - \ln \beta\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the Gumbel distribution.

property mean: Array

Mean of the Gumbel distribution:

\[\mathbb{E}[X] = \mu + \beta \gamma\]

where \(\gamma \approx 0.5772\ldots\) is the Euler-Mascheroni constant, available at, euler_gamma.

property variance: Array

Variance of the Gumbel distribution:

\[\mathrm{Var}(X) = \frac{\pi^2}{6} \beta^2\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Gumbel distribution:

\[F(x \mid \mu, \beta) = \exp\!\left(-\exp\!\left(-\frac{x - \mu}{\beta}\right)\right)\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the Gumbel distribution:

\[F^{-1}(q \mid \mu, \beta) = \mu - \beta \ln(-\ln q), \quad q \in (0, 1)\]
Parameters:

q – Quantile values in \((0, 1)\).

Returns:

Real-valued quantiles of the Gumbel distribution at q.

HalfCauchy

class HalfCauchy(scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Half-Cauchy distribution parameterized by scale (scale).

This is a Cauchy distribution folded at zero, with support on \([0, \infty)\). Sampling draws a Cauchy random variable and takes the absolute value. The log density adds \(\log 2\) to the underlying Cauchy log density so the folded mass is accounted for.

The probability density function (PDF) is defined as:

\[f(x; \sigma) = \frac{2}{\pi \sigma \left[1 + \left(\frac{x}{\sigma}\right)^2\right]}, \qquad x \ge 0\]

where \(\sigma > 0\) is the scale. The mean and variance are undefined (this implementation returns infinity).

Parameters:
  • scale (ArrayLike) – Scale parameter (\(\sigma\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

reparametrized_params: list[str] = ['scale']
support = Positive(lower_bound=0.0)
arg_constraints: dict[str, Any] = {'scale': Positive(lower_bound=0.0)}
pytree_data_fields: tuple[str, ...] = ('_cauchy', 'scale')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples by folding a Cauchy draw: \(X = |Y|\) where \(Y \sim \mathrm{Cauchy}(0, \sigma)\).

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; \sigma) = \log f_{\mathrm{Cauchy}}(x; 0, \sigma) + \log 2\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function.

\[F(x; \sigma) = 2 F_{\mathrm{Cauchy}}(x; 0, \sigma) - 1\]
Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; \sigma) = F_{\mathrm{Cauchy}}^{-1}\!\left(\frac{q+1}{2}; 0, \sigma\right)\]
Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

property mean: Array

The mean of the Half-Cauchy distribution is undefined.

Returns infinity for all batch elements.

property variance: Array

The variance of the Half-Cauchy distribution is undefined.

Returns infinity for all batch elements.

HalfNormal

class HalfNormal(scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Half-Normal distribution parameterized by scale (scale).

This is a Normal distribution folded at zero, with support on \([0, \infty)\). Sampling draws a Normal random variable and takes the absolute value. The log density adds \(\log 2\) to the underlying Normal log density so the folded mass is accounted for.

The probability density function (PDF) is defined as:

\[f(x; \sigma) = \frac{\sqrt{2}}{\sigma \sqrt{\pi}} \exp\!\left( -\frac{x^2}{2\sigma^2} \right), \qquad x \ge 0\]

where \(\sigma > 0\) is the scale (standard deviation of the unfolded Normal).

Parameters:
  • scale (ArrayLike) – Scale parameter (\(\sigma\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

reparametrized_params: list[str] = ['scale']
support = Positive(lower_bound=0.0)
arg_constraints: dict[str, Any] = {'scale': Positive(lower_bound=0.0)}
pytree_data_fields: tuple[str, ...] = ('_normal', 'scale')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples by folding a Normal draw: \(X = |Y|\) where \(Y \sim \mathcal{N}(0, \sigma^2)\).

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; \sigma) = \log f_{\mathcal{N}}(x; 0, \sigma) + \log 2\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function.

\[F(x; \sigma) = 2 \Phi\!\left(\frac{x}{\sigma}\right) - 1\]

where \(\Phi\) is the standard Normal CDF. Implemented via cdf().

Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; \sigma) = \sigma\,\Phi^{-1}\!\left(\frac{q+1}{2}\right)\]
Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

property mean: Array

Calculates the analytical mean.

\[E[X] = \sigma \sqrt{2 / \pi}\]
property variance: Array

Calculates the analytical variance.

\[\mathrm{Var}(X) = \sigma^2 \left(1 - 2/\pi\right)\]

HurdleGamma

class HurdleGamma(gate: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: HurdleProbs

A hurdle Gamma distribution: a two-part model in which a structural zero occurs with probability \(g\) and, conditional on a positive outcome, the magnitude is drawn from \(\mathrm{Gamma}(\alpha, \lambda)\). The hurdle and the magnitude (given a positive value) are conditionally independent; see HurdleProbs for the full mechanism and assumptions.

Because \(P(X = 0) = 0\) under a Gamma density, no truncation factor is needed and the PDF is

\[P(X = 0) = g, \qquad f(x) = (1 - g) \, \frac{\lambda^{\alpha} x^{\alpha - 1} e^{-\lambda x}}{\Gamma(\alpha)} \;\text{for } x > 0.\]
Parameters:
  • gate (ArrayLike) – probability of a structural zero, \(g \in [0, 1]\).

  • concentration (ArrayLike) – shape parameter \(\alpha > 0\) of the Gamma.

  • rate (ArrayLike) – rate parameter \(\lambda > 0\) of the Gamma.

References:

  1. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent Variables with Application to the Demand for Durable Goods. Econometrica, 39(5), 829-844.

  2. Mullahy, J. (1986). Specification and testing of some modified count data models. Journal of Econometrics, 33(3), 341-365.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'rate': Positive(lower_bound=0.0)}
support = Nonnegative(lower_bound=0.0)
pytree_data_fields: tuple[str, ...] = ('concentration', 'rate')

HurdleLogNormal

class HurdleLogNormal(gate: Array | ndarray | bool | number | bool | int | float | complex, loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: HurdleProbs

A hurdle Log-Normal distribution: a two-part model in which a structural zero occurs with probability \(g\) and, conditional on a positive outcome, the magnitude is drawn from \(\mathrm{LogNormal}(\mu, \sigma)\). The hurdle and the magnitude (given a positive value) are conditionally independent; see HurdleProbs for the full mechanism and assumptions.

Because \(P(X = 0) = 0\) under a Log-Normal density, no truncation factor is needed and the PDF is

\[P(X = 0) = g, \qquad f(x) = (1 - g) \, \frac{1}{x \sigma \sqrt{2 \pi}} \exp\!\left( -\frac{(\ln x - \mu)^2}{2 \sigma^2} \right) \;\text{for } x > 0.\]
Parameters:
  • gate (ArrayLike) – probability of a structural zero, \(g \in [0, 1]\).

  • loc (ArrayLike) – location parameter \(\mu \in \mathbb{R}\) (mean of \(\ln X\) given \(X > 0\)).

  • scale (ArrayLike) – scale parameter \(\sigma > 0\) (std-dev of \(\ln X\) given \(X > 0\)).

References:

  1. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent Variables with Application to the Demand for Durable Goods. Econometrica, 39(5), 829-844.

  2. Mullahy, J. (1986). Specification and testing of some modified count data models. Journal of Econometrics, 33(3), 341-365.

arg_constraints: dict[str, Any] = {'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Nonnegative(lower_bound=0.0)
pytree_data_fields: tuple[str, ...] = ('loc', 'scale')

InverseGamma

class InverseGamma(concentration: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

The Inverse-Gamma distribution, a continuous distribution on the positive reals parameterized by concentration \(\alpha > 0\) and a positive parameter called rate in this library. It is the distribution of \(1/Y\) where \(Y \sim \mathrm{Gamma}(\alpha, \beta)\) with the same concentration and rate \(\beta\), and is implemented as a TransformedDistribution of that Gamma under a PowerTransform with exponent -1.

Note

We keep the same notation rate as in Pyro, but it plays the role of the scale parameter of the Inverse-Gamma in the literature (e.g. Wikipedia: https://en.wikipedia.org/wiki/Inverse-gamma_distribution). In the formulas below, \(\beta\) denotes this NumPyro rate parameter (Wikipedia scale), not a rate in the Wikipedia sense.

The Probability Density Function (PDF) is:

\[f(x \mid \alpha, \beta) = \frac{\beta^{\alpha}}{\Gamma(\alpha)} x^{-\alpha-1} \exp\!\left(-\frac{\beta}{x}\right), \quad x > 0\]

where \(\alpha > 0\) is the concentration (concentration) and \(\beta > 0\) is the NumPyro rate parameter (rate), which corresponds to Wikipedia’s scale.

Parameters:
  • concentration – Concentration (shape) \(\alpha > 0\).

  • rate – NumPyro rate parameter \(\beta > 0\), which plays the role of Wikipedia’s scale (see class note). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'rate': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['concentration', 'rate']
support = Positive(lower_bound=0.0)
property mean: Array

Mean of the Inverse-Gamma distribution:

\[\mathbb{E}[X] = \frac{\beta}{\alpha - 1} \quad (\alpha > 1)\]

For \(\alpha \le 1\) the mean is infinite (returned as inf).

property variance: Array

Variance of the Inverse-Gamma distribution:

\[\mathrm{Var}(X) = \frac{\beta^{2}}{(\alpha - 1)^{2} (\alpha - 2)} \quad (\alpha > 2)\]

For \(\alpha \le 2\) the variance is infinite (returned as inf).

entropy() → Array[source]

Differential entropy of the Inverse-Gamma distribution:

\[H(X) = \alpha + \ln\beta + \ln\Gamma(\alpha) - (1 + \alpha)\,\psi(\alpha)\]

where \(\psi\) is the digamma function.

InverseWishart

class InverseWishart(concentration: Array | ndarray | bool | number | bool | int | float | complex, scale_matrix: Array | None = None, rate_matrix: Array | None = None, scale_tril: Array | None = None, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Inverse Wishart distribution for covariance matrices.

The Inverse Wishart distribution is the conjugate prior for the covariance matrix of a multivariate normal distribution. If \(\mathbf{X} \sim W^{-1}(\mathbf{\Psi}, \nu)\), then \(\mathbf{X}^{-1} \sim W(\mathbf{\Psi}^{-1}, \nu)\) (Wishart distribution).

\[p(\mathbf{X} \mid \mathbf{\Psi}, \nu) = \frac{|\mathbf{\Psi}|^{\nu/2}}{2^{\nu p/2} \Gamma_p(\nu/2)} |\mathbf{X}|^{-(\nu + p + 1)/2} \exp\left( -\frac{1}{2} \mathrm{tr}(\mathbf{\Psi} \mathbf{X}^{-1}) \right)\]

where \(p\) is the dimension of the matrix, \(\nu > p - 1\) is the degrees of freedom, and \(\mathbf{\Psi}\) is the positive definite scale matrix.

The scale may be given as \(\mathbf{\Psi}\) (scale_matrix), as its inverse \(\mathbf{\Psi}^{-1}\) (rate_matrix), or as a lower-triangular factor \(\mathbf{T}\) with \(\mathbf{\Psi} = \mathbf{T}\mathbf{T}^\top\) (scale_tril); exactly one of the three must be provided.

The mean, mode and elementwise variance are

\[\mathbb{E}[\mathbf{X}] = \frac{\mathbf{\Psi}}{\nu - p - 1} \quad (\nu > p + 1), \qquad \operatorname{mode}[\mathbf{X}] = \frac{\mathbf{\Psi}}{\nu + p + 1},\]
\[\operatorname{Var}[X_{ij}] = \frac{(\nu - p + 1)\Psi_{ij}^2 + (\nu - p - 1)\Psi_{ii}\Psi_{jj}} {(\nu - p)(\nu - p - 1)^2(\nu - p - 3)} \quad (\nu > p + 3).\]

This class is a TransformedDistribution over InverseWishartCholesky with the inverse CholeskyTransform. sample returns \(\mathbf{X} = \mathbf{L}\mathbf{L}^\top\) with \(\mathbf{L} \sim\) InverseWishartCholesky, itself generated by a Bartlett decomposition so that \(\mathbf{X}^{-1} \sim W(\mathbf{\Psi}^{-1}, \nu)\). log_prob is evaluated through the Cholesky factor,

\[\log p(\mathbf{X}) = \log p_{\mathbf{L}}(\operatorname{chol}\mathbf{X}) - \log\left|\det J\right|,\]

where \(J\) is the Jacobian of \(\mathbf{L} \mapsto \mathbf{L}\mathbf{L}^\top\) and the trace term is computed as \(\mathrm{tr}(\Psi\mathbf{X}^{-1}) = \|\mathbf{L}^{-1}\mathbf{T}\|_F^2\).

Parameters:
  • concentration – Degrees of freedom parameter (often denoted \(\nu\)). Must be greater than p - 1 where p is the dimension of the scale matrix.

  • scale_matrix – Positive definite scale matrix \(\mathbf{\Psi}\), analogous to the inverse rate of a Gamma distribution.

  • rate_matrix – Inverse of the scale matrix, analogous to the rate of a Gamma distribution.

  • scale_tril – Cholesky decomposition of the scale matrix.

Note

mean returns nan where \(\nu \le p + 1\) and variance returns nan where \(\nu \le p + 3\); mode is always defined. concentration must satisfy \(\nu > p - 1\) for the density to be normalizable; this is not validated (the constraint is dependent) and invalid values yield nan or -inf log densities.

References

[1] https://en.wikipedia.org/wiki/Inverse-Wishart_distribution

arg_constraints: dict[str, Any] = {'concentration': Dependent(), 'rate_matrix': PositiveDefinite(), 'scale_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
support = PositiveDefinite()
reparametrized_params: list[str] = ['scale_matrix', 'rate_matrix', 'scale_tril']
base_dist: InverseWishartCholesky
concentration()[source]
scale_matrix()[source]
rate_matrix()[source]
scale_tril()[source]
mean() → Array[source]

Mean of the distribution.

mode() → Array[source]

Mode of the distribution.

variance() → Array[source]

Variance of the distribution.

classmethod infer_shapes(concentration=(), scale_matrix=None, rate_matrix=None, scale_tril=None)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

InverseWishartCholesky

class InverseWishartCholesky(concentration: Array | ndarray | bool | number | bool | int | float | complex, scale_matrix: Array | None = None, rate_matrix: Array | None = None, scale_tril: Array | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Cholesky factor of an Inverse Wishart distribution for covariance matrices.

This distribution samples the Cholesky factor \(\mathbf{L}\) such that \(\mathbf{X} = \mathbf{L} \mathbf{L}^T \sim W^{-1}(\mathbf{\Psi}, \nu)\). Here \(\mathbf{L}\) is lower triangular with positive diagonal, and its density is taken with respect to Lebesgue measure on its \(p(p+1)/2\) free entries. By the change of variables \(\mathbf{X} = \mathbf{L} \mathbf{L}^T\), with Jacobian \(|\partial \mathbf{X} / \partial \mathbf{L}| = 2^p \prod_{i=1}^p L_{ii}^{p - i + 1}\), and \(|\mathbf{X}| = \prod_{i=1}^p L_{ii}^2\), its density is

\[p(\mathbf{L} \mid \mathbf{\Psi}, \nu) = \frac{|\mathbf{\Psi}|^{\nu/2}}{2^{\nu p/2} \Gamma_p(\nu/2)} \exp\left(-\frac{1}{2} \mathrm{tr}(\mathbf{\Psi} \mathbf{L}^{-T} \mathbf{L}^{-1})\right) \, 2^p \prod_{i=1}^p L_{ii}^{-(\nu + i)},\]

where \(\nu > p - 1\) is the concentration (degrees of freedom), \(\mathbf{\Psi}\) is the positive definite scale matrix and \(\Gamma_p\) is the multivariate gamma function. The rate matrix is \(\mathbf{\Psi}^{-1}\).

Note

mean returns the Cholesky factor of \(\mathbb{E}[\mathbf{X}] = \mathbf{\Psi} / (\nu - p - 1)\), not \(\mathbb{E}[\mathbf{L}]\), and variance is not implemented (NaN).

Samples are drawn with a Bartlett decomposition of the precision \(\mathbf{X}^{-1}\): \(\mathbf{L} = \mathbf{L}_\Psi \mathbf{A}^{-1}\), where \(\mathbf{L}_\Psi\) is scale_tril and \(\mathbf{A}\) is lower triangular with \(A_{ii} \sim \sqrt{\chi^2_{\nu - p + i}}\) and \(A_{ij} \sim \mathcal{N}(0, 1)\) for \(i > j\), so that \(\mathbf{A}^T \mathbf{A} \sim W(\mathbf{I}, \nu)\). The degrees of freedom increase with \(i\), unlike WishartCholesky, because \(\mathbf{A}^T\) is the upper-triangular Bartlett factor.

Parameters:
  • concentration – Degrees of freedom parameter (often denoted \(\nu\)). Must be greater than p - 1 where p is the dimension of the scale matrix.

  • scale_matrix – Positive definite scale matrix \(\mathbf{\Psi}\), analogous to the inverse rate of a Gamma distribution.

  • rate_matrix – Inverse of the scale matrix, analogous to the rate of a Gamma distribution.

  • scale_tril – Cholesky decomposition of the scale matrix.

References

[1] https://en.wikipedia.org/wiki/Inverse-Wishart_distribution [2] https://en.wikipedia.org/wiki/Wishart_distribution#Bartlett_decomposition

arg_constraints: dict[str, Any] = {'concentration': Dependent(), 'rate_matrix': PositiveDefinite(), 'scale_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
support = LowerCholesky()
reparametrized_params: list[str] = ['scale_matrix', 'rate_matrix', 'scale_tril']
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

scale_matrix()[source]
rate_matrix()[source]
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

mean() → Array[source]

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

classmethod infer_shapes(concentration: tuple[int, ...] = (), scale_matrix: tuple[int, ...] | None = None, rate_matrix: tuple[int, ...] | None = None, scale_tril: tuple[int, ...] | None = None)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

Kumaraswamy

class Kumaraswamy(concentration1: Array | ndarray | bool | number | bool | int | float | complex, concentration0: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

The Kumaraswamy distribution, a continuous distribution on the unit interval parameterized by two positive shape parameters \(a\) (concentration1) and \(b\) (concentration0). It is a Beta-like family with a simple closed form PDF and CDF, often used as a computationally convenient alternative to the Beta distribution.

The Probability Density Function (PDF) is:

\[f(x \mid a, b) = a\, b\, x^{a-1}\,(1 - x^{a})^{b-1}, \quad x \in (0, 1)\]

The Cumulative Distribution Function (CDF) is:

\[F(x \mid a, b) = 1 - (1 - x^{a})^{b}, \quad x \in (0, 1)\]

where \(a > 0\) is the first shape parameter (concentration1) and \(b > 0\) is the second shape parameter (concentration0).

Parameters:
  • concentration1 – Shape parameter \(a > 0\).

  • concentration0 – Shape parameter \(b > 0\).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration0': Positive(lower_bound=0.0), 'concentration1': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['concentration1', 'concentration0']
support = UnitInterval(lower_bound=0.0, upper_bound=1.0)
KL_KUMARASWAMY_BETA_TAYLOR_ORDER = 10
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the inverse CDF transform. If \(U \sim \mathrm{Uniform}(0, 1)\), then

\[X = \bigl(1 - U^{1/b}\bigr)^{1/a}\]

which has the same law as the usual inverse \(\bigl(1 - (1-U)^{1/b}\bigr)^{1/a}\) because \(U\) and \(1-U\) are equal in distribution. Values are clipped away from 0 and 1 for numerical stability.

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Samples in the open unit interval.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x \mid a, b) = \ln a + \ln b + (a - 1)\ln x + (b - 1)\ln(1 - x^{a})\]
Parameters:

value – Point \(x \in (0, 1)\) at which to evaluate the log PDF.

Returns:

Log probability density under the Kumaraswamy distribution.

property mean: Array

Mean of the Kumaraswamy distribution:

\[\mathbb{E}[X] = b\, B\!\left(1 + \tfrac{1}{a},\, b\right)\]

where \(B\) is the beta function.

property variance: Array

Variance of the Kumaraswamy distribution:

\[\mathrm{Var}(X) = b\, B\!\left(1 + \tfrac{2}{a},\, b\right) - \bigl(\mathbb{E}[X]\bigr)^{2}\]

Laplace

class Laplace(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

The Laplace (double-exponential) distribution, a continuous real-valued distribution parameterized by location \(\mu\) and scale \(b > 0\). It is the distribution of the difference of two i.i.d. exponential variates and has heavier tails than the Normal distribution.

The Probability Density Function (PDF) is:

\[f(x \mid \mu, b) = \frac{1}{2 b} \exp\!\left(-\frac{|x - \mu|}{b}\right), \quad x \in \mathbb{R}\]

where \(\mu \in \mathbb{R}\) is the location (loc) and \(b > 0\) is the scale (scale).

Parameters:
  • loc – Location parameter \(\mu \in \mathbb{R}\). Defaults to 0.0.

  • scale – Scale parameter \(b > 0\). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the location-scale transform \(X = \mu + b Z\), where \(Z \sim \mathrm{Laplace}(0, 1)\) is drawn from laplace().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the Laplace distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x \mid \mu, b) = -\frac{|x - \mu|}{b} - \ln(2 b)\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the Laplace distribution.

property mean: Array

Mean of the Laplace distribution:

\[\mathbb{E}[X] = \mu\]
property variance: Array

Variance of the Laplace distribution:

\[\mathrm{Var}(X) = 2 b^2\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Laplace distribution. Letting \(z = (x - \mu)/b\),

\[F(x \mid \mu, b) = \frac{1}{2} - \frac{1}{2}\, \operatorname{sgn}(z)\,\left(e^{-|z|} - 1\right)\]

The implementation uses expm1() for numerical stability near \(z = 0\).

Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the Laplace distribution:

\[F^{-1}(q \mid \mu, b) = \mu - b\,\mathrm{sgn}\left(q - \frac{1}{2}\right)\, \ln\!\left(1 - 2 \left| q - \frac{1}{2} \right| \right), \quad q \in [0, 1]\]
Parameters:

q – Quantile values in \([0, 1]\).

Returns:

Real-valued quantiles of the Laplace distribution at q.

entropy() → Array[source]

Differential entropy of the Laplace distribution:

\[H(X) = \ln(2 b) + 1\]

Levy

class Levy(loc: Array | ndarray | bool | number | bool | int | float | complex, scale: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Lévy distribution is a special case of Lévy alpha-stable distribution. Its probability density function is given by,

\[f(x\mid \mu, c) = \sqrt{\frac{c}{2\pi(x-\mu)^{3}}} \exp\left(-\frac{c}{2(x-\mu)}\right), \qquad x > \mu\]

where \(\mu\) is the location parameter and \(c\) is the scale parameter. The support is \(x > \mu\). The cumulative distribution function and its inverse are

\[F(x \mid \mu, c) = \operatorname{erfc}\!\left(\sqrt{\frac{c}{2(x-\mu)}}\right) = 2 - 2\Phi\!\left(\sqrt{\frac{c}{x - \mu}}\right), \qquad F^{-1}(q \mid \mu, c) = \mu + \frac{c}{\big(\Phi^{-1}(1 - q/2)\big)^2},\]

where \(\Phi\) is the standard normal cumulative distribution function. The density has an \(x^{-3/2}\) tail, so no moment of order \(\ge 1/2\) exists: \(\mathbb{E}[X] = \operatorname{Var}[X] = \infty\). The median is \(\mu + c / \big(\Phi^{-1}(3/4)\big)^2 \approx \mu + 2.198\,c\), the mode is \(\mu + c/3\), and the entropy is

\[H(X) = \frac{1 + 3\gamma + \ln(16\pi c^2)}{2},\]

with Euler–Mascheroni constant \(\gamma\). If \(Z \sim \mathcal{N}(0, 1)\) then \(\mu + c/Z^2 \sim \mathrm{Levy}(\mu, c)\); the Lévy distribution is the stable distribution with \(\alpha = 1/2\) and \(\beta = 1\).

Parameters:
  • loc – Location parameter \(\mu\).

  • scale – Scale parameter \(c\).

Note

sample draws by inverse-cdf transform of uniform variates (ndtri); mean and variance return inf arrays; no parameter is marked as reparametrized, so has_rsample is False.

References

[1] https://en.wikipedia.org/wiki/L%C3%A9vy_distribution

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Compute the log probability density function of the Lévy distribution.

\[\log f(x\mid \mu, c) = \frac{1}{2}\log\left(\frac{c}{2\pi}\right) - \frac{c}{2(x-\mu)} - \frac{3}{2}\log(x-\mu), \qquad x > \mu\]
Parameters:

value – A batch of samples from the distribution.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

numpy.ndarray

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of Lévy distribution is given by,

\[F^{-1}(q\mid \mu, c) = \mu + c\left(\Phi^{-1}(1-q/2)\right)^{-2}\]

where \(\Phi^{-1}\) is the inverse of the standard normal cumulative distribution function.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of Lévy distribution is given by,

\[F(x\mid \mu, c) = 2 - 2\Phi\left(\sqrt{\frac{c}{x-\mu}}\right)\]

where \(\Phi\) is the standard normal cumulative distribution function.

Parameters:

value – samples from Lévy distribution.

Returns:

output of the cumulative distribution function evaluated at value.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

entropy() → Array[source]

If \(X \sim \text{Levy}(\mu, c)\), then the entropy of \(X\) is given by,

\[H(X) = \frac{1}{2}+\frac{3}{2}\gamma+\frac{1}{2}\ln{\left(16\pi c^2\right)}\]

LKJ

class LKJ(dimension: int, concentration: Array | ndarray | bool | number | bool | int | float | complex = 1.0, sample_method: Literal['onion', 'cvine'] = 'onion', *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

LKJ distribution for correlation matrices. The distribution is controlled by concentration parameter \(\eta\) to make the probability of the correlation matrix \(M\) proportional to \(\det(M)^{\eta - 1}\). Because of that, when concentration == 1, we have a uniform distribution over correlation matrices.

When concentration > 1, the distribution favors samples with large determinant. This is useful when we know a priori that the underlying variables are not correlated.

When concentration < 1, the distribution favors samples with small determinant. This is useful when we know a priori that some underlying variables are correlated.

The probability density of a \(D \times D\) correlation matrix \(M\), with respect to Lebesgue measure on its strictly lower-triangular entries, is

\[p(M \mid \eta) = c_D(\eta) \det(M)^{\eta - 1}, \qquad c_D(\eta) = \frac{\Gamma(\alpha)^{D-1}} {\pi^{(D-1)/2} \, \Gamma_{D-1}\!\left(\alpha - \tfrac{1}{2}\right)}, \qquad \alpha = \eta + \frac{D-1}{2},\]

where \(\Gamma_{D-1}\) is the multivariate gamma function.

The support is the set of symmetric positive-definite \(D \times D\) matrices with unit diagonal. The mean is \(\mathbb{E}[M] = I\), and each off-diagonal entry satisfies \(\tfrac{M_{ij} + 1}{2} \sim \mathrm{Beta}\!\left(\eta - 1 + \tfrac{D}{2},\, \eta - 1 + \tfrac{D}{2}\right)\), so that

\[\mathrm{Var}[M_{ij}] = \frac{1}{2\eta + D - 1}, \qquad i \neq j.\]

Sample code for using LKJ in the context of multivariate normal sample:

def model(y):  # y has dimension N x d
    d = y.shape[1]
    N = y.shape[0]
    # Vector of variances for each of the d variables
    theta = numpyro.sample("theta", dist.HalfCauchy(jnp.ones(d)))

    concentration = jnp.ones(1)  # Implies a uniform distribution over correlation matrices
    corr_mat = numpyro.sample("corr_mat", dist.LKJ(d, concentration))
    sigma = jnp.sqrt(theta)
    # we can also use a faster formula `cov_mat = jnp.outer(sigma, sigma) * corr_mat`
    cov_mat = jnp.matmul(jnp.matmul(jnp.diag(sigma), corr_mat), jnp.diag(sigma))

    # Vector of expectations
    mu = jnp.zeros(d)

    with numpyro.plate("observations", N):
        obs = numpyro.sample("obs", dist.MultivariateNormal(mu, covariance_matrix=cov_mat), obs=y)
    return obs
Parameters:
  • dimension (int) – dimension of the matrices

  • concentration (ndarray) – concentration/shape parameter of the distribution (often referred to as eta)

  • sample_method (str) – Either “cvine” or “onion”. Both methods are proposed in [1] and offer the same distribution over correlation matrices. But they are different in how to generate samples. Defaults to “onion”.

References

[1] Generating random correlation matrices based on vines and extended onion method, Daniel Lewandowski, Dorota Kurowicka, Harry Joe https://doi.org/10.1016/j.jmva.2009.04.008

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['concentration']
support = CorrMatrix()
pytree_aux_fields: tuple[str, ...] = ('dimension', 'sample_method')
property mean: Array

Mean of the distribution.

LKJCholesky

class LKJCholesky(dimension: int, concentration: Array | ndarray | bool | number | bool | int | float | complex = 1.0, sample_method: Literal['onion', 'cvine'] = 'onion', *, validate_args: bool | None = None)[source]

Bases: Distribution

LKJ distribution for lower Cholesky factors of correlation matrices. The distribution is controlled by concentration parameter \(\eta\) to make the probability of the correlation matrix \(M\) generated from a Cholesky factor proportional to \(\det(M)^{\eta - 1}\). Because of that, when concentration == 1, we have a uniform distribution over Cholesky factors of correlation matrices.

When concentration > 1, the distribution favors samples with large diagonal entries (hence large determinant). This is useful when we know a priori that the underlying variables are not correlated.

When concentration < 1, the distribution favors samples with small diagonal entries (hence small determinant). This is useful when we know a priori that some underlying variables are correlated.

Writing \(M = LL^\top\) for the correlation matrix generated by a lower Cholesky factor \(L\) of dimension \(D \times D\) (so \(L_{11} = 1\)), the probability density of \(L\), with respect to Lebesgue measure on its strictly lower-triangular entries, is

\[p(L \mid \eta) = c_D(\eta) \prod_{i=2}^{D} L_{ii}^{\,2\eta - 2 + D - i}, \qquad c_D(\eta) = \frac{\Gamma(\alpha)^{D-1}} {\pi^{(D-1)/2} \, \Gamma_{D-1}\!\left(\alpha - \tfrac{1}{2}\right)}, \qquad \alpha = \eta + \frac{D-1}{2},\]

where \(\Gamma_{D-1}\) is the multivariate gamma function and \(c_D(\eta)\) is the same normalizing constant as in LKJ. The exponent combines \(\det(M)^{\eta - 1} = \prod_{i=2}^{D} L_{ii}^{2\eta - 2}\) (recall \(L_{11} = 1\)) with the Jacobian \(\prod_{i=2}^{D} L_{ii}^{D-i}\) of the map from the strictly lower-triangular entries of \(L\) to those of \(M\).

The support is the set of lower-triangular \(D \times D\) matrices with positive diagonal and unit-norm rows. The correlation matrix \(M = LL^\top\) has mean \(\mathbb{E}[M] = I\), and each off-diagonal entry satisfies \(\tfrac{M_{ij} + 1}{2} \sim \mathrm{Beta}\!\left(\eta - 1 + \tfrac{D}{2},\, \eta - 1 + \tfrac{D}{2}\right)\), so that

\[\mathrm{Var}[M_{ij}] = \frac{1}{2\eta + D - 1}, \qquad i \neq j.\]

Sample code for using LKJCholesky in the context of multivariate normal sample:

def model(y):  # y has dimension N x d
    d = y.shape[1]
    N = y.shape[0]
    # Vector of variances for each of the d variables
    theta = numpyro.sample("theta", dist.HalfCauchy(jnp.ones(d)))
    # Lower cholesky factor of a correlation matrix
    concentration = jnp.ones(1)  # Implies a uniform distribution over correlation matrices
    L_omega = numpyro.sample("L_omega", dist.LKJCholesky(d, concentration))
    # Lower cholesky factor of the covariance matrix
    sigma = jnp.sqrt(theta)
    # we can also use a faster formula `L_Omega = sigma[..., None] * L_omega`
    L_Omega = jnp.matmul(jnp.diag(sigma), L_omega)

    # Vector of expectations
    mu = jnp.zeros(d)

    with numpyro.plate("observations", N):
        obs = numpyro.sample("obs", dist.MultivariateNormal(mu, scale_tril=L_Omega), obs=y)
    return obs
Parameters:
  • dimension (int) – dimension of the matrices

  • concentration (ndarray) – concentration/shape parameter of the distribution (often referred to as eta)

  • sample_method (str) – Either “cvine” or “onion”. Both methods are proposed in [1] and offer the same distribution over correlation matrices. But they are different in how to generate samples. Defaults to “onion”.

References

[1] Generating random correlation matrices based on vines and extended onion method, Daniel Lewandowski, Dorota Kurowicka, Harry Joe https://doi.org/10.1016/j.jmva.2009.04.008

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['concentration']
support = CorrCholesky()
pytree_data_fields: tuple[str, ...] = ('_beta', 'concentration')
pytree_aux_fields: tuple[str, ...] = ('dimension', 'sample_method')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

LogNormal

class LogNormal(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

The Log-Normal distribution, a continuous distribution on the positive reals parameterized by \(\mu\) and \(\sigma > 0\). It is the distribution of \(\exp(Y)\) where \(Y \sim \mathrm{Normal}(\mu, \sigma)\), so \(\mu\) and \(\sigma\) describe the variable on the log scale rather than the mean and standard deviation of \(X\) itself.

The Probability Density Function (PDF) is:

\[f(x \mid \mu, \sigma) = \frac{1}{x \sigma \sqrt{2\pi}} \exp\!\left(-\frac{(\ln x - \mu)^{2}}{2\sigma^{2}}\right), \quad x > 0\]

where \(\mu \in \mathbb{R}\) is the location on the log scale (loc) and \(\sigma > 0\) is the scale on the log scale (scale).

Parameters:
  • loc – Location on the log scale \(\mu \in \mathbb{R}\). Defaults to 0.0.

  • scale – Scale on the log scale \(\sigma > 0\). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
reparametrized_params: list[str] = ['loc', 'scale']
property mean: Array

Mean of the Log-Normal distribution:

\[\mathbb{E}[X] = \exp\!\left(\mu + \frac{\sigma^{2}}{2}\right)\]
property variance: Array

Variance of the Log-Normal distribution:

\[\mathrm{Var}(X) = \left(e^{\sigma^{2}} - 1\right) e^{2\mu + \sigma^{2}}\]
entropy() → Array[source]

Differential entropy of the Log-Normal distribution:

\[H(X) = \mu + \frac{1}{2}\ln\!\left(2\pi e \sigma^{2}\right)\]

LogUniform

class LogUniform(low: Array | ndarray | bool | number | bool | int | float | complex, high: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

The Log-Uniform (reciprocal) distribution, a continuous distribution on \([a, b]\) with \(0 < a < b\). It is the distribution of \(\exp(Y)\) where \(Y\) is uniform on \([\ln a, \ln b]\), so its density is flat on a log scale and every order of magnitude in \([a, b]\) carries equal probability.

The Probability Density Function (PDF) is:

\[f(x \mid a, b) = \frac{1}{x \left(\ln b - \ln a\right)}, \quad a \leq x \leq b\]

where \(a > 0\) is the lower bound (low) and \(b > a\) is the upper bound (high).

Parameters:
  • low – Lower bound \(a > 0\) of the support.

  • high – Upper bound \(b > a\) of the support.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'high': Positive(lower_bound=0.0), 'low': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['low', 'high']
pytree_data_fields: tuple[str, ...] = ('low', 'high')
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

property mean: Array

Mean of the Log-Uniform distribution:

\[\mathbb{E}[X] = \frac{b - a}{\ln b - \ln a}\]
property variance: Array

Variance of the Log-Uniform distribution:

\[\mathrm{Var}(X) = \frac{b^{2} - a^{2}}{2\left(\ln b - \ln a\right)} - \left(\frac{b - a}{\ln b - \ln a}\right)^{2}\]
entropy() → Array[source]

Differential entropy of the Log-Uniform distribution:

\[H(X) = \frac{\ln a + \ln b}{2} + \ln\!\left(\ln b - \ln a\right)\]

Logistic

class Logistic(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

The Logistic distribution, a continuous real-valued distribution parameterized by location \(\mu\) and scale \(s > 0\). Its CDF is the standard logistic (sigmoid) function shifted and scaled to \(\mu\), \(s\), which makes it the natural latent distribution underlying logistic regression.

The Probability Density Function (PDF) is:

\[f(x \mid \mu, s) = \frac{ \exp\!\left(-\displaystyle\frac{x - \mu}{s}\right) }{ s \left(1 + \exp\!\left(-\displaystyle\frac{x - \mu}{s}\right)\right)^{2} }, \quad x \in \mathbb{R}\]

where \(\mu \in \mathbb{R}\) is the location (loc) and \(s > 0\) is the scale (scale).

Parameters:
  • loc – Location parameter \(\mu \in \mathbb{R}\). Defaults to 0.0.

  • scale – Scale parameter \(s > 0\). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the location-scale transform \(X = \mu + s Z\), where \(Z \sim \mathrm{Logistic}(0, 1)\) is drawn from logistic().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the Logistic distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

Letting \(u = (\mu - x)/s\), the log PDF is

\[\ln f(x \mid \mu, s) = u - \ln s - 2 \ln(1 + e^{u})\]

The implementation uses softplus() for \(\ln(1 + e^{u})\), which is numerically stable for both large positive and large negative values of \(u\).

Parameters:

value – Real-valued point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the Logistic distribution.

property mean: Array

Mean of the Logistic distribution:

\[\mathbb{E}[X] = \mu\]
property variance: Array

Variance of the Logistic distribution:

\[\mathrm{Var}(X) = \frac{\pi^2 s^2}{3}\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Logistic distribution. Letting \(z = (x - \mu)/s\),

\[F(x \mid \mu, s) = \sigma(z) = \frac{1}{1 + e^{-z}}\]

where \(\sigma\) is the logistic sigmoid, computed via expit().

Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the Logistic distribution:

\[F^{-1}(q \mid \mu, s) = \mu + s\,\operatorname{logit}(q), \quad q \in [0, 1]\]

where \(\operatorname{logit}(q) = \ln(q / (1 - q))\).

Parameters:

q – Quantile values in \([0, 1]\).

Returns:

Real-valued quantiles of the Logistic distribution at q.

entropy() → Array[source]

Differential entropy of the Logistic distribution:

\[H(X) = \ln(s) + 2\]

LowRankMultivariateNormal

class LowRankMultivariateNormal(loc: Array | ndarray | bool | number | bool | int | float | complex, cov_factor: Array | ndarray | bool | number | bool | int | float | complex, cov_diag: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Multivariate normal distribution on \(\mathbb{R}^d\) whose covariance matrix is the sum of a low-rank matrix and a positive diagonal matrix,

\[\Sigma = W W^\top + \operatorname{diag}(D),\]

where \(W \in \mathbb{R}^{d \times m}\) is the covariance factor (usually with \(m \ll d\)) and \(D \in \mathbb{R}_{>0}^{d}\) is the diagonal part. The Probability Density Function (PDF) is

\[f(x ; \mu, W, D) = (2 \pi)^{-d/2} |\Sigma|^{-1/2} \exp\left(-\frac{1}{2} (x - \mu)^\top \Sigma^{-1} (x - \mu)\right), \quad x \in \mathbb{R}^d\]

The mean is \(\mu\) and the marginal variances are \(\operatorname{Var}(x_i) = \sum_{j=1}^{m} W_{ij}^2 + D_i\).

A sample is generated as \(x = \mu + W \epsilon_W + \sqrt{D} \odot \epsilon_D\) with \(\epsilon_W \sim \mathrm{Normal}(0, I_m)\) and \(\epsilon_D \sim \mathrm{Normal}(0, I_d)\). The log density avoids forming the \(d \times d\) matrix \(\Sigma\) by using the Woodbury matrix identity and the matrix determinant lemma with the \(m \times m\) capacitance matrix \(C = I_m + W^\top \operatorname{diag}(D)^{-1} W\):

\[\Sigma^{-1} = \operatorname{diag}(D)^{-1} - \operatorname{diag}(D)^{-1} W C^{-1} W^\top \operatorname{diag}(D)^{-1}, \qquad \log |\Sigma| = \log |C| + \sum_{i=1}^{d} \log D_i.\]
Parameters:
  • loc – Mean vector \(\mu \in \mathbb{R}^d\).

  • cov_factor – Factor \(W\) of the low-rank part of the covariance, with shape (..., d, m).

  • cov_diag – Diagonal part \(D > 0\) of the covariance, with shape (..., d).

arg_constraints: dict[str, Any] = {'cov_diag': IndependentConstraint(Positive(lower_bound=0.0), 1), 'cov_factor': IndependentConstraint(Real(), 2), 'loc': RealVector(Real(), 1)}
support = RealVector(Real(), 1)
reparametrized_params: list[str] = ['loc', 'cov_factor', 'cov_diag']
pytree_data_fields: tuple[str, ...] = ('loc', 'cov_factor', 'cov_diag', '_capacitance_tril')
property mean: Array

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

scale_tril() → Array[source]
covariance_matrix() → Array[source]
precision_matrix() → Array[source]
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

entropy() → Array[source]

Returns the entropy of the distribution.

classmethod infer_shapes(loc, cov_factor, cov_diag)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

MatrixNormal

class MatrixNormal(loc: Array | ndarray | bool | number | bool | int | float | complex, scale_tril_row: Array | ndarray | bool | number | bool | int | float | complex, scale_tril_column: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Matrix normal distribution on real matrices with event_shape = (n, p) and mean matrix \(M\) (loc), as described in [1]. The row and column covariance matrices are \(U = L_r L_r^\top\) and \(V = L_c L_c^\top\), where \(L_r\) (scale_tril_row) and \(L_c\) (scale_tril_column) are lower Cholesky factors with positive diagonal entries.

The probability density function is

\[f(X; M, U, V) = \frac{\exp\left(-\frac{1}{2}\operatorname{tr}\left[ U^{-1}(X-M)V^{-1}(X-M)^\top\right]\right)} {(2\pi)^{np/2}|U|^{p/2}|V|^{n/2}}, \qquad X \in \mathbb{R}^{n \times p}.\]

Equivalently, \(\operatorname{vec}(X) \sim \mathcal{N}(\operatorname{vec}(M), V \otimes U)\), where \(\operatorname{vec}\) stacks the columns of a matrix and \(\otimes\) denotes the Kronecker product. For an unbatched matrix x, this is x.reshape(-1, order="F").

Samples are generated as \(X = M + L_r Z L_c^\top\), where \(Z\) is an \(n \times p\) matrix of independent standard normal entries. The log density is evaluated using triangular solves and the diagonals of the Cholesky factors, without constructing the \(np \times np\) Kronecker covariance matrix.

Leading dimensions of all three parameters must be broadcast-compatible and determine batch_shape. The last two dimensions are matrix dimensions: loc has shape (..., n, p), scale_tril_row has shape (..., n, n), and scale_tril_column has shape (..., p, p). Samples have shape sample_shape + batch_shape + (n, p), and log_prob reduces the two event dimensions to give one value per matrix.

Parameters:
  • loc (array_like) – Mean matrix with shape (..., n, p).

  • scale_tril_row (array_like) – Lower Cholesky factor of the row covariance matrix, with shape (..., n, n) and positive diagonal entries.

  • scale_tril_column (array_like) – Lower Cholesky factor of the column covariance matrix, with shape (..., p, p) and positive diagonal entries.

Example

A matrix with two rows and three columns is equivalent to a six-dimensional multivariate normal when its columns are stacked:

>>> import jax.numpy as jnp
>>> from numpyro.distributions import MatrixNormal, MultivariateNormal
>>> loc = jnp.arange(6.0).reshape(2, 3)
>>> row = jnp.array([[1.0, 0.0], [0.4, 0.8]])
>>> column = jnp.array([[1.0, 0.0, 0.0], [0.3, 1.2, 0.0], [0.2, -0.1, 0.7]])
>>> matrix_normal = MatrixNormal(loc, row, column)
>>> vector_normal = MultivariateNormal(
...     loc.reshape(-1, order="F"), scale_tril=jnp.kron(column, row)
... )
>>> x = loc + jnp.array([[0.2, -0.3, 0.5], [0.7, 0.1, -0.4]])
>>> bool(jnp.allclose(
...     matrix_normal.log_prob(x),
...     vector_normal.log_prob(x.reshape(-1, order="F")),
... ))
True

References

[1] https://en.wikipedia.org/wiki/Matrix_normal_distribution

arg_constraints: dict[str, Any] = {'loc': RealVector(Real(), 1), 'scale_tril_column': LowerCholesky(), 'scale_tril_row': LowerCholesky()}
support = RealMatrix(Real(), 2)
reparametrized_params: list[str] = ['loc', 'scale_tril_row', 'scale_tril_column']
property mean: Array

Mean of the distribution.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(values) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

MultivariateNormal

class MultivariateNormal(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, covariance_matrix: Array | ndarray | bool | number | bool | int | float | complex | None = None, precision_matrix: Array | ndarray | bool | number | bool | int | float | complex | None = None, scale_tril: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Multivariate normal (Gaussian) distribution on \(\mathbb{R}^d\) with mean vector \(\mu\) and positive definite covariance matrix \(\Sigma\). Exactly one of covariance_matrix, precision_matrix (\(\Sigma^{-1}\)) or scale_tril (the lower Cholesky factor \(L\) with \(\Sigma = L L^\top\)) must be specified; internally all three are represented by scale_tril.

The Probability Density Function (PDF) is:

\[f(x ; \mu, \Sigma) = (2 \pi)^{-d/2} |\Sigma|^{-1/2} \exp\left(-\frac{1}{2} (x - \mu)^\top \Sigma^{-1} (x - \mu)\right), \quad x \in \mathbb{R}^d\]

where \(d\) is the event size. Samples are generated as \(\mu + L z\) with \(z \sim \mathrm{Normal}(0, I_d)\), and the quadratic form and log determinant are evaluated from \(L\) via triangular solves.

Parameters:
  • loc – Mean vector \(\mu \in \mathbb{R}^d\). A scalar is promoted to a vector of length 1. Defaults to 0.0.

  • covariance_matrix – Covariance matrix \(\Sigma\) (positive definite). Mutually exclusive with precision_matrix and scale_tril.

  • precision_matrix – Precision matrix \(\Sigma^{-1}\) (positive definite).

  • scale_tril – Lower Cholesky factor \(L\) of \(\Sigma\).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'covariance_matrix': PositiveDefinite(), 'loc': RealVector(Real(), 1), 'precision_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
support = RealVector(Real(), 1)
reparametrized_params: list[str] = ['loc', 'covariance_matrix', 'precision_matrix', 'scale_tril']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the reparameterization \(X = \mu + L Z\) with \(Z \sim \mathrm{Normal}(0, I_d)\) drawn from normal() and \(L\) = scale_tril.

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Samples from the multivariate normal distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x ; \mu, \Sigma) = -\frac{1}{2} (x - \mu)^\top \Sigma^{-1} (x - \mu) -\frac{1}{2} \ln |\Sigma| - \frac{d}{2} \ln(2 \pi)\]

The Mahalanobis quadratic form and \(\ln |\Sigma|\) are evaluated from the Cholesky factor scale_tril via triangular solves.

Parameters:

value – Point \(x \in \mathbb{R}^d\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the multivariate normal distribution.

covariance_matrix()[source]

Covariance matrix \(\Sigma = L L^\top\), recovered from scale_tril.

precision_matrix()[source]

Precision matrix \(\Sigma^{-1} = L^{-\top} L^{-1}\), recovered from scale_tril.

property mean: Array

Mean of the multivariate normal distribution:

\[\mathbb{E}[X] = \mu\]
property variance: Array

Variance (diagonal of \(\Sigma\)) of the multivariate normal distribution:

\[\mathrm{Var}(X_i) = \Sigma_{ii} = \sum_j L_{ij}^2\]
classmethod infer_shapes(loc=(), covariance_matrix=None, precision_matrix=None, scale_tril=None)[source]

Infer the batch and event shapes from the shapes of the arguments.

Returns:

A tuple (batch_shape, event_shape).

entropy() → Array[source]

Differential entropy of the multivariate normal distribution:

\[H(X) = \frac{d}{2} \ln(2 \pi e) + \frac{1}{2} \ln |\Sigma|\]
Returns:

Entropy in nats.

MultivariateStudentT

class MultivariateStudentT(df: Array | ndarray | bool | number | bool | int | float | complex, loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale_tril: Array | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Multivariate Student’s t-distribution on \(\mathbb{R}^d\) with degrees of freedom \(\nu > 0\), location vector \(\mu\) and positive definite scale matrix \(\Sigma = L L^\top\), given by its lower Cholesky factor scale_tril. It is the distribution of \(\mu + L Z / \sqrt{V / \nu}\) where \(Z \sim \mathrm{Normal}(0, I_d)\) is independent of \(V \sim \chi^2(\nu)\); equivalently, a multivariate normal with a shared \(\chi^2\) scale mixture. As \(\nu \to \infty\) it approaches MultivariateNormal, and \(\nu = 1\) gives the multivariate Cauchy distribution.

The Probability Density Function (PDF) is:

\[f(x ; \nu, \mu, \Sigma) = \frac{\Gamma\left(\displaystyle\frac{\nu + d}{2}\right)} {\Gamma\left(\displaystyle\frac{\nu}{2}\right) (\nu \pi)^{d/2} |\Sigma|^{1/2}} \left(1 + \frac{1}{\nu} (x - \mu)^\top \Sigma^{-1} (x - \mu)\right)^{-\frac{\nu + d}{2}}, \quad x \in \mathbb{R}^d\]

where \(d\) is the event size. Note that \(\Sigma\) is a scale matrix, not the covariance: the covariance is \(\frac{\nu}{\nu - 2} \Sigma\) for \(\nu > 2\), and the mean equals \(\mu\) only for \(\nu > 1\).

Parameters:
  • df – Degrees of freedom \(\nu > 0\).

  • loc – Location vector \(\mu\). A scalar is promoted to a vector of length 1. Defaults to 0.0.

  • scale_tril – Lower Cholesky factor \(L\) of the scale matrix \(\Sigma\) (required).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'df': Positive(lower_bound=0.0), 'loc': RealVector(Real(), 1), 'scale_tril': LowerCholesky()}
support = RealVector(Real(), 1)
reparametrized_params: list[str] = ['df', 'loc', 'scale_tril']
pytree_data_fields: tuple[str, ...] = ('df', 'loc', 'scale_tril', '_chi2')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the scale-mixture representation \(X = \mu + L Z / \sqrt{V / \nu}\) with \(Z \sim \mathrm{Normal}(0, I_d)\) independent of \(V \sim \chi^2(\nu)\) and \(L\) = scale_tril.

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Samples from the multivariate Student’s t-distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x ; \nu, \mu, \Sigma) = -\frac{\nu + d}{2} \ln\!\left(1 + \frac{1}{\nu} (x - \mu)^\top \Sigma^{-1} (x - \mu)\right) - \ln Z, \quad Z = \frac{\Gamma\!\left(\frac{\nu}{2}\right) (\nu \pi)^{d/2} |\Sigma|^{1/2}} {\Gamma\!\left(\frac{\nu + d}{2}\right)}\]

The Mahalanobis quadratic form and \(\ln |\Sigma|\) are evaluated from the Cholesky factor scale_tril via triangular solves.

Parameters:

value – Point \(x \in \mathbb{R}^d\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the multivariate Student’s t-distribution.

covariance_matrix()[source]

Scale matrix \(\Sigma = L L^\top\), recovered from scale_tril. Note this is not the covariance of the distribution; the actual covariance is \(\frac{\nu}{\nu - 2} \Sigma\) for \(\nu > 2\).

precision_matrix() → Array[source]

Inverse of the scale matrix, \(\Sigma^{-1} = L^{-\top} L^{-1}\), recovered from scale_tril.

property mean: Array

Mean of the multivariate Student’s t-distribution:

\[\mathbb{E}[X] = \mu, \quad \nu > 1\]

Returns inf for \(\nu \leq 1\), where the mean is undefined (matching SciPy).

property variance: Array

Variance of the multivariate Student’s t-distribution:

\[\mathrm{Var}(X_i) = \frac{\nu}{\nu - 2} \, \Sigma_{ii}, \quad \nu > 2\]

Returns nan for \(\nu \leq 1\) and inf for \(1 < \nu \leq 2\), where the variance is undefined.

classmethod infer_shapes(df, loc, scale_tril)[source]

Infer the batch and event shapes from the shapes of the arguments.

Returns:

A tuple (batch_shape, event_shape).

Normal

class Normal(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Normal (Gaussian) distribution parameterized by mean (loc) and standard deviation (scale).

The probability density function (PDF) is defined as:

\[f(x; \mu, \sigma) = \frac{1}{\sigma \sqrt{2\pi}} \exp\!\left( -\frac{(x - \mu)^2}{2\sigma^2} \right)\]

where \(x \in \mathbb{R}\), \(\mu \in \mathbb{R}\) is the mean, and \(\sigma > 0\) is the standard deviation.

Parameters:
  • loc (ArrayLike) – Mean of the distribution (\(\mu\)).

  • scale (ArrayLike) – Standard deviation of the distribution (\(\sigma\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples via the reparameterization trick: \(X = \mu + \sigma \epsilon\), where \(\epsilon \sim \mathcal{N}(0,1)\).

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from the Normal distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; \mu, \sigma) = -\frac{(x - \mu)^2}{2\sigma^2} - \log(\sigma \sqrt{2\pi})\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function.

\[F(x; \mu, \sigma) = \Phi\!\left(\frac{x-\mu}{\sigma}\right)\]

where, \(\Phi\) is the cumulative distribution function of standard normal distribution. Implementation uses jax.scipy.special.ndtr() for \(\Phi\).

Parameters:

value (ArrayLike) – Value to evaluate.

log_cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Log of the cumulative distribution function. Implementation calls jax.scipy.stats.norm.logcdf().

Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; \mu, \sigma) = \mu + \sigma\,\Phi^{-1}(q)\]

where, \(\mathrm{\Phi^{-1}}\) is inverse cumulative distribution function of standard normal distribution. Implementation uses jax.scipy.special.ndtri() for \(\Phi^{-1}\).

Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

property mean: Array

Calculates the analytical mean.

\[E[X] = \mu\]
property variance: Array

Calculates the analytical variance.

\[\mathrm{Var}(X) = \sigma^2\]
entropy() → Array[source]

Entropy of the Normal distribution.

\[H(X) = \frac{1}{2} \ln(2\pi e \sigma^2)\]

Pareto

class Pareto(scale: Array | ndarray | bool | number | bool | int | float | complex, alpha: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Pareto distribution parameterized by scale (scale) and tail index (alpha).

The probability density function (PDF) is defined as:

\[f(x; x_m, \alpha) = \frac{\alpha x_m^{\alpha}}{x^{\alpha + 1}}\]

where \(x > x_m\), \(x_m > 0\) is the scale and \(\alpha > 0\) is the shape. The cumulative distribution function (CDF) is \(F(x) = 1 - (x_m / x)^{\alpha}\).

The distribution is implemented as a TransformedDistribution: \(X = x_m e^{E}\) with \(E \sim \mathrm{Exponential}(\alpha)\), i.e. an Exponential base distribution followed by ExpTransform and AffineTransform.

The mean \(\alpha x_m / (\alpha - 1)\) is finite only for \(\alpha > 1\) and the variance \(\alpha x_m^2 / ((\alpha - 1)^2 (\alpha - 2))\) only for \(\alpha > 2\); both properties return inf otherwise.

Parameters:
  • scale (ArrayLike) – Scale parameter (\(x_m\)), the lower bound of the support.

  • alpha (ArrayLike) – Shape (tail index) parameter (\(\alpha\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'alpha': Positive(lower_bound=0.0), 'scale': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['scale', 'alpha']
property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

entropy() → Array[source]

Returns the entropy of the distribution.

RelaxedBernoulli

RelaxedBernoulli(temperature: Array | ndarray | bool | number | bool | int | float | complex, probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None) → RelaxedBernoulliLogits[source]

Continuous relaxation of the Bernoulli distribution on the unit interval.

At least one of probs or logits must be specified; if both are given, probs takes precedence and logits is ignored. A probability \(p\) is converted to logits \(\ell = \log p - \log(1 - p)\) and a RelaxedBernoulliLogits distribution is returned; see that class for the density and the sampling procedure.

Parameters:
  • temperature – Temperature parameter \(\lambda > 0\).

  • probs – Probability \(p \in (0, 1)\) of the corresponding Bernoulli distribution.

  • logits – Logits \(\ell \in \mathbb{R}\) of the corresponding Bernoulli distribution.

Raises:

ValueError – If neither probs nor logits is specified.

RelaxedBernoulliLogits

class RelaxedBernoulliLogits(temperature: Array | ndarray | bool | number | bool | int | float | complex, logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Continuous relaxation of the Bernoulli distribution on the unit interval (also known as the binary Concrete distribution), parameterized by a temperature \(\lambda > 0\) and logits \(\ell \in \mathbb{R}\).

A sample is generated by drawing \(z \sim \mathrm{Logistic}(\ell / \lambda, 1 / \lambda)\) and applying the sigmoid function,

\[x = \sigma(z) = \frac{1}{1 + e^{-z}}, \quad x \in (0, 1),\]

which is the reparameterized form of \(x = \sigma\left((\ell + \log u - \log(1 - u)) / \lambda\right)\) with \(u \sim \mathrm{Uniform}(0, 1)\). The Probability Density Function (PDF) is

\[f(x ; \lambda, \ell) = \frac{\lambda e^{\ell} x^{-\lambda - 1} (1 - x)^{-\lambda - 1}} {\left(e^{\ell} x^{-\lambda} + (1 - x)^{-\lambda}\right)^{2}}, \quad x \in (0, 1)\]

As \(\lambda \to 0\) the samples concentrate on \(\{0, 1\}\) with \(\mathbb{P}(x \to 1) = \sigma(\ell)\), recovering a Bernoulli distribution with the same logits.

Parameters:
  • temperature – Temperature parameter \(\lambda > 0\).

  • logits – Logits \(\ell \in \mathbb{R}\) of the corresponding Bernoulli distribution.

arg_constraints: dict[str, Any] = {'logits': Real(), 'temperature': Positive(lower_bound=0.0)}
support = UnitInterval(lower_bound=0.0, upper_bound=1.0)

SoftLaplace

class SoftLaplace(loc: Array | ndarray | bool | number | bool | int | float | complex, scale: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Smooth distribution with Laplace-like tail behavior.

The Probability Density Function (PDF), in terms of location \(\mu \in \mathbb{R}\) and scale \(\sigma > 0\), is

\[f(x ; \mu, \sigma) = \frac{1}{\pi\,\sigma\,\cosh\!\left(\displaystyle\frac{x-\mu}{\sigma}\right)}, \quad x \in \mathbb{R}\]

which is the log-convex density:

z = (value - loc) / scale
log_prob = log(2 / pi) - log(scale) - logaddexp(z, -z)

Like the Laplace density, this density has the heaviest possible tails (asymptotically) while still being log-convex. Unlike the Laplace distribution, this distribution is infinitely differentiable everywhere, and is thus suitable for HMC and Laplace approximation.

Parameters:
  • loc – Location parameter \(\mu \in \mathbb{R}\).

  • scale – Scale parameter \(\sigma > 0\).

arg_constraints: dict[str, Any] = {'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['loc', 'scale']
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

\[\log f(x ; \mu, \sigma) = \log\frac{2}{\pi} - \log\sigma - \log\!\left(e^{z} + e^{-z}\right), \quad z = \frac{x-\mu}{\sigma}\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density evaluated under the SoftLaplace distribution.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples by inverse-transform sampling: draw \(U \sim \mathrm{Uniform}(0, 1)\) and return \(F^{-1}(U)\), where \(F^{-1}\) is icdf().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the SoftLaplace distribution.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the SoftLaplace distribution:

\[F(x ; \mu, \sigma) = \frac{2}{\pi}\,\arctan\!\left(e^{z}\right), \quad z = \frac{x-\mu}{\sigma}\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

Probability that a SoftLaplace random variable is at most value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse Cumulative Distribution Function (quantile function), the inverse of cdf():

\[F^{-1}(q ; \mu, \sigma) = \mu + \sigma\, \log\!\left(\tan\!\left(\frac{\pi q}{2}\right)\right)\]
Parameters:

q – Quantile level \(q \in [0, 1]\).

Returns:

The value \(x\) such that \(F(x) = q\).

property mean: Array

Mean of the SoftLaplace distribution, equal to the location by symmetry:

\[\mathbb{E}[X] = \mu\]
property variance: Array

Variance of the SoftLaplace distribution:

\[\mathrm{Var}[X] = \left(\frac{\pi \sigma}{2}\right)^{2}\]

StudentT

class StudentT(df: Array | ndarray | bool | number | bool | int | float | complex, loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Student’s t-distribution, a continuous location-scale family on \(\mathbb{R}\) parameterized by degrees of freedom \(\nu > 0\), location \(\mu\) and scale \(\sigma > 0\). It is the distribution of \(\mu + \sigma T\) where \(T = Z / \sqrt{V / \nu}\), \(Z \sim \mathrm{Normal}(0, 1)\) independent of \(V \sim \chi^2(\nu)\). For \(\nu = 1\) it recovers the Cauchy distribution; as \(\nu \to \infty\) it approaches \(\mathrm{Normal}(\mu, \sigma)\).

The Probability Density Function (PDF) is:

\[f(x ; \nu, \mu, \sigma) = \frac{\Gamma\bigl(\tfrac{\nu+1}{2}\bigr)} {\sqrt{\nu\pi}\,\Gamma\bigl(\tfrac{\nu}{2}\bigr)\,\sigma} \left(1 + \frac{1}{\nu}\left(\frac{x-\mu}{\sigma}\right)^{2}\right)^{-\frac{\nu+1}{2}}, \quad x \in \mathbb{R}\]

where \(\nu > 0\) is the degrees of freedom (df), \(\mu \in \mathbb{R}\) is the location (loc) and \(\sigma > 0\) is the scale (scale).

Parameters:
  • df – Degrees of freedom \(\nu > 0\).

  • loc – Location \(\mu \in \mathbb{R}\). Defaults to 0.0.

  • scale – Scale \(\sigma > 0\). Defaults to 1.0.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'df': Positive(lower_bound=0.0), 'loc': Real(), 'scale': Positive(lower_bound=0.0)}
support = Real()
reparametrized_params: list[str] = ['df', 'loc', 'scale']
pytree_data_fields: tuple[str, ...] = ('df', 'loc', 'scale', '_chi2')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples via the location-scale representation \(X = \mu + \sigma T\) where \(T = Z\sqrt{\nu / V}\), \(Z \sim \mathrm{Normal}(0, 1)\) is drawn using normal(), and independent of \(V \sim \chi^{2}(\nu)\).

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Real-valued samples from the Student’s t-distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value.

\[\ln f(x ; \nu, \mu, \sigma) = \ln\Gamma\left(\frac{\nu+1}{2}\right) - \ln\Gamma\left(\frac{\nu}{2}\right) - \frac{1}{2}\ln(\nu\pi) - \ln\sigma - \frac{\nu+1}{2} \ln\!\left( 1 + \frac{1}{\nu}\left(\frac{x-\mu}{\sigma}\right)^{2} \right)\]
Parameters:

value – Real-valued point \(x\) at which to evaluate the log PDF.

Returns:

Log probability density under the Student’s t-distribution.

property mean: Array

Mean of the Student’s t-distribution.

\[\begin{split}\mathbb{E}[X] = \begin{cases} \mu & \nu > 1 \\ \infty & \nu \le 1 \end{cases}\end{split}\]

This implementation returns inf when the mean is undefined, matching the implementation of scipy’s t.

property variance: Array

Variance of the Student’s t-distribution.

\[\begin{split}\mathrm{Var}(X) = \begin{cases} \sigma^{2} \dfrac{\nu}{\nu - 2} & \nu > 2 \\ \infty & 1 < \nu \le 2 \\ \text{undefined} & \nu \le 1 \end{cases}\end{split}\]

This implementation returns inf when the variance is infinite and nan when it is undefined.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative Distribution Function (CDF) of the Student’s t-distribution.

With \(Z = (x - \mu)/\sigma\) and \(u = \nu / (\nu + Z^{2})\),

\[F(x ; \nu, \mu, \sigma) = \frac{1}{2} + \frac{1}{2}\,\operatorname{sign}(Z) \left(1 - I_{u}\left(\frac{\nu}{2}, \frac{1}{2}\right)\right)\]

where \(I_{u}\) is the regularized incomplete beta function. Equivalently, \(Z^{2}\) follows an \(F(1, \nu)\) distribution, where \(F(\cdot, \cdot)\) is the Fisher–Snedecor distribution.

Parameters:

value – Real-valued point \(x\) at which to evaluate the CDF.

Returns:

CDF values in \([0, 1]\).

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse CDF (quantile function) of the Student’s t-distribution.

Obtained by inverting the Beta representation used in cdf(): with \(u = I^{-1}_{1 - |1 - 2q|}(\nu/2, 1/2)\),

\[F^{-1}(q ; \nu, \mu, \sigma) = \mu + \sigma\,\operatorname{sign}\left(q - \frac{1}{2}\right) \sqrt{\nu\,\left(\frac{1}{u} - 1\right)}, \quad q \in [0, 1]\]
Parameters:

q – Quantile values in \([0, 1]\).

Returns:

Real-valued quantiles of the Student’s t-distribution at q.

entropy() → Array[source]

Differential entropy of the Student’s t-distribution.

\[H(X) = \frac{\nu+1}{2} \left[ \psi\!\left(\frac{\nu+1}{2}\right) - \psi\!\left(\frac{\nu}{2}\right) \right] + \frac{1}{2}\log\nu + \log B\!\left(\frac{\nu}{2}, \frac{1}{2}\right) + \log\sigma\]

Uniform

class Uniform(low: Array | ndarray | bool | number | bool | int | float | complex = 0.0, high: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Continuous uniform distribution on the interval \([\mathrm{low}, \mathrm{high})\).

The probability density function (PDF) is defined as:

\[f(x; a, b) = \frac{1}{b - a}, \qquad a \le x < b\]

where \(a =\) low and \(b =\) high. Sampling uses uniform(). The support constraint is an interval that depends on low and high.

Parameters:
  • low (ArrayLike) – Lower bound (\(a\)), defaults to 0.

  • high (ArrayLike) – Upper bound (\(b\)), defaults to 1.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'high': Dependent(), 'low': Dependent()}
reparametrized_params: list[str] = ['low', 'high']
pytree_data_fields: tuple[str, ...] = ('low', 'high')
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples via uniform() on \([\mathrm{low}, \mathrm{high})\).

Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability density function.

\[\log f(x; a, b) = -\log(b - a)\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density.

Returns:

Log probability density.

Return type:

jax.Array

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function, clipped to \([0, 1]\).

\[F(x; a, b) = \mathrm{clip}\!\left(\frac{x - a}{b - a}, 0, 1\right)\]
Parameters:

value (ArrayLike) – Value to evaluate.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function (Quantile function).

\[F^{-1}(q; a, b) = a + q\,(b - a)\]
Parameters:

q (ArrayLike) – Probability value in \([0,1]\).

property mean: Array

Calculates the analytical mean.

\[E[X] = (a + b) / 2\]
property variance: Array

Calculates the analytical variance.

\[\mathrm{Var}(X) = (b - a)^2 / 12\]
classmethod infer_shapes(low: tuple[int, ...] = (), high: tuple[int, ...] = ()) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

entropy() → Array[source]

Differential entropy of the Uniform distribution.

\[H(X) = \log(b - a)\]

Weibull

class Weibull(scale: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Weibull distribution parameterized by scale (scale) and shape (concentration).

The probability density function (PDF) is defined as:

\[f(x; \lambda, k) = \frac{k}{\lambda} \left(\frac{x}{\lambda}\right)^{k - 1} \exp\left(-\left(\frac{x}{\lambda}\right)^{k}\right)\]

where \(x > 0\), \(\lambda > 0\) is the scale and \(k > 0\) is the shape. The cumulative distribution function (CDF) is \(F(x) = 1 - \exp(-(x / \lambda)^{k})\).

For \(k = 1\) this reduces to \(\mathrm{Exponential}(1 / \lambda)\). The hazard rate \(h(x) = (k / \lambda)(x / \lambda)^{k - 1}\) is decreasing for \(k < 1\) and increasing for \(k > 1\).

The mean is \(\lambda \, \Gamma(1 + 1/k)\) and the variance is \(\lambda^2 \left[\Gamma(1 + 2/k) - \Gamma(1 + 1/k)^2\right]\).

Samples are drawn with jax.random.weibull_min().

Parameters:
  • scale (ArrayLike) – Scale parameter (\(\lambda\)).

  • concentration (ArrayLike) – Shape parameter (\(k\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'scale': Positive(lower_bound=0.0)}
support = Positive(lower_bound=0.0)
reparametrized_params: list[str] = ['scale', 'concentration']
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

entropy() → Array[source]

Returns the entropy of the distribution.

Wishart

class Wishart(concentration: Array | ndarray | bool | number | bool | int | float | complex, scale_matrix: Array | None = None, rate_matrix: Array | None = None, scale_tril: Array | None = None, *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Wishart distribution for covariance matrices.

The Wishart distribution is the multivariate generalization of the Gamma distribution and the conjugate prior for the precision matrix of a multivariate normal distribution. If \(\mathbf{X} \sim W(\mathbf{V}, \nu)\), its density over the \(p \times p\) positive definite matrix \(\mathbf{X}\) is

\[p(\mathbf{X} \mid \mathbf{V}, \nu) = \frac{|\mathbf{X}|^{(\nu - p - 1)/2} \exp\left(-\frac{1}{2} \mathrm{tr}(\mathbf{V}^{-1} \mathbf{X})\right)} {2^{\nu p/2} |\mathbf{V}|^{\nu/2} \Gamma_p(\nu/2)},\]

where \(\nu > p - 1\) is the concentration (degrees of freedom), \(\mathbf{V}\) is the positive definite scale matrix and \(\Gamma_p\) is the multivariate gamma function. The rate matrix is \(\mathbf{V}^{-1}\).

The mean and the elementwise variance are

\[\mathbb{E}[\mathbf{X}] = \nu \mathbf{V}, \qquad \mathrm{Var}[X_{ij}] = \nu \left(V_{ij}^2 + V_{ii} V_{jj}\right).\]
Parameters:
  • concentration – Degrees of freedom \(\nu\), analogous to the concentration of a Gamma distribution. Must be greater than \(p - 1\), where \(p\) is the dimension of the scale matrix.

  • scale_matrix – Scale matrix analogous to the inverse rate of a Gamma distribution.

  • rate_matrix – Rate matrix analogous to the rate of a Gamma distribution.

  • scale_tril – Cholesky decomposition of the scale_matrix.

arg_constraints: dict[str, Any] = {'concentration': Dependent(), 'rate_matrix': PositiveDefinite(), 'scale_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
support = PositiveDefinite()
reparametrized_params: list[str] = ['scale_matrix', 'rate_matrix', 'scale_tril']
base_dist: WishartCholesky
concentration()[source]
scale_matrix()[source]
rate_matrix()[source]
scale_tril()[source]
mean() → Array[source]

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

classmethod infer_shapes(concentration=(), scale_matrix=None, rate_matrix=None, scale_tril=None)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

entropy() → Array[source]

Returns the entropy of the distribution.

WishartCholesky

class WishartCholesky(concentration: Array | ndarray | bool | number | bool | int | float | complex, scale_matrix: Array | None = None, rate_matrix: Array | None = None, scale_tril: Array | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Cholesky factor of a Wishart distribution for covariance matrices.

If \(\mathbf{X} \sim W(\mathbf{V}, \nu)\) is a Wishart distributed \(p \times p\) positive definite matrix, this distribution describes its lower triangular Cholesky factor \(\mathbf{L}\) with positive diagonal, such that \(\mathbf{X} = \mathbf{L} \mathbf{L}^\top\). By the change of variables \(\mathbf{X} = \mathbf{L} \mathbf{L}^\top\), with Jacobian \(|\partial \mathbf{X} / \partial \mathbf{L}| = 2^p \prod_{i=1}^p L_{ii}^{p - i + 1}\), its density is

\[p(\mathbf{L} \mid \mathbf{V}, \nu) = \frac{|\mathbf{L} \mathbf{L}^\top|^{(\nu - p - 1)/2} \exp\left(-\frac{1}{2} \mathrm{tr}(\mathbf{V}^{-1} \mathbf{L} \mathbf{L}^\top)\right)} {2^{\nu p/2} |\mathbf{V}|^{\nu/2} \Gamma_p(\nu/2)} \, 2^p \prod_{i=1}^p L_{ii}^{p - i + 1},\]

where \(\nu > p - 1\) is the concentration (degrees of freedom), \(\mathbf{V}\) is the positive definite scale matrix and \(\Gamma_p\) is the multivariate gamma function. The rate matrix is \(\mathbf{V}^{-1}\).

Samples are drawn with the Bartlett decomposition, \(\mathbf{L} = \mathbf{L}_V \mathbf{A}\), where \(\mathbf{L}_V\) is scale_tril, \(A_{ii} \sim \sqrt{\chi^2_{\nu - i + 1}}\) and \(A_{ij} \sim \mathcal{N}(0, 1)\) for \(i > j\).

Parameters:
  • concentration – Degrees of freedom \(\nu\), analogous to the concentration of a Gamma distribution. Must be greater than \(p - 1\), where \(p\) is the dimension of the scale matrix.

  • scale_matrix – Scale matrix analogous to the inverse rate of a Gamma distribution.

  • rate_matrix – Rate matrix analogous to the rate of a Gamma distribution.

  • scale_tril – Cholesky decomposition of the scale_matrix.

arg_constraints: dict[str, Any] = {'concentration': Dependent(), 'rate_matrix': PositiveDefinite(), 'scale_matrix': PositiveDefinite(), 'scale_tril': LowerCholesky()}
support = LowerCholesky()
reparametrized_params: list[str] = ['scale_matrix', 'rate_matrix', 'scale_tril']
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

scale_matrix()[source]
rate_matrix()[source]
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

mean() → Array[source]

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

classmethod infer_shapes(concentration: tuple[int, ...] = (), scale_matrix: tuple[int, ...] | None = None, rate_matrix: tuple[int, ...] | None = None, scale_tril: tuple[int, ...] | None = None)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

ZeroSumNormal

class ZeroSumNormal(scale: Array | ndarray | bool | number | bool | int | float | complex, event_shape: tuple[int, ...], *, validate_args: bool | None = None)[source]

Bases: TransformedDistribution

Zero Sum Normal distribution adapted from PyMC [1] as described in [2,3]. All axes in event_shape are constrained to sum to zero. For example, event_shape=(3, 4) constrains both rows and columns to sum to zero.

For a single constrained axis, event_shape=(n,), and scalar scale \(\sigma\), the distribution is

\[ZSN(\sigma) = N(0, \sigma^2 (I_n - \tfrac{1}{n}J_n)).\]

Here \(n\) is the length of the constrained axis, and \(I_n\) and \(J_n\) are the \(n \times n\) identity and all-ones matrices. Each entry has variance \(\sigma^2(1 - 1/n)\).

Parameters:
  • scale (array_like) – Standard deviation of the underlying normal distribution before the zerosum constraint is enforced.

  • event_shape (tuple) – The event shape of the distribution, the axes of which get constrained to sum to zero.

For event_shape=(4,), there is one constrained axis of length four:

>>> from numpy.testing import assert_allclose
>>> import numpyro.distributions as dist
>>> d = dist.ZeroSumNormal(1.0, event_shape=(4,))
>>> assert_allclose(d.variance, [0.75, 0.75, 0.75, 0.75])

Example:

>>> from numpy.testing import assert_allclose
>>> from jax import random
>>> import jax.numpy as jnp
>>> import numpyro
>>> import numpyro.distributions as dist
>>> from numpyro.infer import MCMC, NUTS

>>> N = 1000
>>> n_categories = 20
>>> rng_key = random.key(0)
>>> key1, key2, key3 = random.split(rng_key, 3)
>>> category_ind = random.choice(key1, jnp.arange(n_categories), shape=(N,))
>>> beta = random.normal(key2, shape=(n_categories,))
>>> beta -= beta.mean(-1)
>>> y = 5 + beta[category_ind] + random.normal(key3, shape=(N,))

>>> def model(category_ind, y): # category_ind is an indexed categorical variable with 20 categories
...     N = len(category_ind)
...     alpha = numpyro.sample("alpha", dist.Normal(0, 2.5))
...     beta = numpyro.sample("beta", dist.ZeroSumNormal(1, event_shape=(n_categories,)))
...     sigma =  numpyro.sample("sigma", dist.Exponential(1))
...     with numpyro.plate("observations", N):
...         mu = alpha + beta[category_ind]
...         obs = numpyro.sample("obs", dist.Normal(mu, sigma), obs=y)
...     return obs

>>> nuts_kernel = NUTS(model=model, target_accept_prob=0.9)
>>> mcmc = MCMC(
...     sampler=nuts_kernel,
...     num_samples=1_000, num_warmup=1_000, num_chains=4
... )
>>> mcmc.run(random.key(0), category_ind=category_ind, y=y)
>>> posterior_samples = mcmc.get_samples()
>>> # Confirm everything along last axis sums to zero
>>> assert_allclose(posterior_samples['beta'].sum(-1), 0, atol=1e-3)

References [1] https://github.com/pymc-devs/pymc/blob/6252d2e58dc211c913ee2e652a4058d271d48bbd/pymc/distributions/multivariate.py#L2637 [2] https://www.pymc.io/projects/docs/en/stable/api/distributions/generated/pymc.ZeroSumNormal.html [3] https://learnbayesstats.com/episode/74-optimizing-nuts-developing-zerosumnormal-distribution-adrian-seyboldt/

arg_constraints: dict[str, Any] = {'scale': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['scale']
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

Discrete Distributions

Bernoulli

Bernoulli(probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None) → BernoulliProbs | BernoulliLogits[source]

Factory function to create a Bernoulli distribution instance from either probability or log-odds parameterization.

Parameters:
  • probs – The success probability parameter in the unit interval \([0, 1]\), defaults to None

  • logits – The log-odds parameter, defaults to None

  • validate_args – Optional toggle to enforce domain constraints during graph construction. Default is None.

Returns:

The created Bernoulli distribution instance.

BernoulliLogits

class BernoulliLogits(logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Bernoulli discrete random variable parameterized by log-odds (logits).

The Probability Mass Function (PMF) of the Bernoulli distribution is:

\[P(X = k | \alpha) = \sigma(\alpha)^k (1 - \sigma(\alpha))^{1-k}, \quad k \in \{0, 1\}\]

Where \(\alpha = \text{logits}\) is the log-odds parameter and \(\sigma(\alpha) = 1/(1 + \exp{(-\alpha)})\) is the sigmoid function.

Parameters:
  • logits – Log-odds parameter \(\alpha \in [-\infty, \infty]\); \(\mp\infty\) denote \(p = 0\) and \(p = 1\).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'logits': ExtendedReal()}
support = Boolean()

The support of the Bernoulli distribution is the set of binary outcomes \(\{0, 1\}\).

has_enumerate_support: bool = True
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Bernoulli distribution.

The method first converts logits to probabilities via the sigmoid function (accessed via the lazy property probs), then invokes bernoulli() for sampling.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Binary-valued samples (0 or 1) drawn from the Bernoulli distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified binary configurations.

The log probability mass function leverages the numerically-stable binary_cross_entropy_with_logits() primitive, which computes the Bernoulli negative log-likelihood directly in log-odds space:

\[\ln P(X = k | \alpha) = -\mathrm{BCEWithLogits}(\alpha, k) = k \ln(\sigma(\alpha)) + (1-k) \ln(1 - \sigma(\alpha))\]

This formulation avoids explicit exponential evaluation for large \(|\alpha|\), protecting against overflow (\(e^\alpha \to \infty\) for \(\alpha \gg 0\)) and underflow (\(e^{-\alpha} \to 0\) for \(\alpha \ll -0\)).

Parameters:

value – Binary observation(s) to score (\(k \in \{0, 1\}\)).

Returns:

Log probability scores evaluated under the Bernoulli PMF.

probs() → Array[source]

The success probability parameter of the Bernoulli distribution is given by the sigmoid of the log-odds parameter:

\[p = \sigma(\alpha) = \frac{1}{1 + e^{-\alpha}}\]
property mean: Array

The mean of the Bernoulli distribution is given by the sigmoid of the log-odds parameter:

\[E[X] = \sigma(\alpha) = \frac{1}{1 + e^{-\alpha}}\]
property variance: Array

The variance of the Bernoulli distribution is given by:

\[\mathrm{Var}[X] = \sigma(\alpha) (1 - \sigma(\alpha))\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the cumulative distribution function (CDF) of the Bernoulli distribution.

\[\begin{split}F(x) = P(X \le x) = \begin{cases} 0 & x < 0, \\ \sigma(-\alpha) & 0 \le x < 1, \\ 1 & x \ge 1. \end{cases}\end{split}\]

\(P(X = 0) = 1 - \sigma(\alpha)\) is evaluated as \(\sigma(-\alpha)\), which keeps full relative precision when \(\sigma(\alpha)\) rounds to 1.

Parameters:

value – Point(s) at which to evaluate the CDF.

Returns:

The CDF evaluated at value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the inverse cumulative distribution function (quantile function) of the Bernoulli distribution.

\[\begin{split}F^{-1}(u) = \min\{k \in \{0, 1\} : F(k) \ge u\} = \begin{cases} 0 & u \le \sigma(-\alpha), \\ 1 & u > \sigma(-\alpha). \end{cases}\end{split}\]

Levels outside \([0, 1]\) are clamped to the support, and \(u = 0\) maps to 0, the lowest support value, even when \(\alpha = \infty\).

Parameters:

q – Quantile level(s) \(u \in [0, 1]\).

Returns:

The inverse CDF evaluated at q.

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

entropy() → Array[source]

The entropy of the Bernoulli distribution is given by:

\[H[X] = -p \ln p - (1-p) \ln (1-p)\]

where \(p = \sigma(\alpha)\) is the mean of the distribution.

It is evaluated as \(p\,\mathrm{softplus}(-\alpha) + (1-p)\,\mathrm{softplus}(\alpha)\), dropping each term where its probability is zero, which is exact for all \(\alpha\) including \(\pm\infty\).

BernoulliProbs

class BernoulliProbs(probs: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Bernoulli discrete random variable parameterizing the probability of a binary outcome.

The Probability Mass Function (PMF) of the Bernoulli distribution is defined as:

\[P(X = k | p) = p^k (1 - p)^{1-k}, \quad k \in \{0, 1\}\]

Where, \(p\) represents the success probability parameter (probs), \(k\) represents the observed binary outcome (value). The support domain is \(k \in \{0, 1\}\).

Parameters:
  • probs – Success probability in the interval \([0, 1]\).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'probs': UnitInterval(lower_bound=0.0, upper_bound=1.0)}
support = Boolean()

The support of the Bernoulli distribution is the set of binary outcomes \(\{0, 1\}\).

has_enumerate_support: bool = True
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Bernoulli distribution.

This method invokes bernoulli() directly, which generates binary samples from the Bernoulli parametrization. Samples are mapped across the specified batch dimensions and sample dimensions via shape broadcasting.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Binary-valued samples (0 or 1) drawn from the Bernoulli distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified binary configurations.

\[\ln P(X=k | p) = k\ln(p) + (1-k)\ln(1-p)\]

The log probability mass function is evaluated using numerically-stable log-space operations. Rather than computing \(\ln(p)\) and \(\ln(1-p)\) directly from clamped probabilities, this implementation employs the primitives xlogy() and xlog1py(), which handle edge cases gracefully:

  • When \(p = 0\) or \(p = 1\), the log-probability computation is protected from logarithmic singularities via masking.

  • The clamped probability values prevent numerical underflow in extreme configurations.

Parameters:

value – Binary observation(s) to score (\(k \in \{0, 1\}\)).

Returns:

Log probability scores evaluated under the Bernoulli PMF.

logits() → Array[source]

The log-odds (logits) parameter of the Bernoulli distribution is given by the logit transformation of the success probability:

\[\alpha = \text{logit}(p) = \ln\left(\frac{p}{1-p}\right)\]
property mean: Array

The mean of the Bernoulli distribution is given by the success probability parameter:

\[E[X] = p\]
Returns:

The mean of the Bernoulli distribution, which is equal to the success probability probs.

property variance: Array

The variance of the Bernoulli distribution is given by:

\[\mathrm{Var}[X] = p (1 - p)\]
Returns:

The variance of the Bernoulli distribution, which is the product of the success probability and its complement.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the cumulative distribution function (CDF) of the Bernoulli distribution.

\[\begin{split}F(x) = P(X \le x) = \begin{cases} 0 & x < 0, \\ 1 - p & 0 \le x < 1, \\ 1 & x \ge 1. \end{cases}\end{split}\]
Parameters:

value – Point(s) at which to evaluate the CDF.

Returns:

The CDF evaluated at value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the inverse cumulative distribution function (quantile function) of the Bernoulli distribution.

\[\begin{split}F^{-1}(u) = \min\{k \in \{0, 1\} : F(k) \ge u\} = \begin{cases} 0 & u \le 1 - p, \\ 1 & u > 1 - p. \end{cases}\end{split}\]

Levels outside \([0, 1]\) are clamped to the support, and \(u = 0\) maps to 0, the lowest support value, even when \(p = 1\).

Parameters:

q – Quantile level(s) \(u \in [0, 1]\).

Returns:

The inverse CDF evaluated at q.

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

entropy() → Array[source]

The entropy of the Bernoulli distribution is given by:

\[H[X] = -p \ln p - (1-p) \ln (1-p)\]

BetaBinomial

class BetaBinomial(concentration1: Array | ndarray | bool | number | bool | int | float | complex, concentration0: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Beta-Binomial compound distribution: the probability of success (probs for the Binomial distribution) is unknown and randomly drawn from a Beta distribution prior to a certain number of Bernoulli trials given by total_count. Marginalizing out the success probability yields a discrete distribution on \(\{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:

\[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 \(\alpha\) is concentration1, \(\beta\) is concentration0, \(n\) is total_count, and \(\mathrm{B}\) is the beta function.

Parameters:
  • concentration1 (numpy.ndarray) – 1st concentration parameter (alpha) for the Beta distribution.

  • concentration0 (numpy.ndarray) – 2nd concentration parameter (beta) for the Beta distribution.

  • total_count (numpy.ndarray) – number of Bernoulli trials.

arg_constraints: dict[str, Any] = {'concentration0': Positive(lower_bound=0.0), 'concentration1': Positive(lower_bound=0.0), 'total_count': IntegerNonnegative(lower_bound=0)}
has_enumerate_support: bool = True
enumerate_support(expand: bool = True) → Array

Returns an array with shape len(support) x batch_shape containing all values in the support.

pytree_data_fields: tuple[str, ...] = ('concentration1', 'concentration0', 'total_count', '_beta')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

If \(X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)\), then the sampling procedure is:

\[\begin{split}\begin{align*} p &\sim \mathrm{Beta}(\alpha, \beta) \\ X \mid p &\sim \mathrm{Binomial}(n, p) \end{align*}\end{split}\]

It uses Beta to generate samples from the Beta distribution and BinomialProbs to generate samples from the Binomial distribution.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer-valued samples in \(\{0, 1, \dots, n\}\) drawn from the Beta-Binomial distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)\), then the log probability mass function is:

\[\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 betaln().

Parameters:

value – Number of successes \(k \in \{0, 1, \dots, n\}\) to score.

Returns:

Log probability scores evaluated under the Beta-Binomial PMF.

property mean: Array

If \(X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)\), then the mean is:

\[\mathbb{E}[X] = \frac{n\alpha}{\alpha + \beta}\]
property variance: Array

If \(X \sim \mathrm{BetaBinomial}(\alpha, \beta, n)\), then the variance is:

\[\mathrm{Var}[X] = \frac{n\,\alpha\beta\,(\alpha + \beta + n)} {(\alpha + \beta)^{2}\,(\alpha + \beta + 1)}\]
property support: Constraint

The support of the Beta-Binomial distribution is the set of integers \(\{0, 1, \dots, n\}\), where \(n\) is total_count.

BetaNegativeBinomial

class BetaNegativeBinomial(concentration1: Array | ndarray | bool | number | bool | int | float | complex, concentration0: Array | ndarray | bool | number | bool | int | float | complex, n: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Compound distribution comprising of a beta-negative-binomial pair. The probs parameter for the NegativeBinomialProbs distribution is unknown and randomly drawn from a 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.

Parameters:
  • concentration1 (numpy.ndarray) – 1st concentration parameter (alpha) for the Beta distribution.

  • concentration0 (numpy.ndarray) – 2nd concentration parameter (beta) for the Beta distribution.

  • n (numpy.ndarray) – 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: dict[str, Any] = {'concentration0': Positive(lower_bound=0.0), 'concentration1': Positive(lower_bound=0.0), 'n': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_data_fields: tuple[str, ...] = ('concentration1', 'concentration0', 'n', '_beta')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

If \(X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)\), then the sampling procedure is:

\[\begin{split}\begin{align*} p &\sim \mathrm{Beta}(\alpha, \beta) \\ X \mid p &\sim \mathrm{NegativeBinomial}(n, p) \end{align*}\end{split}\]

It uses Beta to generate samples from the Beta distribution and NegativeBinomialProbs to generate samples from the Negative Binomial distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)\), then the log probability mass function is:

\[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.

property mean: Array

If \(X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)\) and \(\beta > 1\), then the mean is:

\[\mathbb{E}[X] = \frac{n\alpha}{\beta - 1},\]

otherwise, the its undefined.

property variance: Array

If \(X \sim \mathrm{BetaNegativeBinomial}(\alpha, \beta, n)\) and \(\beta > 2\), then the variance is:

\[\mathrm{Var}[X] = \frac{n\alpha (n + \beta - 1)(\alpha + \beta - 1)}{(\beta - 1)^2 \cdot (\beta - 2)},\]

otherwise, the its undefined.

Binomial

Binomial(total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None) → BinomialProbs | BinomialLogits[source]

Factory function to create a Binomial distribution instance from either probability or log-odds parameterization.

Parameters:
  • total_count – Number of trials (non-negative integer), defaults to 1

  • probs – The success probability parameter in the unit interval \([0, 1]\), defaults to None

  • logits – The log-odds parameter, defaults to None

  • validate_args – Optional toggle to enforce simplex constraint during graph construction. Default is None

Returns:

A Binomial distribution instance corresponding to the specified parameterization.

BinomialLogits

class BinomialLogits(logits: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Binomial discrete random variable parameterized by log-odds (logits).

The Probability Mass Function (PMF) of the Binomial distribution is:

\[P(X = k | n, \alpha) = \binom{n}{k} \sigma(\alpha)^k (1 - \sigma(\alpha))^{n-k}\]

Where \(\alpha = \text{logits}\) and \(\sigma(\alpha) = 1/(1 + \exp(-\alpha))\).

Parameters:
  • logits – Log-odds parameter in \([-\infty, \infty]\); \(\mp\infty\) denote \(p = 0\) and \(p = 1\).

  • total_count – Number of trials (non-negative integer).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'logits': ExtendedReal(), 'total_count': IntegerNonnegative(lower_bound=0)}
has_enumerate_support: bool = True
enumerate_support(expand: bool = True) → Array

Returns an array with shape len(support) x batch_shape containing all values in the support.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Binomial distribution.

The method first converts logits to probabilities via the sigmoid function (via the lazy property probs), then uses the internal binomial() utility for sampling. This maintains numerical stability across extreme log-odds values.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Non-negative integer samples representing success counts.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified count configurations.

The log probability mass function is computed in log-odds space with \(\ln p = -\mathrm{softplus}(-\alpha)\) and \(\ln(1-p) = -\mathrm{softplus}(\alpha)\), which are exact at \(\alpha = \pm\infty\):

\[\ln P(X = k | n, \alpha) = \ln \binom{n}{k} + k \ln p + (n - k) \ln(1-p)\]

A term whose count is zero is dropped rather than evaluated as \(0 \cdot \infty\).

The binomial coefficient in log-space is computed using the log-gamma function:

\[\ln \binom{n}{k} = \ln\Gamma(n + 1) - \ln\Gamma(k + 1) - \ln\Gamma(n - k + 1)\]

This approach using gammaln() avoids computing factorials explicitly.

Parameters:

value – Count observation(s) in the range \([0, n]\).

Returns:

Log probability scores evaluated under the Binomial PMF.

probs() → Array[source]

The success probability per trial of the Binomial distribution is given by the sigmoid of the log-odds parameter:

\[p = \sigma(\alpha) = \frac{1}{1 + e^{-\alpha}}\]
property mean: Array

The mean of the Binomial distribution is given by:

\[E[X] = n \sigma(\alpha)\]
property variance: Array

The variance of the Binomial distribution is given by:

\[\mathrm{Var}[X] = n \sigma(\alpha) (1 - \sigma(\alpha))\]
property support: Constraint

The support of the Binomial distribution is the set of integer counts from 0 to the total count.

BinomialProbs

class BinomialProbs(probs: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Binomial discrete random variable parameterizing the count of successes in repeated trials.

The Probability Mass Function (PMF) of the Binomial distribution is defined as:

\[P(X = k | n, p) = \binom{n}{k} p^k (1 - p)^{n-k}, \quad k \in \{0, 1, \dots, n\}\]

Where, \(n\) is the number of trials (total_count), \(p\) is the success probability per trial (probs), \(k\) is the observed count of successes (value).

Parameters:
  • probs – Success probability per trial in \([0, 1]\).

  • total_count – Number of trials (non-negative integer).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'probs': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'total_count': IntegerNonnegative(lower_bound=0)}
has_enumerate_support: bool = True
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Binomial distribution.

This method uses the internal binomial() utility function to generate count samples.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Non-negative integer samples representing success counts.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified count configurations.

The log probability mass function is fully evaluated in log-space to prevent factorial overflow and underflow:

\[\ln P(X = k | n, p) = \ln \binom{n}{k} + k \ln p + (n-k) \log(1-p)\]

The binomial coefficient in log-space is computed using the log-gamma function:

\[\ln \binom{n}{k} = \ln\Gamma(n + 1) - \ln\Gamma(k + 1) - \ln\Gamma(n - k + 1)\]

This approach using gammaln() avoids computing factorials explicitly. The probability terms are evaluated using xlogy() and xlog1py() to handle boundary cases gracefully (\(p = 0\), \(p = 1\), etc.).

Parameters:

value – Count observation(s) in the range \([0, n]\).

Returns:

Log probability scores evaluated under the Binomial PMF.

logits() → Array[source]

The log-odds (logits) parameter of the Binomial distribution is given by the logit transformation of the success probability:

\[\alpha = \text{logit}(p) = \ln\left(\frac{p}{1-p}\right)\]
property mean: Array

The mean of the Binomial distribution is given by:

\[E[X] = n p\]
property variance: Array

The variance of the Binomial distribution is given by:

\[\mathrm{Var}[X] = n p (1 - p)\]
property support: Constraint

The support of the Binomial distribution is the set of integer counts from 0 to the total count.

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

Categorical

Categorical(probs=None, logits=None, *, validate_args: bool | None = None)[source]

Create a Categorical distribution over \(K\) discrete outcomes.

For a category probability vector \(\mathbf{p}\), the probability mass function is

\[P(X = k \mid \mathbf{p}) = p_k, \quad k \in \{0, 1, \dots, K-1\}, \quad \sum_{k=0}^{K-1} p_k = 1.\]

Alternatively, unnormalized logits \(\boldsymbol{\alpha}\) define the probabilities through a softmax:

\[P(X = k \mid \boldsymbol{\alpha}) = \frac{\exp(\alpha_k)}{\sum_{j=0}^{K-1} \exp(\alpha_j)}, \quad k \in \{0, 1, \dots, K-1\}.\]

The trailing dimension of either parameter indexes the \(K\) categories; preceding dimensions are batch dimensions. Exactly one of probs and logits must be supplied. The factory returns a CategoricalProbs distribution when probs is supplied and a CategoricalLogits distribution when logits is supplied.

Parameters:
  • probs – Category probability vectors on the simplex, with categories on the trailing dimension.

  • logits – Real-valued unnormalized log probabilities, with categories on the trailing dimension.

  • validate_args – If True, enforce parameter constraints during initialization.

Returns:

A Categorical distribution parameterized by probs or logits.

Raises:

ValueError – If both parameterizations or neither is supplied.

CategoricalLogits

class CategoricalLogits(logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Categorical discrete random variable over \(K\) mutually exclusive outcomes, parameterized by unnormalized log-probabilities (logits).

The Probability Mass Function (PMF) of the Categorical distribution is defined, via the softmax transformation of the logits, as:

\[P(X = k \mid \boldsymbol{\alpha}) = \frac{\exp(\alpha_k)}{\sum_{j=0}^{K-1} \exp(\alpha_j)}, \quad k \in \{0, 1, \dots, K-1\}\]

Where, \(\boldsymbol{\alpha} = (\alpha_0, \alpha_1, \dots, \alpha_{K-1})\) is the real-valued logits vector (logits), \(K\) is the number of categories (the size of the trailing dimension of logits), and \(k\) is the observed category index (value). The support domain is \(k \in \{0, 1, \dots, K-1\}\).

Parameters:
  • logits – Logits vector; the trailing dimension indexes the \(K\) categories. Logits are unnormalized and converted to probabilities via the softmax function. A \(-\infty\) entry is a zero-probability category; \(+\infty\) is rejected since the softmax is then undefined.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'logits': SoftmaxLogits()}
has_enumerate_support: bool = True
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Categorical distribution.

This method invokes categorical() directly, which samples in logit-space using the Gumbel-max trick and therefore avoids materializing the softmax-normalized probabilities.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer-valued samples in \(\{0, 1, \dots, K-1\}\) drawn from the Categorical distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified category indices.

\[\ln P(X = k \mid \boldsymbol{\alpha}) = \alpha_k - \ln\!\sum_{j=0}^{K-1} \exp(\alpha_j)\]

The normalizing log-partition is computed via logsumexp(), which uses the standard max-subtraction trick to guarantee numerical stability in the presence of large or widely-spread logit magnitudes. After normalization, the relevant log-probability is gathered with take_along_axis().

Parameters:

value – Category index/indices to score (\(k \in \{0, 1, \dots, K-1\}\)).

Returns:

Log probability scores evaluated under the Categorical PMF.

probs() → Array[source]

The probability vector of the Categorical distribution is given by the softmax of the logits:

\[p_k = \frac{\exp(\alpha_k)}{\sum_{j=0}^{K-1} \exp(\alpha_j)}, \quad k \in \{0, 1, \dots, K-1\}\]
property mean: Array

The mean of a Categorical distribution over arbitrary unordered categories is not well-defined. This property therefore returns NaN.

Returns:

An array of NaNs with shape equal to batch_shape.

property variance: Array

The variance of a Categorical distribution over arbitrary unordered categories is not well-defined. This property therefore returns NaN.

Returns:

An array of NaNs with shape equal to batch_shape.

property support: Constraint

The support of the Categorical distribution is the set of integers \(\{0, 1, \dots, K-1\}\), where \(K\) is the number of categories inferred from the trailing dimension of logits.

enumerate_support(expand: bool = True) → Array[source]

Enumerate all values in the support of the Categorical distribution.

Parameters:

expand – Whether to broadcast the enumerated values across the batch shape. Default is True.

Returns:

An array of integer category indices \(\{0, 1, \dots, K-1\}\), optionally broadcast across the batch dimensions.

entropy() → Array[source]

The entropy of the Categorical distribution is given by:

\[H[X] = -\sum_{k=0}^{K-1} p_k \ln p_k, \qquad \ln p_k = \alpha_k - \ln\!\sum_{j=0}^{K-1} \exp(\alpha_j)\]

where \(p_k = \mathrm{softmax}(\boldsymbol{\alpha})_k\). The log-partition term uses logsumexp() for stability, and a zero-probability category contributes \(0 \ln 0 = 0\).

Returns:

The entropy of the Categorical distribution.

CategoricalProbs

class CategoricalProbs(probs: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Categorical discrete random variable over \(K\) mutually exclusive outcomes, parameterized by a probability vector on the simplex.

The Probability Mass Function (PMF) of the Categorical distribution is defined as:

\[P(X = k \mid \mathbf{p}) = p_k, \quad k \in \{0, 1, \dots, K-1\}\]

where the probability vector \(\mathbf{p} = (p_0, p_1, \dots, p_{K-1})\) satisfies \(p_k \ge 0\) and \(\sum_{k=0}^{K-1} p_k = 1\).

Where, \(\mathbf{p}\) represents the category probability vector (probs), \(K\) is the number of categories (the size of the trailing dimension of probs), and \(k\) is the observed category index (value). The support domain is \(k \in \{0, 1, \dots, K-1\}\).

Parameters:
  • probs – Category probability vector on the simplex; the trailing dimension indexes the \(K\) categories and must sum to one.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'probs': Simplex()}
has_enumerate_support: bool = True
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Categorical distribution.

This method delegates to categorical(), which internally relies on categorical() over the log-probabilities of probs.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer-valued samples in \(\{0, 1, \dots, K-1\}\) drawn from the Categorical distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified category indices.

\[\ln P(X = k \mid \mathbf{p}) = \ln p_k\]

The implementation gathers the log-probabilities from logits (which are already normalized log-probabilities computed from probs) at the positions indicated by value using take_along_axis().

Parameters:

value – Category index/indices to score (\(k \in \{0, 1, \dots, K-1\}\)).

Returns:

Log probability scores evaluated under the Categorical PMF.

logits() → Array[source]

The log-probability (logits) parameter of the Categorical distribution is the (already-normalized) log of the category probabilities:

\[\alpha_k = \ln p_k, \quad k \in \{0, 1, \dots, K-1\}\]
property mean: Array

The mean of a Categorical distribution over arbitrary unordered categories is not well-defined. This property therefore returns NaN.

Returns:

An array of NaNs with shape equal to batch_shape.

property variance: Array

The variance of a Categorical distribution over arbitrary unordered categories is not well-defined. This property therefore returns NaN.

Returns:

An array of NaNs with shape equal to batch_shape.

property support: Constraint

The support of the Categorical distribution is the set of integers \(\{0, 1, \dots, K-1\}\), where \(K\) is the number of categories inferred from the trailing dimension of probs.

enumerate_support(expand: bool = True) → Array[source]

Enumerate all values in the support of the Categorical distribution.

Parameters:

expand – Whether to broadcast the enumerated values across the batch shape. Default is True.

Returns:

An array of integer category indices \(\{0, 1, \dots, K-1\}\), optionally broadcast across the batch dimensions.

entropy() → Array[source]

The entropy of the Categorical distribution is given by:

\[H[X] = -\sum_{k=0}^{K-1} p_k \ln p_k\]
Returns:

The entropy of the Categorical distribution.

DirichletMultinomial

class DirichletMultinomial(concentration: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, total_count_max: int | None = None, validate_args: bool | None = None)[source]

Bases: Distribution

A Dirichlet-Multinomial compound distribution: the class probabilities (probs for the Multinomial distribution) are unknown and randomly drawn from a 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:

\[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 \(\boldsymbol{\alpha} = (\alpha_0, \alpha_1, \dots, \alpha_{K-1})\) is the concentration vector (concentration), \(n\) is the number of trials (total_count), \(\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 \(\mathbf{x}\) satisfies \(\sum_{k=0}^{K-1} x_k = n\).

Parameters:
  • concentration (numpy.ndarray) – concentration parameter (alpha) for the Dirichlet distribution.

  • total_count (numpy.ndarray) – number of Categorical trials.

  • total_count_max (int) – the maximum number of trials, i.e. max(total_count)

arg_constraints: dict[str, Any] = {'concentration': IndependentConstraint(Positive(lower_bound=0.0), 1), 'total_count': IntegerNonnegative(lower_bound=0)}
pytree_data_fields: tuple[str, ...] = ('concentration', '_dirichlet')
pytree_aux_fields: tuple[str, ...] = ('total_count', 'total_count_max')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

If \(X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)\), then the sampling procedure is:

\[\begin{split}\begin{align*} \mathbf{p} &\sim \mathrm{Dirichlet}(\boldsymbol{\alpha}) \\ X \mid \mathbf{p} &\sim \mathrm{Multinomial}(n, \mathbf{p}) \end{align*}\end{split}\]

It uses Dirichlet to generate samples from the Dirichlet distribution and MultinomialProbs to generate samples from the Multinomial distribution.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer count vectors \(\mathbf{x}\) with \(\sum_{k=0}^{K-1} x_k =\) total_count, drawn from the Dirichlet-Multinomial distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)\), then the log probability mass function is:

\[\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 \(n\) is total_count and \(A = \sum_{k=0}^{K-1} \alpha_k\). To ensure differentiability, the factorial terms are computed using gammaln().

Parameters:

value – Count vector \(\mathbf{x}\) whose last dimension has size \(K\) and sums to total_count.

Returns:

Log probability scores evaluated under the Dirichlet-Multinomial PMF.

property mean: Array

If \(X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)\), then the mean is:

\[\mathbb{E}[X_k] = n\,\frac{\alpha_k}{A}, \quad k \in \{0, 1, \dots, K-1\}\]

where \(A = \sum_{k=0}^{K-1} \alpha_k\).

property variance: Array

If \(X \sim \mathrm{DirichletMultinomial}(\boldsymbol{\alpha}, n)\), then the variance is:

\[\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 \(A = \sum_{k=0}^{K-1} \alpha_k\).

property support: Constraint

The support of the Dirichlet-Multinomial distribution is the set of count vectors \(\mathbf{x} \in \{0, 1, \dots, n\}^K\) whose entries sum to total_count \(n\).

classmethod infer_shapes(concentration: tuple[int, ...], total_count: tuple[int, ...] = ()) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

DiscreteUniform

class DiscreteUniform(low: ndarray | Array | number | int | float | complex = 0, high: ndarray | Array | number | int | float | complex = 1, *, validate_args: bool | None = None)[source]

Bases: Distribution

A discrete uniform random variable over the inclusive integer interval \(\{a, a+1, \dots, b\}\), where \(a\) (low) is the inclusive lower bound and \(b\) (high) is the inclusive upper bound of the support.

The Probability Mass Function (PMF) of the discrete uniform distribution is defined as:

\[P(X = k \mid a, b) = \frac{1}{b - a + 1}, \quad k \in \{a, a+1, \dots, b\}\]

Where \(k\) is the observed integer value (value).

Parameters:
  • low – Inclusive lower bound of the integer support. Default is 0.

  • high – Inclusive upper bound of the integer support. Must satisfy high >= low. Default is 1.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'high': Dependent(), 'low': Dependent()}
has_enumerate_support: bool = True
pytree_data_fields: tuple[str, ...] = ('low', 'high')
property support: Constraint

The support of the discrete uniform distribution is the set of integers \(\{\text{low}, \text{low}+1, \dots, \text{high}\}\).

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the discrete uniform distribution.

This method invokes randint() directly, which generates uniformly distributed integers in the half-open interval [low, high + 1), equivalent to the inclusive interval \(\{a, \dots, b\}\).

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer-valued samples drawn uniformly from \(\{a, \dots, b\}\).

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at specified integer values.

\[\ln P(X = k \mid a, b) = -\ln(b - a + 1)\]

The log-PMF is constant over the support, so the implementation simply broadcasts the negative log of the support cardinality to the requested shape.

Parameters:

value – Integer observation(s) to score (\(k \in \{a, \dots, b\}\)).

Returns:

Log probability scores evaluated under the discrete uniform PMF.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the cumulative distribution function (CDF) of the discrete uniform distribution.

\[F(x) = \frac{\lfloor x \rfloor + 1 - a}{b - a + 1}, \quad \text{clipped to } [0, 1]\]
Parameters:

value – Point(s) at which to evaluate the CDF.

Returns:

The CDF evaluated at value, clipped to the unit interval.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the inverse cumulative distribution function (quantile function) of the discrete uniform distribution.

\[F^{-1}(u) = a + \lceil u\,(b - a + 1) \rceil - 1, \quad u \in (0, 1]\]

that is, the smallest \(k \in \{a, \dots, b\}\) with \(F(k) \ge u\). \(u = 0\) maps to \(a\).

Parameters:

q – Quantile level(s) \(u \in [0, 1]\).

Returns:

The inverse CDF evaluated at q.

property mean: Array

The mean of the discrete uniform distribution is the midpoint of the support:

\[E[X] = \frac{a + b}{2}\]
Returns:

The mean of the discrete uniform distribution.

property variance: Array

The variance of the discrete uniform distribution is given by:

\[\mathrm{Var}[X] = \frac{(b - a + 1)^2 - 1}{12}\]
Returns:

The variance of the discrete uniform distribution.

enumerate_support(expand: bool = True) → Array[source]

Enumerate all values in the support of the discrete uniform distribution.

Both low and high must be concrete (non-JAX-tracer) values and homogeneous across the batch shape; otherwise a NotImplementedError is raised.

Parameters:

expand – Whether to broadcast the enumerated values across the batch shape. Default is True.

Returns:

An array of integer values \(\{a, a+1, \dots, b\}\), optionally broadcast across the batch dimensions.

entropy() → Array[source]

The entropy of the discrete uniform distribution is given by:

\[H[X] = \ln(\text{high} - \text{low} + 1)\]
Returns:

The entropy of the discrete uniform distribution.

GammaPoisson

class GammaPoisson(concentration: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

Compound distribution comprising of a gamma-poisson pair, also referred to as a gamma-poisson mixture. The rate parameter for the Poisson distribution is unknown and randomly drawn from a Gamma distribution.

Parameters:
  • concentration (numpy.ndarray) – shape parameter (alpha) of the Gamma distribution.

  • rate (numpy.ndarray) – rate parameter (rate) for the Gamma distribution.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'rate': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_data_fields: tuple[str, ...] = ('concentration', 'rate', '_gamma')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the sampling procedure is:

\[\begin{split}\begin{align*} \theta &\sim \mathrm{Gamma}(\alpha, \lambda) \\ X \mid \theta &\sim \mathrm{Poisson}(\theta) \end{align*}\end{split}\]

It uses Gamma to generate samples from the Gamma distribution and Poisson to generate samples from the Poisson distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the probability mass function is:

\[p_{X}(k) = \frac{\lambda^\alpha}{(\alpha + k)(1+\lambda)^{\alpha + k}\mathrm{B}(\alpha, k + 1)}\]
property mean: Array

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the mean is:

\[\mathbb{E}[X] = \frac{\alpha}{\lambda}\]
property variance: Array

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the variance is:

\[\mathrm{Var}[X] = \frac{\alpha}{\lambda^2}(1 + \lambda)\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the cumulative distribution function, for \(k = \lfloor x \rfloor \geq 0\), is:

\[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 \(x < 0\) and one at \(x = \infty\). This implementation uses betainc(), which does not support gradients with respect to its first argument, so the CDF is not differentiable with respect to concentration.

Geometric

Geometric(probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None) → GeometricProbs | GeometricLogits[source]

Geometric distribution parameterized by either probabilities or logits.

Exactly one of probs or logits must be specified.

Parameters:
  • probs (ArrayLike, optional) – Probability of success on each independent trial (\(p\)).

  • logits (ArrayLike, optional) – Logits of success on each independent trial.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

Returns:

A probability- or logit-parameterized Geometric distribution.

Return type:

Union[GeometricProbs, GeometricLogits]

Raises:

ValueError – If both or neither of probs and logits are specified.

GeometricLogits

class GeometricLogits(logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Geometric distribution parameterized by logits (logits).

\[P(X = k \mid \ell) = \sigma(\ell) \left(1-\sigma(\ell)\right)^k, \qquad k \in \{0, 1, 2, \ldots\}.\]

where \(\ell\) denote the logits parameter, \(p = \sigma(\ell) = \displaystyle\frac{1}{1+\exp(-\ell)}\) is the probability of success.

Parameters:
  • logits (ArrayLike) – Logits of success on each trial (\(\ell\)) in \((-\infty, \infty]\); \(+\infty\) is certain success on the first trial.

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'logits': GreaterThan(lower_bound=-inf)}
support = IntegerNonnegative(lower_bound=0)
probs() → Array[source]

The success probability obtained by applying the sigmoid function to the logits.

\[p = \sigma(\ell) = \frac{1}{1+\exp(-\ell)}.\]
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples using inverse CDF technique in logit space.

Parameters:
  • key (jax.Array) – JAX pseudo-random number generator key.

  • sample_shape (tuple[int, ...]) – Sample dimensions to prepend to the batch shape.

Returns:

Samples from the Geometric distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log probability mass function.

\[\log P(X = k; \ell) = -\operatorname{softplus}(-\ell) - k \operatorname{softplus}(\ell),\]

where, \(\operatorname{softplus}\) is softplus().

Parameters:

value (ArrayLike) – Number of failures before the first success. Values must be nonnegative integers.

Returns:

Log probability mass.

Return type:

jax.Array

property mean: Array

Calculates the mean of the Geometric distribution.

\[E[X] = \frac{1}{p}-1,\]

where \(p=\sigma(\ell)\). Computed directly as \(\exp(-\ell)\) to avoid cancellation when \(p\) rounds to one.

property variance: Array

Calculates the variance of the Geometric distribution.

\[\operatorname{Var}(X) = \frac{1-p}{p^2},\]

implemented as,

\[\operatorname{Var}(X) = \exp(-\ell)(1+\exp(-\ell)),\]

where \(p=\sigma(\ell)\).

entropy() → Array[source]

Calculates the entropy of the Geometric distribution.

\[H(X) = -\frac{1-p}{p}\ln{q}-\ln{p},\]

where, \(\ln{p}=-\operatorname{softplus}(-\ell)\), \(\ln{q}=-\operatorname{softplus}(\ell)\), and \(p=\operatorname{expit}(\ell)\). Implementation uses softplus() and expit() for \(\operatorname{softplus}\) and \(\operatorname{expit}\), respectively.

Returns:

Entropy of the Geometric distribution.

Return type:

jax.Array

GeometricProbs

class GeometricProbs(probs: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Geometric discrete random variable representing the number of failures before the first success, parameterized by the success probability (probs).

The probability mass function (PMF) is defined as:

\[P(X = k; p) = p(1-p)^k\]

where \(p \in (0,1]\) is the probability of success on each independent trial. \(k \in \{0, 1, 2, \ldots\}\) is the number of failures before first success. Equivalently, the first success occurs on trial \(k+1\).

Parameters:
  • probs (ArrayLike) – Probability of success on each trial (\(p\)).

  • validate_args (bool, optional) – Whether to validate input constraints, defaults to None.

arg_constraints: dict[str, Any] = {'probs': UnitInterval(lower_bound=0.0, upper_bound=1.0)}
support = IntegerNonnegative(lower_bound=0)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Generates samples using inverse CDF method.

For a uniform random variable \(U \sim \mathrm{Uniform}[0, 1)\), a Geometric sample is obtained as:

\[X = \left\lfloor \frac{\log(1-U)}{\log(1-p)} \right\rfloor.\]
Parameters:
  • key (jax.Array) – JAX PRNGKey for reproducibility.

  • sample_shape (tuple[int, ...]) – The shape of the samples to be generated.

Returns:

Samples from Geometric distribution of shape sample_shape + batch_shape.

Return type:

jax.Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculates the log of the probability mass function.

\[\log P(X = k; p) = k\log(1-p) + \log p.\]
Parameters:

value (ArrayLike) – Values at which to evaluate the log density. Values must be nonnegative integers.

Returns:

Log probability mass.

Return type:

jax.Array

logits() → Array[source]

Calculates the logits corresponding to the success probability.

\[\ell = \log\left(\frac{p}{1-p}\right).\]
property mean: Array

Calculates the mean of the Geometric distribution.

\[\mathbb{E}[X] = \frac{1-p}{p}.\]
property variance: Array

Calculates the variance of the Geometric distribution.

\[\operatorname{Var}(X) = \frac{1-p}{p^2}.\]
entropy() → Array[source]

Entropy of the Geometric distribution.

\[H(X) = -\log p - \frac{1-p}{p}\log(1-p).\]
Returns:

Entropy of the Geometric distribution.

Return type:

jax.Array

HurdleDistribution

HurdleDistribution(base_dist: Distribution, *, gate: Array | ndarray | bool | number | bool | int | float | complex | None = None, gate_logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None) → HurdleProbs | HurdleLogits[source]

Generic hurdle distribution.

A hurdle model is a two-part model: a Bernoulli “hurdle” selects between an exact zero (with probability gate) and a positive draw from the (zero-truncated, for discrete bases) base distribution. Writing \(g\) for the gate and \(B\) for the base PMF, a discrete base gives

\[P(X = 0) = g, \qquad P(X = k) = (1 - g)\, \frac{B(k)}{1 - B(0)} \;\text{for } k \geq 1,\]

while a continuous base with density \(b\) on \(\mathbb{R}_{>0}\) gives a point mass \(P(X = 0) = g\) mixed with \(p(x) = (1 - g)\, b(x)\) for \(x > 0\). When gate_logits \(= z\) is supplied instead, \(g = \sigma(z) = 1 / (1 + e^{-z})\). With base mean \(\mu_B\) and variance \(\sigma_B^2\), the moments for a discrete base are

\[\mathbb{E}[X] = (1 - g)\, \frac{\mu_B}{1 - B(0)}, \qquad \operatorname{Var}[X] = (1 - g)\, \frac{\mu_B^2 + \sigma_B^2}{1 - B(0)} - \mathbb{E}[X]^2,\]

and for a continuous base the same expressions without the \(1 - B(0)\) divisor.

Returns a HurdleProbs if gate is supplied, or a HurdleLogits if gate_logits is supplied. Exactly one of the two must be provided. See HurdleProbs for the full mechanism and assumptions.

Parameters:
  • base_dist (Distribution) – the base distribution.

  • gate (ArrayLike) – probability of a structural zero.

  • gate_logits (ArrayLike) – log-odds of a structural zero.

References:

  1. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent Variables with Application to the Demand for Durable Goods. Econometrica, 39(5), 829-844.

  2. Mullahy, J. (1986). Specification and testing of some modified count data models. Journal of Econometrics, 33(3), 341-365.

HurdleLogits

class HurdleLogits(base_dist: Distribution, gate_logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: HurdleProbs

Hurdle distribution parameterized by gate_logits (the log-odds of the structural zero) instead of a probability.

Like HurdleProbs, this is a two-part model where a Bernoulli “hurdle” - here parameterized in logit space - selects between an exact zero and a positive draw from the (zero-truncated, for discrete bases) base distribution. See HurdleProbs for the full mechanism, assumptions, and underlying PMF/PDF.

Parameters:
  • base_dist (Distribution) – the base distribution.

  • gate_logits (ArrayLike) – log-odds of a structural zero, \(\mathrm{logit}(g) = \log\frac{g}{1 - g}\).

References:

  1. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent Variables with Application to the Demand for Durable Goods. Econometrica, 39(5), 829-844.

  2. Mullahy, J. (1986). Specification and testing of some modified count data models. Journal of Econometrics, 33(3), 341-365.

arg_constraints: dict[str, Any] = {'gate_logits': ExtendedReal()}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'gate_logits')

HurdleNegativeBinomial2

HurdleNegativeBinomial2(gate: Array | ndarray | bool | number | bool | int | float | complex, mean: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None) → HurdleProbs[source]

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 \(g\) and positive counts follow a zero-truncated \(\mathrm{NegativeBinomial2}(\mu, \alpha)\). The hurdle and the magnitude (given a positive count) are conditionally independent; see 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

\[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 \(\mathrm{NB2}(\cdot\mid\mu, \alpha)\) is the PMF of a Negative Binomial distribution with mean \(\mu\) and concentration (dispersion) \(\alpha\).

Parameters:
  • gate (ArrayLike) – probability of a structural zero, \(g \in [0, 1]\).

  • mean (ArrayLike) – mean \(\mu > 0\) of the underlying NegativeBinomial2.

  • concentration (ArrayLike) – concentration \(\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.

HurdlePoisson

class HurdlePoisson(gate: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: HurdleProbs

A hurdle Poisson distribution: a two-part model in which structural zeros are produced by a Bernoulli “hurdle” with probability \(g\) and positive counts follow a zero-truncated \(\mathrm{Poisson}(\lambda)\). The hurdle and the magnitude (given a positive count) are conditionally independent; see HurdleProbs for the full mechanism and assumptions.

The probability mass function is

\[P(X = 0) = g, \qquad P(X = k) = (1 - g) \, \frac{\lambda^{k} e^{-\lambda} / k!}{1 - e^{-\lambda}} \;\text{for } k \geq 1.\]
Parameters:
  • gate (ArrayLike) – probability of a structural zero, \(g \in [0, 1]\).

  • rate (ArrayLike) – rate \(\lambda > 0\) of the underlying Poisson.

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.

arg_constraints: dict[str, Any] = {'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'rate': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_data_fields: tuple[str, ...] = ('rate',)

HurdleProbs

class HurdleProbs(base_dist: Distribution, gate: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Generic hurdle distribution parameterized by a probability \(g\) (gate) of the structural zero and an arbitrary base distribution.

Hurdle mechanism. A hurdle model is a two-part model. A Bernoulli “hurdle” decides whether the outcome is zero (with probability \(g\), the gate) or strictly positive (with probability \(1 - g\)). Conditional on the outcome being positive, the magnitude is drawn from the base distribution - zero-truncated in the discrete case so the base distribution cannot itself produce a zero. With \(B\) denoting the base PMF/PDF:

\[P(X = 0) = g, \qquad P(X = k) = (1 - g) \, \frac{B(k)}{1 - B(0)} \;\text{for } k \geq 1 \;\text{(discrete base)}\]

For a continuous base on \(\mathbb{R}_{>0}\) the truncation factor \(1 - B(0)\) equals 1 and the formula simplifies to a point mass at 0 with weight \(g\) mixed with \((1 - g) \, b(x)\) on \(x > 0\).

Assumptions.

  1. All zeros are structural - they originate exclusively from the hurdle process. This contrasts with zero-inflated models, which mix structural zeros with sampling zeros from the base distribution.

  2. The hurdle decision (zero vs. positive) and the magnitude (given positive) are conditionally independent given the parameters.

  3. For a discrete base, \(P(\text{base} = 0) < 1\) so the truncation factor \(1 - B(0)\) is well-defined. For a continuous base supported on \(\mathbb{R}_{>0}\), \(P(\text{base} = 0) = 0\) and no truncation is needed.

Note

gate is the probability of a structural zero. This matches the convention used by ZeroInflatedDistribution, and corresponds to 1 - psi in PyMC’s hurdle distributions.

Parameters:
  • base_dist (Distribution) – the base distribution.

  • gate (ArrayLike) – probability of a structural zero, in \([0, 1]\).

References:

  1. Cragg, J. G. (1971). Some Statistical Models for Limited Dependent Variables with Application to the Demand for Durable Goods. Econometrica, 39(5), 829-844.

  2. Mullahy, J. (1986). Specification and testing of some modified count data models. Journal of Econometrics, 33(3), 341-365.

arg_constraints: dict[str, Any] = {'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0)}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'gate')
pytree_aux_fields: tuple[str, ...] = ('_is_discrete',)
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

mean() → Array[source]

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

Multinomial

Multinomial(total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, total_count_max: int | None = None, validate_args: bool | None = None) → MultinomialProbs | MultinomialLogits[source]

Multinomial distribution.

A Multinomial random vector \(\mathbf{X} \in \mathbb{N}^K\) counts how many of \(n\) independent trials fall into each of \(K\) mutually exclusive categories with probabilities \(\mathbf{p} = (p_1, \dots, p_K)\), \(\sum_k p_k = 1\). For \(\mathbf{x} \in \mathbb{N}^K\) with \(\sum_k x_k = n\), its probability mass function is

\[P(\mathbf{X} = \mathbf{x} \mid n, \mathbf{p}) = \frac{n!}{\prod_{k=1}^{K} x_k!} \prod_{k=1}^{K} p_k^{x_k}.\]

When logits \(\mathbf{z}\) are given, the probabilities are \(\mathbf{p} = \operatorname{softmax}(\mathbf{z})\). The moments are

\[\mathbb{E}[X_k] = n p_k, \qquad \operatorname{Var}[X_k] = n p_k (1 - p_k), \qquad \operatorname{Cov}[X_j, X_k] = -n p_j p_k \quad (j \ne k),\]

and variance returns the diagonal \(n p_k (1 - p_k)\) only.

Exactly one of probs or logits must be given; the function returns a MultinomialProbs or a MultinomialLogits instance respectively (note that the returned classes take probs/logits before total_count).

Parameters:
  • total_count – number of trials \(n\). If this is a JAX array, it is required to specify total_count_max.

  • probs – event probabilities \(\mathbf{p}\)

  • logits – event log probabilities \(\mathbf{z}\)

  • total_count_max (int) – the maximum number of trials, i.e. max(total_count)

Note

total_count_max (an upper bound on total_count) must be given when total_count is a traced array, because the sampler draws a static number total_count_max of categorical trials and masks the excess; otherwise a ValueError is raised.

MultinomialLogits

class MultinomialLogits(logits: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, total_count_max: int | None = None, validate_args: bool | None = None)[source]

Bases: Distribution

A Multinomial discrete random vector over \(K\) mutually exclusive outcomes, parameterized by unnormalized log-probabilities (logits) and a total count \(n\) of i.i.d. trials.

The Probability Mass Function (PMF) of the Multinomial distribution is defined, via the softmax transformation of the logits, as:

\[P(X = \mathbf{x} \mid \boldsymbol{\alpha}, n) = \frac{n!}{\prod_{k=0}^{K-1} x_k!} \prod_{k=0}^{K-1} \left( \frac{\exp(\alpha_k)}{\sum_{j=0}^{K-1} \exp(\alpha_j)} \right)^{x_k}\]

where \(\boldsymbol{\alpha} = (\alpha_0, \alpha_1, \dots, \alpha_{K-1})\) is the real-valued logits vector (logits), \(n\) is the number of trials (total_count), and the count vector \(\mathbf{x} = (x_0, x_1, \dots, x_{K-1})\) lies on the support \(x_k \in \{0, 1, \dots, n\}\) with \(\sum_{k=0}^{K-1} x_k = n\).

Parameters:
  • logits – Logits vector; the trailing dimension indexes the \(K\) categories. Logits are unnormalized and converted to probabilities via the softmax function. A \(-\infty\) entry is a zero-probability category; \(+\infty\) is rejected since the softmax is then undefined.

  • total_count – Number of trials \(n\). If this is a JAX array, it is required to specify total_count_max.

  • total_count_max – The maximum number of trials, i.e. max(total_count), used to size the sampler’s internal arrays.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'logits': SoftmaxLogits(), 'total_count': IntegerNonnegative(lower_bound=0)}
pytree_data_fields: tuple[str, ...] = ('logits',)
pytree_aux_fields: tuple[str, ...] = ('total_count', 'total_count_max')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw count-vector samples from the Multinomial distribution.

This method delegates to multinomial(), which draws total_count category indices with categorical() (an inverse-CDF sampler over probs, the softmax of logits) and accumulates them into counts.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer count vectors \(\mathbf{x}\) with \(\sum_{k=0}^{K-1} x_k =\) total_count, drawn from the Multinomial distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at value.

\[\ln P(X = \mathbf{x} \mid \boldsymbol{\alpha}, n) = \ln\Gamma(n + 1) + \sum_{k=0}^{K-1} \left[ x_k \ln p_k - \ln\Gamma(x_k + 1) \right], \qquad \ln p_k = \alpha_k - \ln\!\sum_{j=0}^{K-1} \exp(\alpha_j)\]

where \(n\) is total_count. The log-partition term uses logsumexp() for stability, and a zero count contributes nothing even for a category with \(\alpha_k = -\infty\).

Parameters:

value – Count vector \(\mathbf{x}\) whose last dimension has size \(K\) and sums to total_count.

Returns:

Log probability scores evaluated under the Multinomial PMF.

probs() → Array[source]

The probability vector of the Multinomial distribution is given by the softmax of the logits:

\[p_k = \frac{\exp(\alpha_k)}{\sum_{j=0}^{K-1} \exp(\alpha_j)}, \quad k \in \{0, 1, \dots, K-1\}\]
property mean: Array

Mean of the Multinomial distribution.

\[\mathbb{E}[X_k] = n\, p_k, \quad k \in \{0, 1, \dots, K-1\}\]

where \(p_k = \mathrm{softmax}(\boldsymbol{\alpha})_k\).

property variance: Array

Variance of the Multinomial distribution.

\[\mathrm{Var}(X_k) = n\, p_k (1 - p_k), \quad k \in \{0, 1, \dots, K-1\}\]

where \(p_k = \mathrm{softmax}(\boldsymbol{\alpha})_k\).

property support: Constraint

The support of the Multinomial distribution is the set of count vectors \(\mathbf{x} \in \{0, 1, \dots, n\}^K\) whose entries sum to total_count \(n\).

classmethod infer_shapes(logits: tuple[int, ...], total_count: tuple[int, ...]) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

MultinomialProbs

class MultinomialProbs(probs: Array | ndarray | bool | number | bool | int | float | complex, total_count: Array | ndarray | bool | number | bool | int | float | complex = 1, *, total_count_max: int | None = None, validate_args: bool | None = None)[source]

Bases: Distribution

A Multinomial discrete random vector over \(K\) mutually exclusive outcomes, parameterized by a probability vector on the simplex and a total count \(n\) of i.i.d. trials.

The Probability Mass Function (PMF) of the Multinomial distribution is defined as:

\[P(X = \mathbf{x} \mid \mathbf{p}, n) = \frac{n!}{\prod_{k=0}^{K-1} x_k!} \prod_{k=0}^{K-1} p_k^{x_k}\]

where the probability vector \(\mathbf{p} = (p_0, p_1, \dots, p_{K-1})\) (probs) satisfies \(p_k \ge 0\) and \(\sum_{k=0}^{K-1} p_k = 1\), \(n\) is the number of trials (total_count), and the count vector \(\mathbf{x} = (x_0, x_1, \dots, x_{K-1})\) lies on the support \(x_k \in \{0, 1, \dots, n\}\) with \(\sum_{k=0}^{K-1} x_k = n\).

Parameters:
  • probs – Category probability vector on the simplex; the trailing dimension indexes the \(K\) categories and must sum to one.

  • total_count – Number of trials \(n\). If this is a JAX array, it is required to specify total_count_max.

  • total_count_max – The maximum number of trials, i.e. max(total_count), used to size the sampler’s internal arrays.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'probs': Simplex(), 'total_count': IntegerNonnegative(lower_bound=0)}
pytree_data_fields: tuple[str, ...] = ('probs',)
pytree_aux_fields: tuple[str, ...] = ('total_count', 'total_count_max')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw count-vector samples from the Multinomial distribution.

This method delegates to multinomial(), which draws total_count category indices with categorical() (an inverse-CDF sampler over probs) and accumulates them into counts.

Parameters:
  • key – A JAX random number generator key (PRNG state).

  • sample_shape – Desired sample dimensions to prepend to the batch shape.

Returns:

Integer count vectors \(\mathbf{x}\) with \(\sum_{k=0}^{K-1} x_k =\) total_count, drawn from the Multinomial distribution.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability mass function at value.

\[\ln P(X = \mathbf{x} \mid \mathbf{p}, n) = \ln\Gamma(n + 1) + \sum_{k=0}^{K-1} \left[ x_k \ln p_k - \ln\Gamma(x_k + 1) \right]\]

where \(n\) is total_count. The implementation uses gammaln() for the factorial terms and xlogy() so that zero counts contribute correctly even when some \(p_k = 0\).

Parameters:

value – Count vector \(\mathbf{x}\) whose last dimension has size \(K\) and sums to total_count.

Returns:

Log probability scores evaluated under the Multinomial PMF.

logits() → Array[source]

The log-probability (logits) parameter of the Multinomial distribution is the (already-normalized) log of the category probabilities:

\[\alpha_k = \ln p_k, \quad k \in \{0, 1, \dots, K-1\}\]
property mean: Array

Mean of the Multinomial distribution.

\[\mathbb{E}[X_k] = n\, p_k, \quad k \in \{0, 1, \dots, K-1\}\]
property variance: Array

Variance of the Multinomial distribution.

\[\mathrm{Var}(X_k) = n\, p_k (1 - p_k), \quad k \in \{0, 1, \dots, K-1\}\]
property support: Constraint

The support of the Multinomial distribution is the set of count vectors \(\mathbf{x} \in \{0, 1, \dots, n\}^K\) whose entries sum to total_count \(n\).

classmethod infer_shapes(probs: tuple[int, ...], total_count: tuple[int, ...]) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

OrderedLogistic

class OrderedLogistic(predictor: Array | ndarray | bool | number | bool | int | float | complex, cutpoints: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: CategoricalProbs

A categorical distribution with ordered outcomes.

The ordered logistic (proportional odds) distribution models an ordinal outcome \(Y\) that takes one of \(K\) ordered categories. A real-valued predictor \(\eta\) is compared with \(K - 1\) strictly increasing cutpoints \(c_0 < c_1 < \dots < c_{K-2}\) through the logistic CDF, so that the cumulative probabilities are

\[P(Y \le k \mid \eta, \mathbf{c}) = \sigma(c_k - \eta), \quad k \in \{0, 1, \dots, K-2\}\]

where \(\sigma(x) = 1 / (1 + e^{-x})\) is the logistic sigmoid function, i.e. \(\operatorname{logit} P(Y \le k) = c_k - \eta\). Differencing the cumulative probabilities gives the Probability Mass Function (PMF)

\[P(Y = k \mid \eta, \mathbf{c}) = \sigma(c_k - \eta) - \sigma(c_{k-1} - \eta), \quad k \in \{0, 1, \dots, K-1\}\]

with the conventions \(c_{-1} = -\infty\) and \(c_{K-1} = +\infty\), so that the first and last categories have probabilities \(P(Y = 0) = \sigma(c_0 - \eta)\) and \(P(Y = K-1) = 1 - \sigma(c_{K-2} - \eta)\). The support is \(k \in \{0, 1, \dots, K-1\}\), and increasing \(\eta\) shifts probability mass towards the higher categories.

The category probabilities are computed by applying the inverse of SimplexToOrderedTransform, with \(\eta\) as its anchor point, to the cutpoints; they are stored in probs as for any categorical distribution.

References:

  1. Stan Functions Reference, v2.20 section 12.6, Stan Development Team

  2. Regression Models for Ordinal Data, P. McCullagh (1980), Journal of the Royal Statistical Society: Series B, 42(2)

Parameters:
  • predictor (numpy.ndarray) – prediction \(\eta\) in real domain; typically this is output of a linear model.

  • cutpoints (numpy.ndarray) – positions \(c_0 < \dots < c_{K-2}\) in real domain to separate categories; the trailing dimension has size \(K - 1\) and the leading dimensions are batch dimensions that are broadcast against the shape of predictor.

  • probs – Category probability vector on the simplex; the trailing dimension indexes the \(K\) categories and must sum to one.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'cutpoints': OrderedVector(), 'predictor': Real()}
classmethod infer_shapes(predictor: tuple[int, ...], cutpoints: tuple[int, ...]) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

entropy() → Array[source]

The entropy of the Categorical distribution is given by:

\[H[X] = -\sum_{k=0}^{K-1} p_k \ln p_k\]
Returns:

The entropy of the Categorical distribution.

NegativeBinomial

NegativeBinomial(total_count: Array | ndarray | bool | number | bool | int | float | complex, probs: Array | ndarray | bool | number | bool | int | float | complex | None = None, logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None) → GammaPoisson[source]

Factory function for the Negative Binomial distribution.

\(X \sim \mathrm{NB}(r, p)\) counts the successes (probability \(p\) each) observed before the \(r\)-th failure of a sequence of Bernoulli trials,

\[P(X = k \mid r, p) = \frac{\Gamma(k + r)}{k!\,\Gamma(r)}\,(1 - p)^{r}\,p^{k}, \qquad k \in \mathbb{N},\]

with

\[\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 \(I_x(a, b)\) is the regularized incomplete beta function. With logits \(z\), \(p = \sigma(z)\) and \(\mathbb{E}[X] = r e^{z}\).

The Negative Binomial is the Gamma–Poisson mixture \(\lambda \sim \mathrm{Gamma}(r, \tfrac{1 - p}{p}),\ X \mid \lambda \sim \mathrm{Poisson}(\lambda)\).

Note

Both returned classes subclass GammaPoisson and sample as Gamma→Poisson; the cdf is GammaPoisson.cdf(). NegativeBinomialLogits evaluates log_prob/mean/variance directly in terms of the logits so that \(z = -\infty\) is exact. If both probs and logits are given, probs is used and logits is ignored.

Parameters:
  • total_count – Number of failures \(r > 0\) at which the Bernoulli trials stop (need not be an integer).

  • probs (Optional[ArrayLike]) – Success probability \(p\) of each trial, by default None.

  • logits (Optional[ArrayLike]) – Log-odds \(z = \log\frac{p}{1-p}\); \(-\infty\) puts all mass at zero. By default None.

  • validate_args (Optional[bool]) – Whether to validate the parameters, by default None

Returns:

An instance of NegativeBinomialProbs or NegativeBinomialLogits depending on the provided parameters.

Return type:

GammaPoisson

Raises:

ValueError – If neither probs nor logits is specified.

NegativeBinomialLogits

class NegativeBinomialLogits(total_count: Array | ndarray | bool | number | bool | int | float | complex, logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: GammaPoisson

Negative Binomial distribution parameterized by total_count (\(r\)) and logits (\(\displaystyle\mathrm{logits}(p)=\log \frac{p}{1-p}\)). It is implemented as a \(\mathrm{GammaPoisson}(n, \exp(-\mathrm{logits}(p)))\) distribution.

Parameters:
  • total_count – Number of successful trials.

  • logits – Log-odds parameter (\(\ln \frac{p}{1-p}\)) in \([-\infty, \infty)\); \(-\infty\) puts all mass at zero.

arg_constraints: dict[str, Any] = {'logits': LessThan(upper_bound=inf), 'total_count': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

If \(X \sim \mathrm{NegativeBinomial}(r, \mathrm{logits}(p))\), then the log probability mass function is:

\[\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)\]
property mean: Array

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the mean is:

\[\mathbb{E}[X] = \frac{\alpha}{\lambda}\]
property variance: Array

If \(X \sim \mathrm{GammaPoisson}(\alpha, \lambda)\), then the variance is:

\[\mathrm{Var}[X] = \frac{\alpha}{\lambda^2}(1 + \lambda)\]

NegativeBinomialProbs

class NegativeBinomialProbs(total_count: Array | ndarray | bool | number | bool | int | float | complex, probs: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: GammaPoisson

Negative Binomial distribution parameterized by total_count (\(r\)) and probs (\(p\)). It is implemented as a \(\displaystyle\mathrm{GammaPoisson}(n, \frac{1}{p} - 1)\) distribution.

Parameters:
  • total_count – Number of successful trials (\(r\)).

  • probs – Probability of success for each trial (\(p\)).

arg_constraints: dict[str, Any] = {'probs': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'total_count': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)

NegativeBinomial2

class NegativeBinomial2(mean: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: GammaPoisson

If \(X \sim \mathrm{NegativeBinomial2}(\mu, \alpha)\), then \(X \sim \mathrm{GammaPoisson}(\alpha, \frac{\alpha}{\mu})\).

Parameters:
arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'mean': Nonnegative(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_data_fields: tuple[str, ...] = ('concentration',)

Poisson

class Poisson(rate: Array | ndarray | bool | number | bool | int | float | complex, *, is_sparse: bool = False, validate_args: bool | None = None)[source]

Bases: Distribution

Creates a Poisson distribution parameterized by rate, the rate parameter.

The Poisson distribution models the number of events occurring in a fixed interval given a constant average rate \(\lambda > 0\). Samples are nonnegative integers \(k \in \{0, 1, 2, \dots\}\), with a probability mass function (PMF) given by

\[P(X = k \mid \lambda) = \frac{\lambda^k e^{-\lambda}}{k!}\]

where \(\lambda\) is the rate parameter. A defining property of the distribution is that its mean and variance are both equal to \(\lambda\).

Parameters:
  • rate (numpy.ndarray) – The rate parameter \(\lambda \ge 0\).

  • is_sparse (bool) – Whether to assume value is mostly zero when computing log_prob(), which can speed up computation when data is sparse.

arg_constraints: dict[str, Any] = {'rate': GreaterThanEq(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_aux_fields: tuple[str, ...] = ('is_sparse',)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples from the Poisson distribution using poisson().

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Nonnegative integer samples of shape sample_shape + batch_shape.

Return type:

Array

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Calculate the log of the probability mass function.

\[\log P(X = k \mid \lambda) = k \log \lambda - \log(k!) - \lambda\]

where \(\log(k!)\) is evaluated as \(\log \Gamma(k + 1)\) for numerical stability. When is_sparse is set, entries with \(k = 0\) reduce to \(-\lambda\) and only the nonzero entries incur the full computation.

Parameters:

value – Values at which to evaluate the log PMF.

Returns:

Log probability mass.

Return type:

Array

property mean: Array

Analytical mean of the Poisson distribution.

\[E[X] = \lambda\]
property variance: Array

Analytical variance of the Poisson distribution.

\[\operatorname{Var}(X) = \lambda\]
cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function evaluated at value.

For a nonnegative integer \(k = \lfloor x \rfloor\), the CDF equals the regularized upper incomplete gamma function

\[P(X \le x) = Q(\lfloor x \rfloor + 1, \lambda) = \frac{\Gamma(\lfloor x \rfloor + 1, \lambda)}{\lfloor x \rfloor !}\]
Parameters:

value – Value to evaluate.

Returns:

Cumulative probability.

Return type:

Array

ZeroInflatedDistribution

ZeroInflatedDistribution(base_dist: Distribution, *, gate: Array | ndarray | bool | number | bool | int | float | complex | None = None, gate_logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None) → ZeroInflatedProbs | ZeroInflatedLogits[source]

Generic Zero Inflated distribution.

Mixes a discrete base distribution with pmf \(B\) (scalar event) with a point mass at zero. With gate \(g \in [0, 1]\), the probability of a structural zero,

\[P(X = 0) = g + (1 - g)\, B(0), \qquad P(X = k) = (1 - g)\, B(k) \quad (k \ne 0).\]

When gate_logits \(z\) is given, \(g = \sigma(z)\) with \(\sigma\) the logistic function. With \(\mu_B\) and \(\sigma_B^2\) the mean and variance of the base distribution,

\[\mathbb{E}[X] = (1 - g)\, \mu_B, \qquad \operatorname{Var}[X] = (1 - g)\left(\mu_B^2 + \sigma_B^2\right) - \mathbb{E}[X]^2.\]

Exactly one of gate or gate_logits must be given; the function returns a ZeroInflatedProbs or a ZeroInflatedLogits instance respectively. The base distribution must have a discrete support and an empty event_shape. ZeroInflatedPoisson and ZeroInflatedNegativeBinomial2() are ready-made specializations.

Parameters:
  • base_dist (Distribution) – the base distribution.

  • gate (numpy.ndarray) – probability of extra zeros given via a Bernoulli distribution.

  • gate_logits (numpy.ndarray) – logits of extra zeros given via a Bernoulli distribution.

ZeroInflatedLogits

class ZeroInflatedLogits(base_dist: Distribution, gate_logits: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: ZeroInflatedProbs

A generic zero-inflated distribution parameterized by the gate logits.

This is the same distribution as ZeroInflatedProbs, with the gate \(g\) given on the logit scale \(z\) through the sigmoid,

\[g = \sigma(z) = \frac{1}{1 + e^{-z}}.\]

The PMF is therefore \(P(X = 0) = g + (1 - g)\, b(0)\) and \(P(X = k) = (1 - g)\, b(k)\) for \(k \neq 0\), with \(1 - g = \sigma(-z)\).

Parameters:
  • base_dist (Distribution) – a discrete base distribution with empty event_shape.

  • gate_logits (numpy.ndarray) – logits \(z\) of the structural-zero probability.

arg_constraints: dict[str, Any] = {'gate_logits': ExtendedReal()}
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

ZeroInflatedProbs

class ZeroInflatedProbs(base_dist: Distribution, gate: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

A generic zero-inflated distribution built from a discrete base distribution.

Let \(B\) be a discrete base distribution with PMF \(b(k)\) and gate \(g\) (the probability of a structural zero). The zero-inflated PMF is

\[P(X = 0) = g + (1 - g)\, b(0), \qquad P(X = k) = (1 - g)\, b(k) \;\text{for } k \neq 0.\]

Zeros can come either from the structural component (with probability \(g\)) or from the base distribution itself (with probability \((1 - g)\, b(0)\)). The mean and variance are

\[\mathbb{E}[X] = (1 - g)\, \mathbb{E}[B], \qquad \operatorname{Var}(X) = (1 - g)\left(\operatorname{Var}(B) + \mathbb{E}[B]^2\right) - (1 - g)^2\, \mathbb{E}[B]^2.\]

Note

gate is the probability of a structural zero, matching the convention used by ZeroInflatedPoisson.

Parameters:
  • base_dist (Distribution) – a discrete base distribution with empty event_shape.

  • gate (numpy.ndarray) – probability of extra (structural) zeros, in \([0, 1]\).

arg_constraints: dict[str, Any] = {'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0)}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'gate')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

mean() → Array[source]

Mean of the distribution.

variance() → Array[source]

Variance of the distribution.

property has_enumerate_support

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

enumerate_support(expand: bool = True) → Array[source]

Returns an array with shape len(support) x batch_shape containing all values in the support.

ZeroInflatedPoisson

class ZeroInflatedPoisson(gate: Array | ndarray | bool | number | bool | int | float | complex, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: ZeroInflatedProbs

A Zero-Inflated Poisson distribution.

A zero-inflated Poisson mixes a point mass at zero (the structural or excess zeros) with a Poisson distribution, allowing the number of zeros to exceed what a plain Poisson would produce. With gate \(g\) (the probability of a structural zero) and Poisson rate \(\lambda\), the probability mass function is

\[P(X = 0) = g + (1 - g)\, e^{-\lambda}, \qquad P(X = k) = (1 - g)\, \frac{\lambda^{k} e^{-\lambda}}{k!} \;\text{for } k \geq 1.\]

A zero therefore arises either from the structural component (with probability \(g\)) or as a sampling zero from the Poisson component (with probability \((1 - g)\, e^{-\lambda}\)).

The mean and variance are

\[\mathbb{E}[X] = (1 - g)\, \lambda, \qquad \operatorname{Var}(X) = (1 - g)\, \lambda\, (1 + g\, \lambda).\]

Whenever \(g > 0\) the variance exceeds the mean, so the zero-inflated Poisson captures the overdispersion that a plain Poisson - for which the mean equals the variance - cannot.

Note

gate is the probability of a structural zero, matching the convention used by ZeroInflatedDistribution.

Parameters:
  • gate (numpy.ndarray) – probability of extra (structural) zeros, in \([0, 1]\).

  • rate (numpy.ndarray) – rate \(\lambda\) of the Poisson component (default 1).

arg_constraints: dict[str, Any] = {'gate': UnitInterval(lower_bound=0.0, upper_bound=1.0), 'rate': Positive(lower_bound=0.0)}
support = IntegerNonnegative(lower_bound=0)
pytree_data_fields: tuple[str, ...] = ('rate',)

ZeroInflatedNegativeBinomial2

ZeroInflatedNegativeBinomial2(mean: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, gate: Array | ndarray | bool | number | bool | int | float | complex | None = None, gate_logits: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None)[source]

A zero-inflated Negative Binomial distribution (NB2 / mean-dispersion parameterization).

A zero-inflated 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 \(g\) (the probability of a structural zero), mean \(\mu\) and concentration \(\alpha\), the probability mass function is

\[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 \(\mathrm{NB2}(\cdot \mid \mu, \alpha)\) is the PMF of the NegativeBinomial2 distribution,

\[\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 \(g\)) or as a sampling zero from the Negative Binomial component (with probability \((1 - g)\, \mathrm{NB2}(0 \mid \mu, \alpha)\), where \(\mathrm{NB2}(0 \mid \mu, \alpha) = (\alpha / (\alpha + \mu))^{\alpha}\)).

The mean and variance are

\[\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 \(\mu + \mu^2 / \alpha\)). For \(g = 0\) the distribution reduces to NegativeBinomial2.

The gate must be specified either as a probability gate \(= g\) or as logits gate_logits \(= \ell\), with \(g = 1 / (1 + e^{-\ell})\). Exactly one of the two is required, as for ZeroInflatedDistribution().

Parameters:
  • mean (numpy.ndarray) – mean \(\mu\) of the NegativeBinomial2 component.

  • concentration (numpy.ndarray) – concentration (dispersion) \(\alpha\) of the NegativeBinomial2 component.

  • gate (numpy.ndarray) – probability of extra (structural) zeros, in \([0, 1]\).

  • gate_logits (numpy.ndarray) – logits of the probability of extra (structural) zeros.

Mixture Distributions

Mixture

Mixture(mixing_distribution: CategoricalProbs | CategoricalLogits, component_distributions: list[Distribution] | Distribution, *, validate_args: bool | None = None)[source]

A marginalized finite mixture of component distributions

With mixing weights \(\pi_k\) and component distributions \(p_k\) for \(k = 1, \dots, K\), the density (or mass function) of the mixture is

\[p(x) = \sum_{k=1}^{K} \pi_k \, p_k(x),\]

with mean and variance

\[\mathbb{E}[X] = \sum_{k=1}^{K} \pi_k \, \mathbb{E}[X_k], \qquad \mathrm{Var}[X] = \sum_{k=1}^{K} \pi_k \, \mathrm{Var}[X_k] + \sum_{k=1}^{K} \pi_k \left(\mathbb{E}[X_k] - \mathbb{E}[X]\right)^2.\]

The returned distribution will be either a:

  1. MixtureGeneral, when component_distributions is a list, or

  2. MixtureSameFamily, when component_distributions is a single distribution.

Both classes document how log_prob is evaluated; MixtureGeneral also describes cdf and sampling. Mixture has no support argument; construct MixtureGeneral directly to override the inferred support.

Parameters:
  • mixing_distribution – A Categorical specifying the weights for each mixture components. The size of this distribution specifies the number of components in the mixture, mixture_size.

  • component_distributions – Either a list of component distributions or a single vectorized distribution. When a list is provided, the number of elements must equal mixture_size. Otherwise, the last batch dimension of the distribution must equal mixture_size.

Returns:

The mixture distribution.

MixtureSameFamily

class MixtureSameFamily(mixing_distribution: CategoricalProbs | CategoricalLogits, component_distribution: Distribution, *, validate_args: bool | None = None)[source]

Bases: _MixtureBase

A finite mixture of component distributions from the same family

This mixture only supports a mixture of component distributions that are all of the same family. The different components are specified along the last batch dimension of the input component_distribution. If you need a mixture of distributions from different families, use the more general implementation in MixtureGeneral.

With mixing weights \(\pi_k\) (mixing_distribution.probs) and component distributions \(p_k\) for \(k = 1, \dots, K\), where \(K\) is the mixture_size, the density (or mass function) of the mixture is

\[p(x) = \sum_{k=1}^{K} \pi_k \, p_k(x).\]

log_prob evaluates this density in log space:

\[\log p(x) = \log \sum_{k=1}^{K} \exp\left(\log \pi_k + \log p_k(x)\right).\]

The mean and variance follow from the mixture weights and the component moments:

\[\mathbb{E}[X] = \sum_{k=1}^{K} \pi_k \, \mathbb{E}[X_k], \qquad \mathrm{Var}[X] = \sum_{k=1}^{K} \pi_k \, \mathrm{Var}[X_k] + \sum_{k=1}^{K} \pi_k \left(\mathbb{E}[X_k] - \mathbb{E}[X]\right)^2.\]

For multivariate components, the mean and variance are computed elementwise; the variance is the per-dimension marginal variance, not a covariance matrix.

Parameters:
  • mixing_distribution – A Categorical specifying the weights for each mixture components. The size of this distribution specifies the number of components in the mixture, mixture_size.

  • component_distribution – A single vectorized Distribution, whose last batch dimension equals mixture_size as specified by mixing_distribution.

Example

>>> import jax
>>> import jax.numpy as jnp
>>> import numpyro.distributions as dist
>>> mixing_dist = dist.Categorical(probs=jnp.ones(3) / 3.)
>>> component_dist = dist.Normal(loc=jnp.zeros(3), scale=jnp.ones(3))
>>> mixture = dist.MixtureSameFamily(mixing_dist, component_dist)
>>> mixture.sample(jax.random.key(42)).shape
()
pytree_data_fields: tuple[str, ...] = ('_mixing_distribution', '_component_distribution')
pytree_aux_fields: tuple[str, ...] = ('_mixture_size',)
property component_distribution: Distribution

Return the vectorized distribution of components being mixed.

Returns:

Component distribution

Return type:

Distribution

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

property is_discrete: bool
property component_mean: Array
property component_variance: Array
component_cdf(samples: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]
component_sample(key: Array, sample_shape: tuple[int, ...] = ()) → Array[source]
component_log_probs(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

MixtureGeneral

class MixtureGeneral(mixing_distribution: CategoricalProbs | CategoricalLogits, component_distributions: list[Distribution], *, support: Constraint | None = None, validate_args: bool | None = None)[source]

Bases: _MixtureBase

A finite mixture of component distributions from different families

If all of the component distributions are from the same family, the more specific implementation in MixtureSameFamily will be somewhat more efficient.

With mixing weights \(\pi_k\) (mixing_distribution.probs) and component distributions \(p_k\) for \(k = 1, \dots, K\), where \(K\) is the mixture_size, the density (or mass function) of the mixture is

\[p(x) = \sum_{k=1}^{K} \pi_k \, p_k(x).\]

log_prob evaluates this density in log space:

\[\log p(x) = \log \sum_{k=1}^{K} \exp\left(\log \pi_k + \log p_k(x)\right).\]

The mean and variance follow from the mixture weights and the component moments:

\[\mathbb{E}[X] = \sum_{k=1}^{K} \pi_k \, \mathbb{E}[X_k], \qquad \mathrm{Var}[X] = \sum_{k=1}^{K} \pi_k \, \mathrm{Var}[X_k] + \sum_{k=1}^{K} \pi_k \left(\mathbb{E}[X_k] - \mathbb{E}[X]\right)^2.\]

For multivariate components, the mean and variance are computed elementwise; the variance is the per-dimension marginal variance, not a covariance matrix. For scalar events the cumulative distribution function is the weighted sum of the component cdfs \(F_k\),

\[F(x) = \sum_{k=1}^{K} \pi_k \, F_k(x).\]

Sampling draws one value from every component and keeps the one selected by a component index \(k \sim \mathrm{Categorical}(\boldsymbol\pi)\); sample_with_intermediates() also returns this index.

Parameters:
  • mixing_distribution – A Categorical specifying the weights for each mixture components. The size of this distribution specifies the number of components in the mixture, mixture_size.

  • component_distributions – A list of mixture_size Distribution objects.

  • support – A Constraint object specifying the support of the mixture distribution. If not provided, the support will be inferred from the component distributions.

Note

log_prob uses \(\log \pi_k = \mathrm{log\_softmax}(\text{logits})_k\) and logsumexp; component terms equal to \(-\infty\) (e.g. at zero mixing weights) are stopped from propagating gradients. When support is passed explicitly, the log density of each component with validate_args disabled is set to \(-\infty\) outside that component’s own support before mixing, so components with different supports can be combined. All components must share the same event_shape and, unless support is given, the same support type. cdf raises NotImplementedError if a component does not implement it. has_rsample is False.

Example

>>> import jax
>>> import jax.numpy as jnp
>>> import numpyro.distributions as dist
>>> mixing_dist = dist.Categorical(probs=jnp.ones(3) / 3.)
>>> component_dists = [
...     dist.Normal(loc=0.0, scale=1.0),
...     dist.Normal(loc=-0.5, scale=0.3),
...     dist.Normal(loc=0.6, scale=1.2),
... ]
>>> mixture = dist.MixtureGeneral(mixing_dist, component_dists)
>>> mixture.sample(jax.random.key(42)).shape
()
>>> import jax
>>> import jax.numpy as jnp
>>> import numpyro.distributions as dist
>>> mixing_dist = dist.Categorical(probs=jnp.ones(2) / 2.)
>>> component_dists = [
...     dist.Normal(loc=0.0, scale=1.0),
...     dist.HalfNormal(scale=0.3),
... ]
>>> mixture = dist.MixtureGeneral(mixing_dist, component_dists, support=dist.constraints.real)
>>> mixture.sample(jax.random.key(42)).shape
()
pytree_data_fields: tuple[str, ...] = ('_mixing_distribution', '_component_distributions', '_support')
pytree_aux_fields: tuple[str, ...] = ('_mixture_size',)
property component_distributions: list[Distribution]

The list of component distributions in the mixture

Returns:

The list of component distributions

Return type:

list[Distribution]

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

property is_discrete: bool
property component_mean: Array
property component_variance: Array
component_cdf(samples: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]
component_sample(key: Array, sample_shape: tuple[int, ...] = ()) → Array[source]
component_log_probs(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Directional Distributions

ProjectedNormal

class ProjectedNormal(concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Projected isotropic normal distribution of arbitrary dimension.

This distribution over directional data is qualitatively similar to the von Mises and von Mises-Fisher distributions, but permits tractable variational inference via reparametrized gradients.

If \(\mathbf{z} \sim \mathcal{N}(\boldsymbol{\mu}, \mathbf{I}_d)\), then \(\mathbf{x} = \mathbf{z} / \lVert \mathbf{z} \rVert\) follows a projected normal distribution on the unit sphere \(S^{d-1}\). Its support is sphere, namely \(\{\mathbf{x} \in \mathbb{R}^d : \lVert \mathbf{x} \rVert = 1\}\). Its density with respect to the surface measure on the sphere is obtained by integrating the isotropic normal density along the ray through \(\mathbf{x}\) [1],

\[p(\mathbf{x} \mid \boldsymbol{\mu}) = \frac{e^{-\lVert \boldsymbol{\mu} \rVert^2 / 2}}{(2\pi)^{d/2}} \int_0^\infty r^{d-1} \exp\left( -\frac{r^2}{2} + r\, \boldsymbol{\mu}^\top \mathbf{x} \right) dr,\]

where \(\boldsymbol{\mu}\) is concentration. While the radial integral has a closed form for every nonnegative integer power, log_prob() implements the resulting density only for \(d \in \{2, 3\}\). Writing \(t = \boldsymbol{\mu}^\top \mathbf{x}\) and \(M_k(t) = \int_0^\infty r^k\, \phi(r-t)\, dr\), where \(\phi\) is the standard normal density, these implemented forms are

\[ \begin{align}\begin{aligned}p(\mathbf{x} \mid \boldsymbol{\mu}) = \frac{e^{-(\lVert \boldsymbol{\mu} \rVert^2 - t^2) / 2}}{(2\pi)^{(d-1)/2}} M_{d-1}(t),\\M_1(t) = t\, \Phi(t) + \phi(t),\\M_2(t) = t\, \phi(t) + (1 + t^2)\, \Phi(t).\end{aligned}\end{align} \]

For \(\boldsymbol{\mu} \ne 0\), the intrinsic (Fréchet) mean direction and mode are both \(\boldsymbol{\mu} / \lVert \boldsymbol{\mu} \rVert\). For \(\boldsymbol{\mu} = 0\), the distribution is uniform on the sphere and has no unique mean direction or mode.

To use this distribution with autoguides and HMC, use handlers.reparam with a ProjectedNormalReparam reparametrizer in the model, e.g.:

@handlers.reparam(config={"direction": ProjectedNormalReparam()})
def model():
    direction = numpyro.sample("direction",
                               ProjectedNormal(zeros(3)))
    ...
[1] D. Hernandez-Stumpfhauser, F.J. Breidt, M.J. van der Woerd (2017)

“The General Projected Normal Distribution of Arbitrary Dimension: Modeling and Bayesian Inference” https://doi.org/10.1214/16-BA1031

Parameters:
  • concentration – Mean vector \(\boldsymbol{\mu} \in \mathbb{R}^d\) of the isotropic normal distribution before projection.

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration': RealVector(Real(), 1)}
reparametrized_params: list[str] = ['concentration']
support = Sphere()
property mean: Array

Note this is the mean in the sense of a centroid in the submanifold that minimizes expected squared geodesic distance.

property mode: Array

Mode direction for nonzero concentration.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array[source]

Evaluate the log probability density at value.

This method implements the closed forms described above for event dimensions 2 and 3 only.

Parameters:
  • value – Point on support at which to evaluate the log PDF.

  • intermediates – Not used.

Returns:

Log probability density under the projected normal distribution.

classmethod infer_shapes(concentration: tuple[int, ...]) → tuple[tuple[int, ...], tuple[int, ...]][source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters:
  • *args – Positional args replacing each input arg with a tuple representing the sizes of each tensor input.

  • **kwargs – Keywords mapping name of input arg to tuple representing the sizes of each tensor input.

Returns:

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type:

tuple

SineBivariateVonMises

class SineBivariateVonMises(phi_loc: Array | ndarray | bool | number | bool | int | float | complex, psi_loc: Array | ndarray | bool | number | bool | int | float | complex, phi_concentration: Array | ndarray | bool | number | bool | int | float | complex, psi_concentration: Array | ndarray | bool | number | bool | int | float | complex, correlation: Array | ndarray | bool | number | bool | int | float | complex | None = None, weighted_correlation: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None)[source]

Bases: Distribution

Unimodal distribution of two dependent angles on the 2-torus (\(S^1 \otimes S^1\)) given by

\[C^{-1}\exp(\kappa_1\cos(x_1-\mu_1) + \kappa_2\cos(x_2 -\mu_2) + \rho\sin(x_1 - \mu_1)\sin(x_2 - \mu_2))\]

and

\[C = (2\pi)^2 \sum_{i=0} {2i \choose i} \left(\frac{\rho^2}{4\kappa_1\kappa_2}\right)^i I_i(\kappa_1)I_i(\kappa_2),\]

where \(I_i(\cdot)\) is the modified bessel function of first kind, mu’s are the locations of the distribution, kappa’s are the concentration and rho gives the correlation between angles \(x_1\) and \(x_2\). This distribution is helpful for modeling coupled angles such as torsion angles in peptide chains.

The density is unimodal when \(\rho^2 < \kappa_1\kappa_2\) and bimodal when \(\rho^2 > \kappa_1\kappa_2\) [1]. Passing weighted_correlation \(w \in [-1, 1]\) sets \(\rho = w\sqrt{\kappa_1\kappa_2}\), so \(|w| < 1\) guarantees unimodality.

The marginal density of the first angle and the conditional of the second angle, which sample uses, are

\[f(\phi) \propto \exp\big(\kappa_1 \cos(\phi - \mu_1)\big)\, I_0\!\left(\sqrt{\kappa_2^2 + \rho^2 \sin^2(\phi - \mu_1)}\right), \qquad \psi \mid \phi \sim \mathrm{VonMises}\!\left(\mu_2 + \beta(\phi),\ \alpha(\phi)\right),\]

with \(\alpha(\phi) = \sqrt{\kappa_2^2 + \rho^2\sin^2(\phi - \mu_1)}\) and \(\beta(\phi) = \arctan\!\big(\tfrac{\rho}{\kappa_2}\sin(\phi - \mu_1)\big)\). sample draws \(\phi\) by rejection sampling from an angular central Gaussian envelope (Kent, Ganeiber & Mardia, 2018; see sample()), running at most max_sample_iter (1000) rounds, and then draws \(\psi\) from the conditional.

Note

norm_const evaluates \(\log C\) with the series truncated at 50 terms and \(\rho^2\) clipped from below at the dtype tiny before taking logarithms. mean returns the locations \((\mu_1, \mu_2)\) wrapped to \([-\pi, \pi)\); by the point symmetry of the density about \((\mu_1, \mu_2)\) this is the circular mean in both regimes, but in the bimodal regime it is a saddle point rather than a mode. variance is not implemented. If the rejection sampler has not accepted an entry after max_sample_iter (1000) rounds, that entry is not resampled: its \(\phi\) silently falls back to \(\mu_1\) (the zero initial state of the loop) and \(\psi\) is drawn from the conditional at that value.

To infer parameters, use NUTS or HMC with priors that avoid parameterizations where the distribution becomes bimodal; see note below.

Note

Sample efficiency drops as

\[\frac{\rho^2}{\kappa_1\kappa_2} \rightarrow 1\]

because the distribution becomes increasingly bimodal. To avoid inefficient sampling use the weighted_correlation parameter with a skew away from one (e.g., TransformedDistribution(Beta(5,5), AffineTransform(loc=-1, scale=2))). The weighted_correlation should be in [-1,1].

Note

The correlation and weighted_correlation params are mutually exclusive.

Note

In the context of SVI, this distribution can be used as a likelihood but not for latent variables.

Note

Normalization remains accurate for concentrations up to 10,000. Unlike Pyro, there is no assertion to verify this during initialization, as JIT-compilation would invalidate such a check.

References
  1. Singh, H., Hnizdo, V., & Demchuk, E. (2002). Probabilistic model for two dependent circular variables. Biometrika, 89(3), 719–723.

Parameters:
  • phi_loc (np.ndarray) – location of first angle

  • psi_loc (np.ndarray) – location of second angle

  • phi_concentration (np.ndarray) – concentration of first angle

  • psi_concentration (np.ndarray) – concentration of second angle

  • correlation (np.ndarray) – correlation between the two angles

  • weighted_correlation (np.ndarray) – set correlation to weighted_corr * sqrt(phi_conc*psi_conc) to avoid bimodality (see note). The weighted_correlation should be in [-1,1].

arg_constraints: dict[str, Any] = {'correlation': Real(), 'phi_concentration': Positive(lower_bound=0.0), 'phi_loc': Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793), 'psi_concentration': Positive(lower_bound=0.0), 'psi_loc': Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793)}
support = IndependentConstraint(Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793), 1)
max_sample_iter = 1000
norm_const() → Array[source]
log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]
** References: **
  1. A New Unified Approach for the Simulation of a Wide Class of Directional Distributions John T. Kent, Asaad M. Ganeiber & Kanti V. Mardia (2018)

property mean: Array

Computes circular mean of distribution. Note: same as location when mapped to support [-pi, pi]

SineSkewed

class SineSkewed(base_dist: Distribution, skewness: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Sine-skewing [1] is a procedure for producing a distribution that breaks pointwise symmetry on a torus distribution. The new distribution is called the Sine Skewed X distribution, where X is the name of the (symmetric) base distribution. Torus distributions are distributions with support on products of circles (i.e., \(\otimes S^1\) where \(S^1 = [-pi,pi)\)). So, a 0-torus is a point, the 1-torus is a circle, and the 2-torus is commonly associated with the donut shape.

Let \(f\) be the density of base_dist on the \(d\)-torus, symmetric about its location \(\boldsymbol\mu\) (base_dist.mean), and let \(\boldsymbol\lambda \in \mathbb{R}^d\) be the skewness with \(\sum_{i=1}^{d} |\lambda_i| \le 1\). The sine skewed density is

\[p(\mathbf{x} \mid \boldsymbol\lambda) = f(\mathbf{x}) \left(1 + \sum_{i=1}^{d} \lambda_i \sin(x_i - \mu_i)\right), \qquad \mathbf{x} \in [-\pi, \pi)^d ,\]

so that log_prob is the base log density plus \(\log\big(1 + \sum_i \lambda_i \sin(x_i - \mu_i)\big)\). Normalization is preserved because \(f\) is symmetric about \(\boldsymbol\mu\) and \(\sin\) is odd, so every \(\int f(\mathbf{x})\sin(x_i - \mu_i)\, d\mathbf{x}\) vanishes; the \(\ell_1\) constraint on \(\boldsymbol\lambda\) keeps the bracket non-negative. Sampling follows Section 2.3 of [1]: draw \(\mathbf{Y} \sim f\) and \(U \sim \mathrm{Uniform}(0, 1)\), and return \(\mathbf{Y}\) if \(U \le \tfrac12\big(1 + \sum_i \lambda_i \sin(Y_i - \mu_i)\big)\), otherwise the reflection \(2\boldsymbol\mu - \mathbf{Y}\); the result is wrapped to \([-\pi, \pi)^d\).

The sine skewed X distribution is parameterized by a weight parameter for each dimension of the event of X. For example with a von Mises distribution over a circle (1-torus), the sine skewed von Mises distribution has one skew parameter. The skewness parameters can be inferred using HMC or NUTS. For example, the following will produce a prior over skewness for the 2-torus,:

@numpyro.handlers.reparam(config={'phi_loc': CircularReparam(), 'psi_loc': CircularReparam()})
def model(obs):
    # Sine priors
    phi_loc = numpyro.sample('phi_loc', VonMises(pi, 2.))
    psi_loc = numpyro.sample('psi_loc', VonMises(-pi / 2, 2.))
    phi_conc = numpyro.sample('phi_conc', Beta(1., 1.))
    psi_conc = numpyro.sample('psi_conc', Beta(1., 1.))
    corr_scale = numpyro.sample('corr_scale', Beta(2., 5.))

    # Skewing prior
    ball_trans = L1BallTransform()
    skewness = numpyro.sample('skew_phi', Normal(0, 0.5).expand((2,)))
    skewness = ball_trans(skewness)  # constraint sum |skewness_i| <= 1

    with numpyro.plate('obs_plate'):
        sine = SineBivariateVonMises(phi_loc=phi_loc, psi_loc=psi_loc,
                                     phi_concentration=70 * phi_conc,
                                     psi_concentration=70 * psi_conc,
                                     weighted_correlation=corr_scale)
        return numpyro.sample('phi_psi', SineSkewed(sine, skewness), obs=obs)

To ensure the skewing does not alter the normalization constant of the (sine bivariate von Mises) base distribution the skewness parameters are constraint. The constraint requires the sum of the absolute values of skewness to be less than or equal to one. We can use the L1BallTransform to achieve this.

In the context of SVI, this distribution can freely be used as a likelihood, but use as latent variables it will lead to slow inference for 2 and higher dim toruses. This is because the base_dist cannot be reparameterized.

Note

An event in the base distribution must be on a d-torus, so the event_shape must be (d,).

Note

For the skewness parameter, it must hold that the sum of the absolute value of its weights for an event must be less than or equal to one. See eq. 2.1 in [1].

Note

mean returns the base location \(\boldsymbol\mu\) (base_dist.mean), not the circular mean of the skewed distribution; variance is not implemented. The base distribution must expose mean, which is used as the symmetry center, and must be symmetric about it for the density above to be normalized. When validation is enabled, the checks performed by this class itself only warn on values outside the support of this distribution or of the base distribution; however, a base_dist constructed with validation enabled (the default) still masks out-of-support values to \(-\infty\) inside its own log_prob, and that value is what log_prob returns.

References
  1. Sine-skewed toroidal distributions and their application in protein bioinformatics

    Ameijeiras-Alonso, J., Ley, C. (2019)

Parameters:
  • base_dist (numpyro.distributions.Distribution) – base density on a d-dimensional torus. Supported base distributions include: 1D VonMises, SineBivariateVonMises, 1D ProjectedNormal, and Uniform (-pi, pi).

  • skewness (jax.numpy.array) – skewness of the distribution.

arg_constraints: dict[str, Any] = {'skewness': L1Ball()}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'skewness')
support = IndependentConstraint(Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793), 1)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex, intermediates: list[Any] | None = None) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the base distribution

VonMises

class VonMises(loc: Array | ndarray | bool | number | bool | int | float | complex, concentration: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

The von Mises distribution (circular normal), a continuous distribution on the circle parameterized by location \(\mu\) and concentration \(\kappa > 0\). It is the circular analogue of the Normal distribution and concentrates around \(\mu\) as \(\kappa\) grows.

The Probability Density Function (PDF) is:

\[f(x \mid \mu, \kappa) = \frac{\exp\!\bigl(\kappa \cos(x - \mu)\bigr)}{2\pi\, I_{0}(\kappa)}, \quad x \in [-\pi, \pi]\]

where \(\mu \in \mathbb{R}\) is the location (loc), \(\kappa > 0\) is the concentration (concentration), and \(I_{0}\) is the modified Bessel function of the first kind of order zero. The closed interval matches support (circular). The density is \(2\pi\)-periodic in \(x\), and log_prob() wraps value modulo \(2\pi\). The implementation evaluates the log-density with the exponentially scaled Bessel \(I_{0}^{e}(\kappa) = I_{0}(\kappa)\,e^{-\kappa}\) for numerical stability.

This distribution is supported by a circular constraint from -pi to +pi. By default, the circular support behaves like constraints.interval(-math.pi, math.pi). To avoid issues at the boundaries of this interval during sampling, you should reparameterize this distribution using handlers.reparam with a CircularReparam reparametrizer in the model, e.g.:

@handlers.reparam(config={"direction": CircularReparam()})
def model():
    direction = numpyro.sample("direction", VonMises(0.0, 4.0))
    ...
Parameters:
  • loc – Location (mean direction) \(\mu \in \mathbb{R}\); only \(\mu \bmod 2\pi\) matters.

  • concentration – Concentration \(\kappa > 0\).

  • validate_args – If True, enforce domain constraints during initialization.

arg_constraints: dict[str, Any] = {'concentration': Positive(lower_bound=0.0), 'loc': Real()}
reparametrized_params: list[str] = ['loc']
support = Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Draw samples by generating a centered von Mises variate and shifting by loc, then wrapping into \([-\pi, \pi]\).

Parameters:
  • key – A JAX PRNG key.

  • sample_shape – Sample dimensions to prepend to the batch shape.

Returns:

Circular samples in \([-\pi, \pi]\) (endpoint \(-\pi\) is reachable).

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluate the log probability density function at value:

\[\ln f(x \mid \mu, \kappa) = \kappa\bigl(\cos(x - \mu) - 1\bigr) - \log(2\pi) - \log I_{0}^{e}(\kappa)\]

which equals \(\kappa\cos(x-\mu) - \log(2\pi) - \log I_{0}(\kappa)\).

Parameters:

value – Angle \(x\) at which to evaluate the log PDF.

Returns:

Log probability density under the von Mises distribution.

property mean: Array

Circular mean of the von Mises distribution, equal to loc wrapped into \([-\pi, \pi]\):

\[\mathbb{E}_{\mathrm{circ}}[X] = ((\mu + \pi) \bmod 2\pi) - \pi\]
property variance: Array

Circular variance of the von Mises distribution:

\[\mathrm{Var}_{\mathrm{circ}}(X) = 1 - \frac{I_{1}(\kappa)}{I_{0}(\kappa)} = 1 - \frac{I_{1}^{e}(\kappa)}{I_{0}^{e}(\kappa)}\]

where \(I_{1}\) is the modified Bessel function of the first kind of order one (evaluated via its exponentially scaled form).

Truncated Distributions

DoublyTruncatedPowerLaw

class DoublyTruncatedPowerLaw(alpha: Array | ndarray | bool | number | bool | int | float | complex, low: Array | ndarray | bool | number | bool | int | float | complex, high: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Power law distribution with \(\alpha\) index, and lower and upper bounds. We can define the power law distribution as,

\[f(x; \alpha, a, b) = \frac{x^{\alpha}}{Z(\alpha, a, b)}, \qquad a \leq x \leq b,\]

where, \(a\) and \(b\) are the lower and upper bounds respectively, with \(0 \leq a < b\) (and \(a > 0\) when \(\alpha \leq -1\), otherwise \(Z\) diverges), and \(Z(\alpha, a, b)\) is the normalization constant. It is defined as,

\[\begin{split}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}\end{split}\]

The cdf is

\[\begin{split}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}\end{split}\]

and the quantile function is

\[\begin{split}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}\end{split}\]

Samples are drawn by inverse-cdf sampling. The raw moments are

\[\begin{split}\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}\end{split}\]
Parameters:
  • alpha – index \(\alpha\) of the power law distribution

  • low – lower bound \(a\) of the distribution

  • high – upper bound \(b\) of the distribution

Note

The \(\alpha = -1\) branch is selected by exact floating-point equality. log_prob, cdf and icdf carry custom JVP rules; at exactly \(\alpha = -1\) the \(\alpha\)-derivative is approximated by the average of the \(\alpha \ne -1\) closed form evaluated at \(\alpha \pm 10^{-3}\). cdf is clipped to \([0, 1]\). mean and variance are not implemented (use the moment formula above).

arg_constraints: dict[str, Any] = {'alpha': Real(), 'high': GreaterThan(lower_bound=0), 'low': GreaterThanEq(lower_bound=0)}
reparametrized_params: list[str] = ['alpha', 'low', 'high']
pytree_data_fields: tuple[str, ...] = ('alpha', 'low', 'high', '_support')
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Log probability density for \(a \leq x \leq b\).

For \(\alpha \ne -1\):

\[\log\left(\frac{(\alpha + 1)x^\alpha}{b^{\alpha + 1} - a^{\alpha + 1}}\right)\]

For \(\alpha = -1\):

\[-\log(x) - \log\left(\log(b) - \log(a)\right)\]

Derivations are calculated by Wolfram Alpha via the Jacobian matrix accordingly.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Cumulative distribution function for \(a \leq x \leq b\).

For \(\alpha \ne -1\):

\[\frac{x^{\alpha + 1} - a^{\alpha + 1}}{b^{\alpha + 1} - a^{\alpha + 1}}\]

For \(\alpha = -1\):

\[\frac{\log(x) - \log(a)}{\log(b) - \log(a)}\]

Derivations are calculated by Wolfram Alpha via the Jacobian matrix accordingly.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Inverse cumulative distribution function for \(0 \leq q \leq 1\).

For \(\alpha = -1\):

\[a \left(\frac{b}{a}\right)^{q}\]

For \(\alpha \ne -1\):

\[\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.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

LeftTruncatedDistribution

class LeftTruncatedDistribution(base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT, low: Array | ndarray | bool | number | bool | int | float | complex = 0.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A symmetric location-scale base distribution \(f\) truncated from below at low.

\[p(x \mid a) = \frac{f(x)}{1 - F(a)}, \qquad x \geq a,\]

where \(F\) is the cdf of the base distribution and \(a\) is low.

Parameters:

Note

mean and variance are only computed for a Normal base; a Cauchy base returns nan and any other base raises NotImplementedError.

arg_constraints: dict[str, Any] = {'low': LessThan(upper_bound=inf)}
reparametrized_params: list[str] = ['low']
supported_types = (<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'>, <class 'numpyro.distributions.continuous.StudentT'>)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'low', '_support')
base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

LeftTruncatedGamma

class LeftTruncatedGamma(base_dist: Gamma, low: Array | ndarray | bool | number | bool | int | float | complex = 0.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Gamma distribution truncated from below at low.

\[f(x \mid \alpha, \lambda, a) = \frac{ \mathrm{Gamma}(x \mid \alpha, \lambda) }{ Q(\alpha, \lambda a) }, \qquad x \geq a,\]

where \(Q(\alpha, z)\) is the regularized upper incomplete gamma function (gammaincc()). Taking the normalizer from the upper tail keeps it accurate however far into the tail low sits.

Parameters:
  • base_dist – a Gamma instance.

  • 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: dict[str, Any] = {'low': GreaterThanEq(lower_bound=0.0)}
reparametrized_params: list[str] = ['low']
supported_types = (<class 'numpyro.distributions.continuous.Gamma'>,)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'low', '_support')
base_dist: Gamma
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

LowerTruncatedPowerLaw

class LowerTruncatedPowerLaw(alpha: Array | ndarray | bool | number | bool | int | float | complex, low: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool | None = None)[source]

Bases: Distribution

Lower truncated power law distribution with \(\alpha\) index. We can define the power law distribution as,

\[f(x; \alpha, a) = (-\alpha-1)a^{-\alpha - 1}x^{\alpha}, \qquad x > a > 0, \qquad \alpha < -1,\]

where, \(a\) is the lower bound, so that

\[\log f(x; \alpha, a) = \alpha \log x + \log(-\alpha - 1) - (1 + \alpha) \log a.\]

The cdf of the distribution is given by,

\[F(x; \alpha, a) = 1 - \left(\frac{x}{a}\right)^{1+\alpha},\]

and the quantile function by

\[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,

\[\begin{split}E[X^k] = \begin{cases} \frac{-\alpha-1}{-\alpha-1-k}a^k & \text{if } k < -\alpha-1, \\ \infty & \text{otherwise}. \end{cases}\end{split}\]

This is the same law as Pareto with scale \(= a\) and alpha \(= -\alpha - 1\).

Parameters:
  • alpha – index \(\alpha < -1\) of the power law distribution

  • low – lower bound \(a > 0\) of the distribution

Note

cdf returns \(0\) for \(x \leq a\); icdf returns nan outside \([0, 1]\). mean and variance are not implemented even though the moment formula above is available.

arg_constraints: dict[str, Any] = {'alpha': LessThan(upper_bound=-1.0), 'low': GreaterThan(lower_bound=0.0)}
reparametrized_params: list[str] = ['alpha', 'low']
pytree_data_fields: tuple[str, ...] = ('alpha', 'low', '_support')
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

RightTruncatedDistribution

class RightTruncatedDistribution(base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT, high: Array | ndarray | bool | number | bool | int | float | complex = 0.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A symmetric location-scale base distribution \(f\) truncated from above at high.

\[p(x \mid b) = \frac{f(x)}{F(b)}, \qquad x \leq b,\]

where \(F\) is the cdf of the base distribution and \(b\) is high.

Parameters:

Note

mean and variance are only computed for a Normal base; a Cauchy base returns nan and any other base raises NotImplementedError.

arg_constraints: dict[str, Any] = {'high': GreaterThan(lower_bound=-inf)}
reparametrized_params: list[str] = ['high']
supported_types = (<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'>, <class 'numpyro.distributions.continuous.StudentT'>)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'high', '_support')
base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

RightTruncatedGamma

class RightTruncatedGamma(base_dist: Gamma, high: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Gamma distribution truncated from above at high.

\[f(x \mid \alpha, \lambda, b) = \frac{ \mathrm{Gamma}(x \mid \alpha, \lambda) }{ P(\alpha, \lambda b) }, \qquad 0 < x \leq b,\]

where \(P(\alpha, z)\) is the regularized lower incomplete gamma function (gammainc()).

The support is closed at zero, so log_prob(0.) is +inf when concentration < 1, where the density genuinely diverges. The base Gamma has an open support and masks that point instead; matching it would need a half-open interval constraint, which does not exist yet (open_interval() would also wrongly exclude high).

Parameters:
  • base_dist – a Gamma instance.

  • 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: dict[str, Any] = {'high': Positive(lower_bound=0.0)}
reparametrized_params: list[str] = ['high']
supported_types = (<class 'numpyro.distributions.continuous.Gamma'>,)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'high', '_support')
base_dist: Gamma
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

TruncatedCauchy

class TruncatedCauchy(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, low: Array | ndarray | bool | number | bool | int | float | complex | None = None, high: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None)[source]

Bases:

A Cauchy distribution truncated to [low, high].

With location \(\mu\), scale \(\gamma\), and bounds \(a\) (low) and \(b\) (high), the density is

\[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 \(F(x) = \frac{1}{2} + \frac{1}{\pi}\arctan\frac{x - \mu}{\gamma}\); an omitted bound contributes \(\arctan(\pm\infty) = \pm\pi/2\). The cdf is

\[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 TruncatedDistribution() applied to Cauchy(loc, scale), so it returns a LeftTruncatedDistribution, RightTruncatedDistribution or TwoSidedTruncatedDistribution depending on which bounds are given, or the plain Cauchy when neither is.

Parameters:
  • loc – location \(\mu\) of the base Cauchy distribution.

  • scale – scale \(\gamma > 0\) of the base Cauchy distribution.

  • low – lower truncation point, or None to not truncate from below.

  • 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.

TruncatedDistribution

TruncatedDistribution(base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT, low: Array | ndarray | bool | number | bool | int | float | complex | None = None, high: Array | ndarray | bool | number | bool | int | float | complex | None = None, *, validate_args: bool | None = None)[source]

Truncate a symmetric location-scale distribution to [low, high].

If the base distribution has density \(f\) and cdf \(F\), the truncated density is

\[p(x \mid a, b) = \frac{f(x)}{F(b) - F(a)}, \qquad a \leq x \leq b,\]

where \(a\) is low and \(b\) is high; an omitted bound contributes \(F(a) = 0\) or \(F(b) = 1\). The cdf and inverse cdf are

\[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 LeftTruncatedDistribution (low only), a RightTruncatedDistribution (high only) or a TwoSidedTruncatedDistribution (both).

Parameters:
  • 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.

  • 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.

  • 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:

>>> 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'

TruncatedGamma

TruncatedGamma(concentration: Array | ndarray | bool | number | bool | int | float | complex = 1.0, rate: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, low: Array | ndarray | bool | number | bool | int | float | complex | None = None, high: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None)[source]

A Gamma distribution truncated to [low, high].

With the base density

\[\mathrm{Gamma}(x \mid \alpha, \lambda) = \frac{\lambda^\alpha}{\Gamma(\alpha)}\, x^{\alpha - 1} e^{-\lambda x}, \qquad x > 0,\]

and bounds \(a\) (low) and \(b\) (high), the truncated density is

\[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 \(P(\alpha, z)\) is the regularized lower incomplete gamma function (gammainc()); an omitted bound contributes \(P(\alpha, 0) = 0\) or \(P(\alpha, \infty) = 1\).

Depending on which bounds are given this returns the plain Gamma (neither), a LeftTruncatedGamma (low only), a RightTruncatedGamma (high only) or a TwoSidedTruncatedGamma (both). See those classes for how the normalizer is evaluated in the tails and for the icdf algorithm.

Parameters:
  • concentration – concentration parameter \(\alpha\) of the base Gamma distribution.

  • rate – rate parameter \(\lambda\) of the base distribution.

  • low – the value which is used to truncate the base distribution from below. Setting this parameter to None to not truncate from below.

  • high – the value which is used to truncate the base distribution from above. Setting this parameter to None to not truncate from above.

Example:

>>> 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)

TruncatedNormal

class TruncatedNormal(loc: Array | ndarray | bool | number | bool | int | float | complex = 0.0, scale: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, low: Array | ndarray | bool | number | bool | int | float | complex | None = None, high: Array | ndarray | bool | number | bool | int | float | complex | None = None, validate_args: bool | None = None)[source]

Bases:

A Normal distribution truncated to [low, high].

With \(\alpha = (a - \mu) / \sigma\) and \(\beta = (b - \mu) / \sigma\) for bounds \(a\) (low) and \(b\) (high), and \(Z = \Phi(\beta) - \Phi(\alpha)\), the density is

\[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 \(\phi\) and \(\Phi\) are the standard normal pdf and cdf. An omitted bound contributes \(\alpha = -\infty\) or \(\beta = \infty\), with \(\phi(\pm\infty) = 0\), \(\alpha\,\phi(\alpha) \to 0\), \(\Phi(-\infty) = 0\) and \(\Phi(\infty) = 1\). The mean and variance are

\[\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 TruncatedDistribution() applied to Normal(loc, scale), so it returns a LeftTruncatedDistribution, RightTruncatedDistribution or TwoSidedTruncatedDistribution depending on which bounds are given, or the plain Normal when neither is.

Parameters:
  • loc – location \(\mu\) of the base Normal distribution.

  • scale – scale \(\sigma > 0\) of the base Normal distribution.

  • low – lower truncation point, or None to not truncate from below.

  • high – upper truncation point, or None to not truncate from above.

Example:

>>> 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'

TruncatedPolyaGamma

class TruncatedPolyaGamma(batch_shape: tuple[int, ...] = (), *, validate_args: bool | None = None)[source]

Bases: Distribution

An approximation of the Polya-Gamma distribution \(\mathrm{PG}(1, 0)\) restricted to \([0, 2.5]\).

\(X \sim \mathrm{PG}(1, 0)\) is defined by the infinite convolution of exponential variates

\[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 \(\mathbb{E}[e^{-tX}] = 1 / \cosh\!\big(\sqrt{t/2}\big)\) and \(\mathbb{E}[X] = 1/4\). Its density has the alternating series representation

\[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.\]

\(\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 \(\mathrm{PG}(1, \psi)\).

Parameters:

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 \(\frac{1}{2\pi^2}\sum_{k > 8} (k - 1/2)^{-2} \approx 0.0063\), so the sampler mean is about \(0.244\) rather than \(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 \(10^{-6}\) for \(x < 1.39\) (float32 rounding in the alternating sum adds up to about \(10^{-5}\)), about \(5 \times 10^{-3}\) at \(x = 2\) and about \(0.7\) at \(x = 2.5\), where the density is \(2.8 \times 10^{-5}\). The density is not renormalized to the support: the mass of \(\mathrm{PG}(1, 0)\) above \(2.5\) is \(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
arg_constraints: dict[str, Any] = {}
support = Interval(lower_bound=0.0, upper_bound=2.5)
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

TwoSidedTruncatedDistribution

class TwoSidedTruncatedDistribution(base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT, low: Array | ndarray | bool | number | bool | int | float | complex = 0.0, high: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A symmetric location-scale base distribution \(f\) truncated to [low, high].

\[p(x \mid a, b) = \frac{f(x)}{F(b) - F(a)}, \qquad a \leq x \leq b,\]

where \(F\) is the cdf of the base distribution, \(a\) is low and \(b\) is high.

Parameters:

Note

mean and variance are only computed for a Normal base; a Cauchy base returns nan and any other base raises NotImplementedError.

arg_constraints: dict[str, Any] = {'high': Dependent(), 'low': Dependent()}
reparametrized_params: list[str] = ['low', 'high']
supported_types = (<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'>, <class 'numpyro.distributions.continuous.StudentT'>)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'low', 'high', '_support')
base_dist: Cauchy | Laplace | Logistic | Normal | SoftLaplace | StudentT
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

TwoSidedTruncatedGamma

class TwoSidedTruncatedGamma(base_dist: Gamma, low: Array | ndarray | bool | number | bool | int | float | complex = 0.0, high: Array | ndarray | bool | number | bool | int | float | complex = 1.0, *, validate_args: bool | None = None)[source]

Bases: Distribution

A Gamma distribution truncated to the interval [low, high].

\[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 \(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 \(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 RightTruncatedGamma for why this differs from the base Gamma.

Parameters:
  • base_dist – a Gamma instance.

  • low – the value at which the base distribution is truncated from below.

  • 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: dict[str, Any] = {'high': Dependent(), 'low': Dependent()}
reparametrized_params: list[str] = ['low', 'high']
supported_types = (<class 'numpyro.distributions.continuous.Gamma'>,)
pytree_data_fields: tuple[str, ...] = ('base_dist', 'low', 'high', '_support')
base_dist: Gamma
property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

icdf(q: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The inverse cumulative distribution function of this distribution.

Parameters:

q – quantile values, should belong to [0, 1].

Returns:

the samples whose cdf values equals to q.

cdf(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

The cumulative distribution function of this distribution.

Parameters:

value – samples from this distribution.

Returns:

output of the cumulative distribution function evaluated at value.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

property mean: Array

Mean of the distribution.

property variance: Array

Variance of the distribution.

Censored Distributions

LeftCensoredDistribution

class LeftCensoredDistribution(base_dist: Distribution, censored: Array | ndarray | bool | number | bool | int | float | complex = False, *, validate_args: bool = False)[source]

Bases: Distribution

Distribution wrapper for left-censored outcomes.

This distribution augments a base distribution with left-censoring, so that the likelihood contribution depends on the censoring indicator.

Let \(f\) and \(F\) be the density and cumulative distribution function of base_dist. For a reported value \(y\) with censoring indicator \(c \in \{0, 1\}\) (censored), the likelihood is

\[p(y \mid c) = f(y)^{1 - c} \, F(y)^{c},\]

so that log_prob evaluates

\[\log p(y \mid c) = (1 - c) \log f(y) + c \log F(y).\]

When \(c = 1\) the latent event time \(T\) is only known to satisfy \(T \le y\), and the contribution is \(P(T \le y) = F(y)\).

Note

log_prob evaluates \(\log F(y)\) as log(clip(base_dist.cdf(y), 100 * tiny, 1)), where tiny is the smallest positive normal number of the value dtype, to avoid \(\log 0\). sample draws from the uncensored base distribution and ignores censored. mean and variance are not implemented. support is the support of base_dist. validate_args defaults to False; when True, the constructor evaluates base_dist.cdf once on a feasible value and raises TypeError if it is not implemented.

Parameters:
  • base_dist (numpyro.distributions.Distribution) – Parametric distribution for the uncensored values (e.g., Exponential, Weibull, LogNormal, Normal, etc.). This distribution must implement a cdf method.

  • censored (array-like of {0,1}) – Censoring indicator per observation: 0 → value is observed exactly 1 → observation is left-censored at the reported value (true value occurred on or before the reported value)

Note

The log_prob(value) method expects value to be the observed upper bound for each observation. The contribution to the log-likelihood is:

log f(value) if censored == 0 log F(value) if censored == 1

where f is the density and F the cumulative distribution function of base_dist.

This is commonly used in survival analysis, where event times are positive, but the approach is more general and can be applied to any distribution with a cumulative distribution function, regardless of support.

In R’s survival package notation, this corresponds to Surv(time, event, type = 'left').

Example:

Surv(time = c(2, 4, 6), event = c(0, 1, 0), type=’left’)

means:

subject 1 had an event exactly at t=2 subject 2 had an event before or at t=4 (left-censored) subject 3 had an event exactly at t=6

Example:

>>> from jax import numpy as jnp
>>> from numpyro import distributions as dist
>>> base = dist.LogNormal(0., 1.)
>>> surv_dist = dist.LeftCensoredDistribution(base, censored=jnp.array([0, 1, 1]))
>>> loglik = surv_dist.log_prob(jnp.array([2., 4., 6.]))
arg_constraints: dict[str, Any] = {'censored': Boolean()}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'censored', '_support')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

RightCensoredDistribution

class RightCensoredDistribution(base_dist: Distribution, censored: Array | ndarray | bool | number | bool | int | float | complex = False, *, validate_args: bool = False)[source]

Bases: Distribution

Distribution wrapper for right-censored outcomes.

This distribution augments a base distribution with right-censoring, so that the likelihood contribution depends on the censoring indicator.

Let \(f\) and \(F\) be the density and cumulative distribution function of base_dist, with survival function \(S = 1 - F\). For a reported value \(y\) with censoring indicator \(c \in \{0, 1\}\) (censored), the likelihood is

\[p(y \mid c) = f(y)^{1 - c} \, S(y)^{c},\]

so that log_prob evaluates

\[\log p(y \mid c) = (1 - c) \log f(y) + c \log\big(1 - F(y)\big).\]

When \(c = 1\) the latent event time \(T\) is only known to satisfy \(T \ge y\), and the contribution is \(P(T \ge y) = 1 - F(y)\).

Note

log_prob evaluates \(\log(1 - F(y))\) as log1p(-clip(base_dist.cdf(y), 0, 1 - eps)), where eps is the machine epsilon of the value dtype, to avoid \(\log 0\). sample draws from the uncensored base distribution and ignores censored. mean and variance are not implemented. support is the support of base_dist. validate_args defaults to False; when True, the constructor evaluates base_dist.cdf once on a feasible value and raises TypeError if it is not implemented.

Parameters:
  • base_dist (numpyro.distributions.Distribution) – Parametric distribution for the uncensored values (e.g., Exponential, Weibull, LogNormal, Normal, etc.). This distribution must implement a cdf method.

  • censored (array-like of {0,1}) – Censoring indicator per observation: 0 → value is observed exactly 1 → observation is right-censored at the reported value (true value occurred on or after the reported value)

Note

The log_prob(value) method expects value to be the observed lower bound for each observation. The contribution to the log-likelihood is:

log f(value) if censored == 0 log (1 - F(value)) if censored == 1

where f is the density and F the cumulative distribution function of base_dist.

This is commonly used in survival analysis, where event times are positive, but the approach is more general and can be applied to any distribution with a cumulative distribution function, regardless of support.

In R’s survival package notation, this corresponds to Surv(time, event, type = 'right').

Example:

Surv(time = c(5, 8, 10), event = c(1, 0, 1))

means:

subject 1 had an event at t=5 subject 2 was censored at t=8 subject 3 had an event at t=10

Example:

>>> from jax import numpy as jnp
>>> from numpyro import distributions as dist
>>> base = dist.Exponential(rate=0.1)
>>> surv_dist = dist.RightCensoredDistribution(base, censored=jnp.array([0, 1, 0]))
>>> loglik = surv_dist.log_prob(jnp.array([5., 8., 10.]))
arg_constraints: dict[str, Any] = {'censored': Boolean()}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'censored', '_support')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

IntervalCensoredDistribution

class IntervalCensoredDistribution(base_dist: Distribution, left_censored: Array | ndarray | bool | number | bool | int | float | complex, right_censored: Array | ndarray | bool | number | bool | int | float | complex, *, validate_args: bool = False)[source]

Bases: Distribution

Distribution wrapper for interval-censored outcomes.

This distribution augments a base distribution with interval censoring, so that the likelihood contribution depends on whether the observation is exactly observed, left-censored, right-censored, interval-censored, or doubly-censored (i.e., known to lie outside the observed interval).

Parameters:
  • base_dist (numpyro.distributions.Distribution) – Parametric distribution for the uncensored values (e.g., Exponential, Weibull, LogNormal, Normal, etc.). This distribution must implement a cdf method.

  • left_censored (array-like of {0,1}) – Indicator per observation: 1 → observation is left-censored at the reported upper bound 0 → not left-censored

  • right_censored (array-like of {0,1}) – Indicator per observation: 1 → observation is right-censored at the reported lower bound 0 → not right-censored

Note

The log_prob(value) method expects value to be a two-dimensional array of shape (batch_size, 2), where each row is (lower, upper). The contribution to the log-likelihood is determined as follows. With value \((l, u)\) and indicators \(\ell\) (left_censored) and \(r\) (right_censored),

\[\begin{split}\log p(l, u \mid \ell, r) = \begin{cases} \log F(u) & \ell = 1,\ r = 0 \\ \log\big(1 - F(l)\big) & \ell = 0,\ r = 1 \\ \log\big(F(u) - F(l)\big) & \ell = 0,\ r = 0,\ l < u \\ \log f(l) & \ell = 0,\ r = 0,\ l = u \\ \log\big(1 - [F(u) - F(l)]\big) & \ell = 1,\ r = 1 \end{cases}\end{split}\]

where \(f\) is the density and \(F\) the cumulative distribution function of base_dist. The five rows correspond to the event lying in \((-\infty, u]\) (left-censored), in \([l, \infty)\) (right-censored), in \((l, u]\) (interval-censored), exactly at \(l\) (point observation), or outside \((l, u]\) (doubly-censored).

This is commonly used in survival analysis, where event times are positive, but the approach is general and can be applied to any distribution with a cumulative distribution function, regardless of support.

In R’s survival package notation, this corresponds to Surv(l, r, type = 'interval2').

Example:

Surv(l = c(2, 4, 6), r = c(5, Inf, 9), type = ‘interval2’)

means:

subject 1 had an event in (2, 5] subject 2 was right-censored at 4 subject 3 had an event in (6, 9]

Note

For numerical stability, \(F(l)\) and \(F(u)\) are clipped to \([100\,\text{tiny}, 1 - \epsilon]\) (tiny the smallest positive normal number and eps the machine epsilon of the value dtype) after substituting \(F(l) = 0\) on left-censored rows and \(F(u) = 1\) on right-censored rows. The interval term is evaluated as \(\log F(u) + \log\big(1 - e^{\log F(l) - \log F(u)}\big)\), and the doubly-censored row applies log1mexp to it. The point case is detected with jnp.isclose(l, u) and only when neither indicator is set. event_shape is (2,). sample draws uncensored scalar values from base_dist (one per batch element, without the interval structure) and ignores the censoring indicators. mean and variance are not implemented. validate_args defaults to False; when True, the constructor evaluates base_dist.cdf once on a feasible value and raises TypeError if it is not implemented.

Example:

>>> from jax import numpy as jnp
>>> from numpyro import distributions as dist
>>> base = dist.Weibull(concentration=2.0, scale=3.0)
>>> left_censored = jnp.array([0, 0, 0])
>>> right_censored = jnp.array([0, 1, 0])
>>> surv_dist = dist.IntervalCensoredDistribution(base, left_censored, right_censored)
>>> values = jnp.array([
...     [2.0, 5.0],
...     [4.0, jnp.inf],
...     [6.0, 9.0],
... ])
>>> loglik = surv_dist.log_prob(values)
arg_constraints: dict[str, Any] = {'left_censored': Boolean(), 'right_censored': Boolean()}
pytree_data_fields: tuple[str, ...] = ('base_dist', 'left_censored', 'right_censored', '_support')
sample(key: Array | None, sample_shape: tuple[int, ...] = ()) → Array[source]

Returns a sample from the distribution having shape given by sample_shape + batch_shape + event_shape. Note that when sample_shape is non-empty, leading dimensions (of size sample_shape) of the returned sample will be filled with iid draws from the distribution instance.

Parameters:
  • key (jax.random.key) – the rng_key key to be used for the distribution.

  • sample_shape (tuple) – the sample shape for the distribution.

Returns:

an array of shape sample_shape + batch_shape + event_shape

Return type:

numpy.ndarray

property support: Constraint

The support of this distribution. Subclasses can override this as a class attribute or as a property.

log_prob(value) → Array[source]

Evaluates the log probability density for a batch of samples given by value.

Parameters:
  • value – A batch of samples from the distribution.

  • intermediates – Optional intermediates computed during sampling (e.g. from sample_with_intermediates()) that some distributions can reuse to avoid recomputation.

Returns:

an array with shape value.shape[:-self.event_shape]

Return type:

ArrayLike

TensorFlow Distributions

Thin wrappers around TensorFlow Probability (TFP) distributions. For details on the TFP distribution interface, see its Distribution docs.

BijectorConstraint

class BijectorConstraint(bijector)[source]

A constraint which is codomain of a TensorFlow bijector.

Parameters:

bijector (Bijector) – a TensorFlow bijector

BijectorTransform

class BijectorTransform(bijector)[source]

A wrapper for TensorFlow bijectors to make them compatible with NumPyro’s transforms.

Parameters:

bijector (Bijector) – a TensorFlow bijector

TFPDistribution

class TFPDistribution(batch_shape: tuple[int, ...] = (), event_shape: tuple[int, ...] = (), *, validate_args: bool | None = None)[source]

A thin wrapper for TensorFlow Probability (TFP) distributions. The constructor has the same signature as the corresponding TFP distribution.

This class can be used to convert a TFP distribution to a NumPyro-compatible one as follows:

d = TFPDistribution[tfd.Normal](0, 1)

Note that typical use cases do not require explicitly invoking this wrapper, since NumPyro wraps TFP distributions automatically under the hood in model code, e.g.:

from tensorflow_probability.substrates.jax import distributions as tfd

def model():
    numpyro.sample("x", tfd.Normal(0, 1))

Constraints

Constraint

class Constraint[source]

Bases: Generic[NumLikeT]

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

is_discrete: bool = False
event_dim: int = 0
tree_flatten()[source]
check(value: NumLikeT) → Array | ndarray | bool | number | bool | int | float | complex[source]

Returns a byte tensor of sample_shape + batch_shape indicating whether each event in value satisfies this constraint.

feasible_like(prototype: NumLikeT) → NumLikeT[source]

Get a feasible value which has the same shape as dtype as prototype.

eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]
classmethod tree_unflatten(aux_data, params)[source]

boolean

boolean = Boolean()

circular

circular = Circular(lower_bound=-3.141592653589793, upper_bound=3.141592653589793)

corr_cholesky

corr_cholesky = CorrCholesky()

corr_matrix

corr_matrix = CorrMatrix()

dependent

dependent: _Dependent = Dependent()

Placeholder for variables whose support depends on other variables. These variables obey no simple coordinate-wise constraints.

Parameters:
  • is_discrete (bool) – Optional value of .is_discrete in case this can be computed statically. If not provided, access to the .is_discrete attribute will raise a NotImplementedError.

  • event_dim (int) – Optional value of .event_dim in case this can be computed statically. If not provided, access to the .event_dim attribute will raise a NotImplementedError.

extended_real

extended_real = ExtendedReal()

The extended real line [-inf, inf]: every value except NaN.

For parameters whose link function has a limit at infinity, such as the logits of a Bernoulli (sigmoid(-inf) == 0) or the bound of a truncated distribution. Not a valid support: it has no bijector.

greater_than

greater_than(lower_bound: ndarray | Array | number | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

integer_interval

integer_interval(lower_bound: ndarray | Array | number | int | float | complex, upper_bound: ndarray | Array | number | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

integer_greater_than

integer_greater_than(lower_bound: ndarray | Array | number | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

interval

interval(lower_bound: ndarray | Array | number | int | float | complex, upper_bound: ndarray | Array | number | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

l1_ball

l1_ball(x: ndarray | Array | number | int | float | complex) → Array | ndarray | bool | number | bool | int | float | complex

Constrain to the L1 ball of any dimension.

less_than

less_than(upper_bound: ndarray | Array | number | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

lower_cholesky

lower_cholesky = LowerCholesky()

multinomial

multinomial(upper_bound: Array | ndarray | bool | number | bool | int | float | complex) → None

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

nonnegative_integer

nonnegative_integer = IntegerNonnegative(lower_bound=0)

ordered_vector

ordered_vector = OrderedVector()

positive

positive = Positive(lower_bound=0.0)

positive_definite

positive_definite = PositiveDefinite()

positive_integer

positive_integer = IntegerPositive(lower_bound=1)

positive_ordered_vector

positive_ordered_vector = PositiveOrderedVector()

Constrains to a positive real-valued tensor where the elements are monotonically increasing along the event_shape dimension.

real

real = Real()

real_vector

real_vector = RealVector(Real(), 1)

scaled_unit_lower_cholesky

scaled_unit_lower_cholesky = ScaledUnitLowerCholesky()

softplus_positive

softplus_positive = SoftplusPositive(lower_bound=0.0)

softplus_lower_cholesky

softplus_lower_cholesky = SoftplusLowerCholesky()

simplex

simplex = Simplex()

softmax_logits

softmax_logits = SoftmaxLogits()

Vectors whose softmax is well defined: no NaN, no +inf (the normalizer would be inf - inf) and at least one finite entry (an all -inf vector has no normalizer). A -inf entry is a zero-probability category, the logit-space counterpart of a zero on the simplex. Not a valid support: it has no bijector.

sphere

sphere = Sphere()

Constrain to the Euclidean sphere of any dimension.

unit_interval

unit_interval = UnitInterval(lower_bound=0.0, upper_bound=1.0)

zero_sum

zero_sum = <class 'numpyro.distributions.constraints._ZeroSum'>

Abstract base class for constraints.

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

Transforms

biject_to

biject_to(constraint)

Transform

class Transform[source]

Bases: Generic[NumLikeT]

property domain: Constraint
property codomain: Constraint
tree_flatten()[source]
property inv: Transform
log_abs_det_jacobian(x: NumLikeT, y: NumLikeT, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
call_with_intermediates(x: NumLikeT) → Tuple[ndarray | Array | number | int | float | complex, Any | None][source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

property sign: ndarray | Array | number | int | float | complex

Sign of the derivative of the transform if it is bijective.

classmethod tree_unflatten(aux_data, params)[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

AbsTransform

class AbsTransform[source]

Bases: ParameterFreeTransform[ndarray | Array | number | int | float | complex]

domain = Real()
codomain = Positive(lower_bound=0.0)

AffineTransform

class AffineTransform(loc: ndarray | Array | number | int | float | complex, scale: ndarray | Array | number | int | float | complex, domain: Constraint = Real())[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

Note

When scale is a JAX tracer, we always assume that scale > 0 when calculating codomain.

property domain: Constraint
property codomain: Constraint
property sign: ndarray | Array | number | int | float | complex

Sign of the derivative of the transform if it is bijective.

log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

CholeskyTransform

class CholeskyTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transform via the mapping \(y = cholesky(x)\), where x is a positive definite matrix.

domain = PositiveDefinite()
codomain = LowerCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

ComplexTransform

class ComplexTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transforms a pair of real numbers to a complex number.

domain = RealVector(Real(), 1)
codomain = Complex()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

ComposeTransform

class ComposeTransform(parts: Sequence[Transform])[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

property domain: Constraint
property codomain: Constraint
property sign: ndarray | Array | number | int | float | complex

Sign of the derivative of the transform if it is bijective.

log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
call_with_intermediates(x: ndarray | Array | number | int | float | complex) → Tuple[ndarray | Array | number | int | float | complex, Any | None][source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

CorrCholeskyTransform

class CorrCholeskyTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transforms an unconstrained real vector \(x\) with length \(D*(D-1)/2\) into the Cholesky factor of a D-dimension correlation matrix. This Cholesky factor is a lower triangular matrix with positive diagonals and unit Euclidean norm for each row. The transform is processed as follows:

  1. First we convert \(x\) into a lower triangular matrix with the following order:

\[\begin{split}\begin{bmatrix} 1 & 0 & 0 & 0 \\ x_0 & 1 & 0 & 0 \\ x_1 & x_2 & 1 & 0 \\ x_3 & x_4 & x_5 & 1 \end{bmatrix}\end{split}\]

2. For each row \(X_i\) of the lower triangular part, we apply a signed version of class StickBreakingTransform to transform \(X_i\) into a unit Euclidean length vector using the following steps:

  1. Scales into the interval \((-1, 1)\) domain: \(r_i = \tanh(X_i)\).

  2. Transforms into an unsigned domain: \(z_i = r_i^2\).

  3. Applies \(s_i = StickBreakingTransform(z_i)\).

  4. Transforms back into signed domain: \(y_i = (sign(r_i), 1) * \sqrt{s_i}\).

domain = RealVector(Real(), 1)
codomain = CorrCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

CorrMatrixCholeskyTransform

class CorrMatrixCholeskyTransform[source]

Bases: CholeskyTransform

Transform via the mapping \(y = cholesky(x)\), where x is a correlation matrix.

domain = CorrMatrix()
codomain = CorrCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

DiscreteCosineTransform

class DiscreteCosineTransform(dim: int = -1, smooth: float = 0.0)[source]

Bases: Transform[ndarray | Array]

Discrete Cosine Transform of type II.

This computes the orthonormal DCT and its inverse along a chosen axis using jax.scipy.fft.dct() and jax.scipy.fft.idct(). The Jacobian determinant is 1.

When reparameterizing variables that are approximately continuous along the time dimension, set smooth=1. For variables that are approximately continuously differentiable along the time axis, set smooth=2.

Parameters:
  • dim – Dimension along which to transform. Must be negative. This is an absolute dim counting from the right.

  • smooth – Smoothing parameter. When 0, this transforms white noise to white noise; when 1 this transforms Brownian noise to white noise; when -1 this transforms violet noise to white noise; etc. Any real number is allowed. See https://en.wikipedia.org/wiki/Colors_of_noise.

bijective = True
property domain: Constraint
property codomain: Constraint
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

ExpTransform

class ExpTransform(domain: Constraint = Real())[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

sign = 1
property domain: Constraint
property codomain: Constraint
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

HaarTransform

class HaarTransform(dim: int = -1, flip: bool = False)[source]

Bases: Transform[ndarray | Array]

Discrete Haar transform.

This computes the (orthonormal) Haar transform and its inverse along a chosen axis. The Jacobian determinant is 1. For sequences with length T not a power of two, this implementation is equivalent to a block-structured Haar transform in which block sizes decrease by factors of one half from left to right.

Parameters:
  • dim – Dimension along which to transform. Must be negative. This is an absolute dim counting from the right.

  • flip – Whether to flip the time axis before applying the Haar transform. Defaults to False.

bijective = True
property domain: Constraint
property codomain: Constraint
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

IdentityTransform

class IdentityTransform[source]

Bases: ParameterFreeTransform[ndarray | Array | number | int | float | complex]

sign = 1
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

L1BallTransform

class L1BallTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transforms an unconstrained real vector \(x\) into the unit L1 ball.

domain = RealVector(Real(), 1)
codomain = L1Ball()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

LowerCholeskyAffine

class LowerCholeskyAffine(loc: ndarray | Array, scale_tril: ndarray | Array)[source]

Bases: Transform[ndarray | Array]

Transform via the mapping \(y = loc + scale\_tril\ @\ x\).

Parameters:
  • loc – a real vector.

  • scale_tril – a lower triangular matrix with positive diagonal. May include leading batch dimensions, which are broadcast against loc and the input.

Example

>>> import jax.numpy as jnp
>>> from numpyro.distributions.transforms import LowerCholeskyAffine
>>> base = jnp.ones(2)
>>> loc = jnp.zeros(2)
>>> scale_tril = jnp.array([[0.3, 0.0], [1.0, 0.5]])
>>> affine = LowerCholeskyAffine(loc=loc, scale_tril=scale_tril)
>>> affine(base)
Array([0.3, 1.5], dtype=float32)
domain = RealVector(Real(), 1)
codomain = RealVector(Real(), 1)
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

LowerCholeskyTransform

class LowerCholeskyTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transform a real vector to a lower triangular cholesky factor, where the strictly lower triangular submatrix is unconstrained and the diagonal is parameterized with an exponential transform.

domain = RealVector(Real(), 1)
codomain = LowerCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

OrderedTransform

class OrderedTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transform a real vector to an ordered vector.

References:

  1. Stan Reference Manual v2.20, section 10.6, Stan Development Team

Example

>>> import jax.numpy as jnp
>>> from numpyro.distributions.transforms import OrderedTransform
>>> base = jnp.ones(3)
>>> transform = OrderedTransform()
>>> assert jnp.allclose(transform(base), jnp.array([1., 3.7182817, 6.4365635]), rtol=1e-3, atol=1e-3)
domain = RealVector(Real(), 1)
codomain = OrderedVector()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

PackRealFastFourierCoefficientsTransform

class PackRealFastFourierCoefficientsTransform(transform_shape: tuple[int, ...] | None = None)[source]

Bases: Transform[ndarray | Array]

Transform a real vector to complex coefficients of a real fast Fourier transform.

Parameters:

transform_shape – Shape of the real vector, defaults to the input size.

domain = RealVector(Real(), 1)
codomain = IndependentConstraint(Complex(), 1)
shape: tuple[int, ...] | None
tree_flatten()[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → Array[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

PermuteTransform

class PermuteTransform(permutation: ndarray | Array)[source]

Bases: Transform[ndarray | Array]

domain = RealVector(Real(), 1)
codomain = RealVector(Real(), 1)
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

PowerTransform

class PowerTransform(exponent: ndarray | Array | number | int | float | complex)[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

domain = Positive(lower_bound=0.0)
codomain = Positive(lower_bound=0.0)
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]
property sign: ndarray | Array | number | int | float | complex

Sign of the derivative of the transform if it is bijective.

RealFastFourierTransform

class RealFastFourierTransform(transform_shape: tuple[int, ...] | None = None, transform_ndims: int = 1)[source]

Bases: Transform[ndarray | Array]

N-dimensional discrete fast Fourier transform for real input.

Parameters:
  • transform_shape – Length of each transformed axis to use from the input, defaults to the input size.

  • transform_ndims – Number of trailing dimensions to transform.

forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
tree_flatten()[source]
property domain: Constraint
property codomain: Constraint
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

RecursiveLinearTransform

class RecursiveLinearTransform(transition_matrix: ndarray | Array, initial_value: ndarray | Array | None = None)[source]

Bases: Transform[ndarray | Array]

Apply a linear transformation recursively such that \(y_t = A y_{t - 1} + x_t\) for \(t > 0\), where \(x_t\) and \(y_t\) are vectors and \(A\) is a square transition matrix. The series is initialized by \(y_0 = 0\).

Parameters:

transition_matrix – Square transition matrix \(A\) for successive states or a batch of transition matrices.

Example:

>>> from jax import random
>>> from jax import numpy as jnp
>>> import numpyro
>>> from numpyro import distributions as dist
>>>
>>> def cauchy_random_walk():
...     return numpyro.sample(
...         "x",
...         dist.TransformedDistribution(
...             dist.Cauchy(0, 1).expand([10, 1]).to_event(1),
...             dist.transforms.RecursiveLinearTransform(jnp.eye(1)),
...         ),
...     )
>>>
>>> numpyro.handlers.seed(cauchy_random_walk, 0)().shape
(10, 1)
>>>
>>> def rocket_trajectory():
...     scale = numpyro.sample(
...         "scale",
...         dist.HalfCauchy(1).expand([2]).to_event(1),
...     )
...     transition_matrix = jnp.array([[1, 1], [0, 1]])
...     return numpyro.sample(
...         "x",
...         dist.TransformedDistribution(
...             dist.Normal(0, scale).expand([10, 2]).to_event(1),
...             dist.transforms.RecursiveLinearTransform(transition_matrix),
...         ),
...     )
>>>
>>> numpyro.handlers.seed(rocket_trajectory, 0)().shape
(10, 2)
domain = RealMatrix(Real(), 2)
codomain = RealMatrix(Real(), 2)
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

ScaledUnitLowerCholeskyTransform

class ScaledUnitLowerCholeskyTransform[source]

Bases: LowerCholeskyTransform

Like LowerCholeskyTransform this Transform transforms a real vector to a lower triangular cholesky factor. However it does so via a decomposition

\(y = loc + unit\_scale\_tril\ @\ scale\_diag\ @\ x\).

where \(unit\_scale\_tril\) has ones along the diagonal and \(scale\_diag\) is a diagonal matrix with all positive entries that is parameterized with a softplus transform.

domain = RealVector(Real(), 1)
codomain = ScaledUnitLowerCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

SigmoidTransform

class SigmoidTransform[source]

Bases: ParameterFreeTransform[ndarray | Array | number | int | float | complex]

codomain = UnitInterval(lower_bound=0.0, upper_bound=1.0)
sign = 1
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

SimplexToOrderedTransform

class SimplexToOrderedTransform(anchor_point: Array | ndarray | bool | number | bool | int | float | complex = 0.0)[source]

Bases: Transform[ndarray | Array]

Transform a simplex into an ordered vector (via difference in Logistic CDF between cutpoints) Used in [1] to induce a prior on latent cutpoints via transforming ordered category probabilities.

Parameters:

anchor_point – Anchor point is a nuisance parameter to improve the identifiability of the transform. For simplicity, we assume it is a scalar value, but it is broadcastable x.shape[:-1]. For more details please refer to Section 2.2 in [1]

References:

  1. Ordinal Regression Case Study, section 2.2, M. Betancourt, https://betanalpha.github.io/assets/case_studies/ordinal_regression.html

Example

>>> import jax.numpy as jnp
>>> from numpyro.distributions.transforms import SimplexToOrderedTransform
>>> base = jnp.array([0.3, 0.1, 0.4, 0.2])
>>> transform = SimplexToOrderedTransform()
>>> assert jnp.allclose(transform(base), jnp.array([-0.8472978, -0.40546507, 1.3862944]), rtol=1e-3, atol=1e-3)
domain = Simplex()
codomain = OrderedVector()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

SoftplusLowerCholeskyTransform

class SoftplusLowerCholeskyTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

Transform from unconstrained vector to lower-triangular matrices with nonnegative diagonal entries. This is useful for parameterizing positive definite matrices in terms of their Cholesky factorization.

domain = RealVector(Real(), 1)
codomain = SoftplusLowerCholesky()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

SoftplusTransform

class SoftplusTransform[source]

Bases: ParameterFreeTransform[ndarray | Array | number | int | float | complex]

Transform from unconstrained space to positive domain via softplus \(y = \log(1 + \exp(x))\). The inverse is computed as \(x = \log(\exp(y) - 1)\).

domain = Real()
codomain = SoftplusPositive(lower_bound=0.0)
sign = 1
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

StickBreakingTransform

class StickBreakingTransform[source]

Bases: ParameterFreeTransform[ndarray | Array]

domain = RealVector(Real(), 1)
codomain = Simplex()
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

ZeroSumTransform

class ZeroSumTransform(transform_ndims: int = 1)[source]

Bases: Transform[ndarray | Array]

A transform that constrains an array to sum to zero, adapted from PyMC [1] as described in [2,3]

Parameters:

transform_ndims – Number of trailing dimensions to transform.

References [1] https://github.com/pymc-devs/pymc/blob/244fb97b01ad0f3dadf5c3837b65839e2a59a0e8/pymc/distributions/transforms.py#L266 [2] https://www.pymc.io/projects/docs/en/stable/api/distributions/generated/pymc.ZeroSumNormal.html [3] https://learnbayesstats.com/episode/74-optimizing-nuts-developing-zerosumnormal-distribution-adrian-seyboldt/

property domain: Constraint
property codomain: Constraint
extend_axis_rev(array: ndarray | Array, axis: int) → ndarray | Array[source]
extend_axis(array: ndarray | Array, axis: int) → ndarray | Array[source]
log_abs_det_jacobian(x: ndarray | Array, y: ndarray | Array, intermediates: Any | None = None) → Array[source]
forward_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shape of the forward computation, given the input shape. Defaults to preserving shape.

inverse_shape(shape: tuple[int, ...]) → tuple[int, ...][source]

Infers the shapes of the inverse computation, given the output shape. Defaults to preserving shape.

tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

Flows

InverseAutoregressiveTransform

class InverseAutoregressiveTransform(autoregressive_nn, log_scale_min_clip: Array | ndarray | bool | number | bool | int | float | complex = -5.0, log_scale_max_clip: Array | ndarray | bool | number | bool | int | float | complex = 3.0)[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

An implementation of Inverse Autoregressive Flow, using Eq (10) from Kingma et al., 2016,

\(\mathbf{y} = \mu_t + \sigma_t\odot\mathbf{x}\)

where \(\mathbf{x}\) are the inputs, \(\mathbf{y}\) are the outputs, \(\mu_t,\sigma_t\) are calculated from an autoregressive network on \(\mathbf{x}\), and \(\sigma_t>0\).

References

  1. Improving Variational Inference with Inverse Autoregressive Flow [arXiv:1606.04934], Diederik P. Kingma, Tim Salimans, Rafal Jozefowicz, Xi Chen, Ilya Sutskever, Max Welling

Parameters:

autoregressive_nn – an autoregressive neural network whose forward call returns a real-valued mean and log scale as a tuple

domain = RealVector(Real(), 1)
codomain = RealVector(Real(), 1)
call_with_intermediates(x: ndarray | Array | number | int | float | complex) → tuple[ndarray | Array | number | int | float | complex, Any | None][source]
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

Calculates the elementwise determinant of the log jacobian.

Parameters:
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

BlockNeuralAutoregressiveTransform

class BlockNeuralAutoregressiveTransform(bn_arn)[source]

Bases: Transform[ndarray | Array | number | int | float | complex]

An implementation of Block Neural Autoregressive flow.

References

  1. Block Neural Autoregressive Flow, Nicola De Cao, Ivan Titov, Wilker Aziz

domain = RealVector(Real(), 1)
codomain = RealVector(Real(), 1)
call_with_intermediates(x: ndarray | Array | number | int | float | complex) → tuple[ndarray | Array | number | int | float | complex, Any | None][source]
log_abs_det_jacobian(x: ndarray | Array | number | int | float | complex, y: ndarray | Array | number | int | float | complex, intermediates: Any | None = None) → ndarray | Array | number | int | float | complex[source]

Calculates the elementwise determinant of the log jacobian.

Parameters:
tree_flatten()[source]
eq(other: object, static: bool = False) → Array | ndarray | bool | number | bool | int | float | complex[source]

Utilities

log1mexp

log1mexp(x: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Numerically stable calculation of the quantity \(\log(1 - \exp(x))\), following the algorithm of Mächler 2012.

Returns -jnp.inf when x == 0 and jnp.nan when x > 0.

Parameters:

x – A number or array of numbers.

Returns:

The value of \(\log(1 - \exp(x))\).

logdiffexp

logdiffexp(a: Array | ndarray | bool | number | bool | int | float | complex, b: Array | ndarray | bool | number | bool | int | float | complex) → Array[source]

Numerically stable calculation of the quantity \(\log(\exp(a) - \exp(b))\), provided \(+\infty > a \ge b\), following the algorithm of Mächler 2012.

Returns -jnp.inf when a == b, including when a == b == -jnp.inf, since this corresponds to jnp.log(0). Returns jnp.nan when a < b or a == jnp.inf.

Parameters:
  • a – A number or array of numbers.

  • b – A number or array of numbers.

Returns:

The value of \(\log(\exp(a) - \exp(b))\).