Skip to content

Statistics

numerax.stats

Statistics submodule for numerax.

make_profile_llh

make_profile_llh(llh_fn: Callable, is_nuisance: list[bool] | ndarray, get_initial_nuisance: Callable, tol: float = 1e-06, initial_value: float = 1e-09, initial_diff: float = 1000000000.0, optimizer: GradientTransformation = _DEFAULT_OPTIMIZER) -> Callable

Factory function for creating profile likelihood functions.

Overview

Profile likelihood is a statistical technique used when dealing with nuisance parameters that are not of primary interest but are necessary for the model. This function creates an optimized profile likelihood that maximizes over nuisance parameters while keeping inference parameters fixed.

Mathematical Background

Given a likelihood function \(L(\boldsymbol{\theta}, \boldsymbol{\lambda})\) where \(\boldsymbol{\theta}\) are parameters of interest and \(\boldsymbol{\lambda}\) are nuisance parameters, the profile likelihood is:

\[L_p(\boldsymbol{\theta}) = \max_{\boldsymbol{\lambda}} L(\boldsymbol{\theta}, \boldsymbol{\lambda})\]

In practice, we work with the log-likelihood \(\ell(\boldsymbol{\theta}, \boldsymbol{\lambda}) = \log L(\boldsymbol{\theta}, \boldsymbol{\lambda})\):

\[\ell_p(\boldsymbol{\theta}) = \max_{\boldsymbol{\lambda}} \ell(\boldsymbol{\theta}, \boldsymbol{\lambda})\]

This function uses L-BFGS optimization to find the maximum likelihood estimates of nuisance parameters for each fixed value of inference parameters.

Args
  • llh_fn: Log likelihood function taking (params, *args) and returning scalar log likelihood value
  • is_nuisance: Boolean array where True indicates nuisance parameters and False indicates inference parameters
  • get_initial_nuisance: Function taking (*args) and returning initial values for nuisance parameters
  • tol: Convergence tolerance for the optimization (default: 1e-6)
  • initial_value: Initial objective value for convergence tracking (default: 1e-9)
  • initial_diff: Initial difference for convergence tracking (default: 1e9)
  • optimizer: Optax optimizer to use for maximization (default: lbfgs()). Currently tested only with the default L-BFGS optimizer
Returns

Profile likelihood function with signature: (inference_values, *args) -> (profile_llh_value, optimal_nuisance, convergence_diff, num_iterations)

Example

Consider fitting a normal distribution where we want to infer the mean \(\mu\) but treat the variance \(\sigma^2\) as a nuisance parameter:

import jax.numpy as jnp
import numerax

# Sample data
data = jnp.array([1.2, 0.8, 1.5, 0.9, 1.1, 1.3, 0.7, 1.4])


# Log likelihood for normal distribution
def normal_llh(params, data):
    mu, log_sigma = params  # Use log(sigma) for numerical stability
    sigma = jnp.exp(log_sigma)
    return jnp.sum(
        -0.5 * jnp.log(2 * jnp.pi)
        - log_sigma
        - 0.5 * ((data - mu) / sigma) ** 2
    )


# Profile over log_sigma (nuisance), infer mu
is_nuisance = [False, True]  # mu=inference, log_sigma=nuisance


def get_initial_log_sigma(data):
    # Initialize with log of sample standard deviation
    return jnp.array([jnp.log(jnp.std(data))])


profile_llh = numerax.stats.make_profile_llh(
    normal_llh, is_nuisance, get_initial_log_sigma
)

# Evaluate profile likelihood at different mu values
mu_test = 1.0
llh_val, opt_log_sigma, diff, n_iter = profile_llh(
    jnp.array([mu_test]), data
)
Notes
  • The function is JIT-compiled for performance
  • Uses L-BFGS optimization which is well-suited for smooth likelihood surfaces
  • Returns convergence information for diagnostics
  • Handles parameter masking automatically
  • Consider using log-parameterization for positive parameters (e.g., \(\log \sigma\)) for unconstrained optimization
  • This function might not work well if the likelihood surface has multiple local maxima; in such cases, consider ensuring that initial guesses are close to the global maximum.

chi2

Chi-squared distribution functions.

This module provides a complete interface for chi-squared distribution computations, combining re-exported JAX's standard statistical functions (pdf, cdf, etc.) with a custom high-precision percent point function (ppf).

All functions support location-scale parameterization and are fully compatible with JAX transformations (JIT, grad, vmap).

ppf

ppf(q: ArrayLike, df: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Chi-squared percent point function (inverse CDF).

Overview

Computes the percent point function (quantile function) of the chi-squared distribution. This is the inverse of the cumulative distribution function, finding \(x\) such that \(P(X \leq x) = q\) for a chi-squared random variable \(X\) with \(\text{df}\) degrees of freedom.

Mathematical Background

The chi-squared distribution with \(\text{df}\) degrees of freedom is a special case of the gamma distribution:

\[X \sim \chi^2(\text{df}) \equiv \text{Gamma}\left( \frac{\text{df}}{2}, 2\right)\]

For the location-scale family:

\[Y = \text{loc} + \text{scale} \cdot X\]

The percent point function is computed as:

\[ \text{ppf}(q, \text{df}, \text{loc}, \text{scale}) = \text{loc} + \text{scale} \cdot 2 \cdot \text{gammap\_inverse}\left(q, \frac{\text{df}}{2}\right) \]
Args
  • q: Probability values in \([0, 1]\). Can be scalar or array.
  • df: Degrees of freedom (must be positive). Can be scalar or array.
  • loc: Location parameter (default: 0). Can be scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Can be scalar or array.
Returns

Quantiles \(x\) where \(P(X \leq x) = q\). Shape follows JAX broadcasting rules.

Example
import jax.numpy as jnp
import numerax

# Single quantile
x = numerax.stats.chi2.ppf(0.5, df=2)  # Median of χ²(2)

# Multiple quantiles
q_vals = jnp.array([0.1, 0.25, 0.5, 0.75, 0.9])
x_vals = numerax.stats.chi2.ppf(q_vals, df=3)

# Location-scale family
x_scaled = numerax.stats.chi2.ppf(0.5, df=2, loc=1, scale=2)

# Differentiable for optimization
grad_fn = jax.grad(numerax.stats.chi2.ppf)
sensitivity = grad_fn(0.5, 2.0)  # ∂x/∂q at median
Notes
  • Differentiable: Automatic differentiation through gammap_inverse
  • Broadcasting: Supports JAX array broadcasting for all parameters
  • Performance: JIT-compiled compatibility

halfnorm

Half-normal distribution functions.

This module provides the density, distribution, and quantile functions of the half-normal distribution (the distribution of \(|Z|\) for a standard normal \(Z\)), which JAX does not provide. The signatures mirror scipy.stats.halfnorm (including loc and scale), each function is evaluated in a form that stays accurate in the tails in both float32 and float64, and all functions are compatible with JAX transformations (JIT, grad, vmap).

cdf

cdf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal cumulative distribution function.

Computes \(\text{erf}(y/\sqrt{2})\) for \(y = (x - \text{loc})/\text{scale} \ge 0\), and zero below the support. Using erf rather than \(2\Phi(y) - 1\) keeps full relative accuracy for \(y\) near zero. See logpdf for the mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Cumulative probabilities. Shape follows JAX broadcasting rules.

isf

isf(q: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal inverse survival function.

Computes \(-\Phi^{-1}(q/2)\), i.e. ppf(1 - q) without forming \(1 - q\), so upper-tail quantiles for tiny \(q\) stay accurate, then applies \(\text{loc} + \text{scale} \cdot (\cdot)\). Returns inf at \(q = 0\), loc at \(q = 1\), and nan outside \([0, 1]\). See logpdf for the mathematical background.

Args
  • q: Survival probabilities in \([0, 1]\). Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Quantiles \(x\) where \(P(X > x) = q\). Shape follows JAX broadcasting rules.

logcdf

logcdf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal log cumulative distribution function.

Computes \(\log \text{erf}(y/\sqrt{2})\) for small \(y\) and \(\text{log1p}(-\text{erfc}(y/\sqrt{2}))\) for \(y \ge 1\), where \(y = (x - \text{loc})/\text{scale}\), so that neither regime loses precision. Returns -inf for \(y \le 0\). See logpdf for the mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Log cumulative probabilities. Shape follows JAX broadcasting rules.

logpdf

logpdf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal log probability density function.

Overview

Computes the natural logarithm of the probability density function of the half-normal distribution in the location-scale family.

Mathematical Background

The half-normal distribution is the distribution of \(X = |Z|\) for \(Z \sim N(0, 1)\). Its standard (\(\text{loc}=0\), \(\text{scale}=1\)) density on the support \(x \ge 0\) is

\[f(x) = \sqrt{\frac{2}{\pi}}\, e^{-x^2/2},\]

with distribution and survival functions

\[F(x) = \text{erf}\!\left(\tfrac{x}{\sqrt{2}}\right), \qquad S(x) = \text{erfc}\!\left(\tfrac{x}{\sqrt{2}}\right) = 2\,\Phi(-x),\]

where \(\Phi\) is the standard normal CDF. The quantile function is \(F^{-1}(q) = \sqrt{2}\,\text{erfinv}(q) = -\Phi^{-1}\!\left( \tfrac{1 - q}{2}\right)\).

The location-scale family follows the usual convention \(f(x; \text{loc}, \text{scale}) = \tfrac{1}{\text{scale}} f\!\left( \tfrac{x - \text{loc}}{\text{scale}}\right)\).

Every function in this module evaluates whichever of the equivalent forms is accurate in the relevant regime: cdf uses erf (full relative accuracy near the origin) and sf uses erfc (relative accuracy in the upper tail); logsf switches to an asymptotic expansion so it stays accurate far past where erfc underflows; ppf switches between erfinv and ndtri at \(q = 1/2\) so that neither tiny \(q\) nor \(q\) close to one loses precision; and isf evaluates \(-\Phi^{-1}(q/2)\) directly rather than forming \(1 - q\).

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Log probability density values. Shape follows JAX broadcasting rules.

Example
import jax
import jax.numpy as jnp
import numerax

# Single value
lp = numerax.stats.halfnorm.logpdf(1.0)

# Vectorized, with location and scale
x_vals = jnp.array([0.5, 1.0, 2.0, 5.0])
lps = numerax.stats.halfnorm.logpdf(x_vals, loc=0.0, scale=2.0)

# Differentiable in x, loc, and scale
grad_fn = jax.grad(numerax.stats.halfnorm.logpdf, argnums=2)
sensitivity = grad_fn(1.0, 0.0, 2.0)  # d logpdf / d scale
Notes
  • Differentiable: w.r.t. x, loc, and scale (and q for ppf/isf). Branch selections use safe substitutes so gradients (and second derivatives) stay NaN-free at finite points. At \(x = \text{loc}\), cdf, sf and logsf return the one-sided (right) derivative.
  • Precision: results follow the input dtype. Accuracy is close to machine precision in both float32 and float64; far in the upper tail sf and pdf are limited by the conditioning of \(e^{-y^2/2}\), about \(y^2\) ulps.
  • Broadcasting: Supports JAX array broadcasting for all parameters.
  • Support boundary: for \(x < \text{loc}\) the density is zero (logpdf returns -inf), matching scipy.stats.halfnorm. \(x = \text{loc}\) is in the support, where the density is \(\sqrt{2/\pi}/\text{scale}\). nan inputs propagate to nan.

logsf

logsf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal log survival function.

Evaluates \(\log S(y)\) for \(y = (x - \text{loc})/\text{scale}\) in three regimes: \(\text{log1p}(-\text{erf}(y/\sqrt{2}))\) for \(y < 1\), \(\log \text{erfc}(y/\sqrt{2})\) for \(1 \le y < y_t\), and beyond that the asymptotic expansion

\[\log S(y) = \tfrac12 \log\tfrac{2}{\pi} - \tfrac{y^2}{2} - \log y + \log\!\left(1 + \sum_{k=1}^{10} \frac{(-1)^k (2k-1)!!}{y^{2k}} \right).\]

The switch \(y_t\) is 20 in float64 and 8 in float32, before erfc (or the erfc**2 formed by second derivatives) underflows; the truncation error there is far below machine epsilon. Returns zero for \(y \le 0\). See logpdf for the mathematical background.

This is more accurate than $\log 2 + $ jax.scipy.special.log_ndtr \((-y)\), whose asymptotic branch loses ~1e-11 relative accuracy in the value (~1e-9 in the gradient) around \(y = 20\).

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Log survival probabilities. Shape follows JAX broadcasting rules.

pdf

pdf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal probability density function.

Computes \(\sqrt{2/\pi}\, e^{-y^2/2} / \text{scale}\) for \(y = (x - \text{loc})/\text{scale} \ge 0\), and zero below the support. This is exp(logpdf(...)); see logpdf for the full mathematical background and conventions.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Probability density values. Shape follows JAX broadcasting rules.

ppf

ppf(q: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal percent point function (inverse CDF).

Computes \(\sqrt{2}\,\text{erfinv}(q)\) for \(q < 1/2\) and \(-\Phi^{-1}\!\left(\tfrac{1 - q}{2}\right)\) for \(q \ge 1/2\), then applies \(\text{loc} + \text{scale} \cdot (\cdot)\). The first form keeps tiny \(q\) from being rounded away; in the second, \(1 - q\) is exact. Returns loc at \(q = 0\), inf at \(q = 1\), and nan outside \([0, 1]\). See logpdf for the mathematical background.

Args
  • q: Probability values in \([0, 1]\). Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Quantiles \(x\) where \(P(X \leq x) = q\). Shape follows JAX broadcasting rules.

sf

sf(x: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Half-normal survival function (\(1 - \text{cdf}\)).

Computes \(\text{erfc}(y/\sqrt{2})\) for \(y = (x - \text{loc})/\text{scale} \ge 0\), and one below the support. This keeps relative accuracy in the upper tail (rather than computing \(1 - \text{cdf}\)), up to the inherent conditioning of about \(y^2\) ulps for large \(y\). See logpdf for the mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Survival probabilities. Shape follows JAX broadcasting rules.

ncx2

Non-central chi-squared distribution functions.

This module provides the probability density function (pdf) and its logarithm (logpdf) for the non-central chi-squared distribution, built on the numerically stable scaled modified Bessel function ive. The signatures mirror scipy.stats.ncx2 (including loc and scale), and all functions are compatible with JAX transformations (JIT, grad, vmap).

logpdf

logpdf(x: ArrayLike, df: ArrayLike, nc: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Non-central chi-squared log probability density function.

Overview

Computes the natural logarithm of the probability density function of the non-central chi-squared distribution with \(\text{df}\) degrees of freedom and non-centrality parameter \(\lambda\) (nc), in the location-scale family.

Mathematical Background

The non-central chi-squared distribution is the distribution of the sum of squares of \(k\) independent unit-variance normal random variables with means \(\mu_1, \ldots, \mu_k\):

\[X = \sum_{i=1}^{k} (Z_i + \mu_i)^2, \qquad Z_i \sim N(0, 1),\]

with degrees of freedom \(k = \text{df}\) and non-centrality parameter \(\lambda = \sum_{i=1}^{k} \mu_i^2\). Note that nc is \(\lambda\) itself (matching scipy.stats.ncx2), not \(\lambda^2\).

The standard (\(\text{loc}=0\), \(\text{scale}=1\)) density is

\[f(x; k, \lambda) = \tfrac12 e^{-(x + \lambda)/2} \left(\tfrac{x}{\lambda}\right)^{\nu/2} I_{\nu}\!\left(\sqrt{\lambda x}\right), \qquad \nu = \tfrac{k}{2} - 1,\]

where \(I_{\nu}\) is the modified Bessel function of the first kind. Using \(I_{\nu}(z) = e^{z}\,\mathtt{ive}(\nu, z)\) and combining the exponentials via \(-(x+\lambda)/2 + \sqrt{\lambda x} = -\tfrac12(\sqrt{x} - \sqrt{\lambda})^2\) gives the numerically stable form actually evaluated:

\[f = \tfrac12\, e^{-\frac12(\sqrt{x} - \sqrt{\lambda})^2} \left(\tfrac{x}{\lambda}\right)^{\nu/2} \mathtt{ive}\!\left(\nu, \sqrt{\lambda x}\right).\]

For small \(u = \lambda x / 4 < 1\) the factors \((x/\lambda)^{\nu/2}\) and \(I_\nu\) each vary like \(\lambda^{\mp\nu/2}\) and would cancel numerically (badly so in the gradient w.r.t. \(\lambda\) as \(\lambda \to 0\)). There the power series of \(I_\nu\) is used instead, in which that cancellation is exact:

\[\log f = -\log 2 - \tfrac{x + \lambda}{2} + \nu \log\tfrac{x}{2} - \log\Gamma(\nu + 1) + \log \sum_{k \ge 0} \frac{u^k}{k!\,(\nu + 1)_k}.\]

The location-scale family follows the usual convention \(f(x; \text{loc}, \text{scale}) = \tfrac{1}{\text{scale}} f_{\text{std}}\!\left( \tfrac{x - \text{loc}}{\text{scale}}\right)\).

Args
  • x: Quantile values. Scalar or array.
  • df: Degrees of freedom (must be positive). Scalar or array.
  • nc: Non-centrality parameter \(\lambda \ge 0\). Scalar or array. nc == 0 reduces to the central chi-squared distribution.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Log probability density values. Shape follows JAX broadcasting rules.

Example
import jax.numpy as jnp
import numerax

# Single value
lp = numerax.stats.ncx2.logpdf(4.0, df=3.0, nc=2.0)

# Vectorized
x_vals = jnp.array([0.5, 1.0, 2.0, 5.0])
lps = numerax.stats.ncx2.logpdf(x_vals, df=3.0, nc=2.0)

# Differentiable in x and nc
grad_fn = jax.grad(numerax.stats.ncx2.logpdf, argnums=2)
sensitivity = grad_fn(4.0, 3.0, 2.0)  # d logpdf / d nc
Notes
  • Differentiable: w.r.t. x, nc, loc, and scale. Not differentiable w.r.t. df -- df feeds the order of the underlying ive, which has no order-derivative, so differentiating w.r.t. df raises TypeError rather than returning a silently-wrong value.
  • Gradient at \(\text{nc} = 0\): the gradient w.r.t. nc is correct for every \(\text{nc} > 0\), but at exactly \(\text{nc} = 0\) it returns 0 rather than the true one-sided score $\tfrac12!\left(\tfrac{(x-\text{loc})/\text{scale}}{\text{df}}
  • 1\right)$. \(\text{nc} = 0\) is the boundary of the parameter domain (where the derivative is one-sided and the closed form has a removable singularity), so this measure-zero point is not special cased. Differentiate at a small \(\text{nc} > 0\) if the score at the null is needed.
  • Broadcasting: Supports JAX array broadcasting for all parameters.
  • Accuracy: inherits the ~1e-6 relative accuracy of ive for \(\lambda x \ge 4\); below that the series form is accurate to working precision.
  • Support boundary: for \(x \le \text{loc}\) the density is taken to be zero (logpdf returns -inf), matching scipy.stats.ncx2.pdf. At the single point \(x = \text{loc}\) the mathematical limit can diverge for \(\text{df} < 2\); that measure-zero point is reported as zero density here.

pdf

pdf(x: ArrayLike, df: ArrayLike, nc: ArrayLike, loc: ArrayLike = 0, scale: ArrayLike = 1) -> ArrayLike

Non-central chi-squared probability density function.

Computes the probability density function of the non-central chi-squared distribution with \(\text{df}\) degrees of freedom and non-centrality parameter \(\lambda\) (nc), in the location-scale family. This is exp(logpdf(...)); see logpdf for the full mathematical background, conventions, and differentiability notes.

Args
  • x: Quantile values. Scalar or array.
  • df: Degrees of freedom (must be positive). Scalar or array.
  • nc: Non-centrality parameter \(\lambda \ge 0\). Scalar or array.
  • loc: Location parameter (default: 0). Scalar or array.
  • scale: Scale parameter (must be positive, default: 1). Scalar or array.
Returns

Probability density values. Shape follows JAX broadcasting rules.

Example
import jax.numpy as jnp
import numerax

# Single value
p = numerax.stats.ncx2.pdf(4.0, df=3.0, nc=2.0)

# Vectorized
x_vals = jnp.array([0.5, 1.0, 2.0, 5.0])
ps = numerax.stats.ncx2.pdf(x_vals, df=3.0, nc=2.0)
Notes
  • Differentiable: w.r.t. x, nc, loc, and scale; differentiating w.r.t. df raises TypeError. The gradient w.r.t. nc returns 0 at exactly nc = 0 (a domain boundary). See logpdf for details.
  • Accuracy: inherits the ~1e-6 relative accuracy of ive.

splitnorm

Split-normal distribution functions.

This module provides the density, distribution, and quantile functions of the split-normal (two-piece normal) distribution: a normal distribution with mode loc whose left and right halves have different scales. It is commonly used to describe asymmetric uncertainties. JAX and scipy do not provide it. The signatures follow the scipy.stats conventions, with the single scale replaced by scale_left and scale_right. The distribution functions are built on halfnorm, every function is evaluated in a form that stays accurate in both tails in float32 and float64, and all functions are compatible with JAX transformations (JIT, grad, vmap).

cdf

cdf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal cumulative distribution function.

Computes \(w_L\, S_h((\mu - x)/\sigma_L)\) below the mode, which keeps relative accuracy in the lower tail, and \(w_L + w_R\, F_h((x - \mu)/\sigma_R)\) above it, a sum of non-negative terms. See logpdf for the notation and mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Cumulative probabilities. Shape follows JAX broadcasting rules.

isf

isf(q: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal inverse survival function.

The mirror image of ppf: computes ppf(1 - q) without forming \(1 - q\) except in the lower tail (\(q > 1 - w_L/2\)), where it is exact, so upper-tail quantiles for tiny \(q\) and quantiles on the far side of a small \(w_R\) stay accurate. Returns inf at \(q = 0\), -inf at \(q = 1\), and nan outside \([0, 1]\). See logpdf for the notation and mathematical background.

Args
  • q: Survival probabilities in \([0, 1]\). Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Quantiles \(x\) where \(P(X > x) = q\). Shape follows JAX broadcasting rules.

logcdf

logcdf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal log cumulative distribution function.

Below the mode, computes \(\log w_L + \log S_h((\mu - x)/\sigma_L)\) using halfnorm.logsf, which stays accurate far past where the CDF underflows. Above the mode, computes \(\text{log1p}(-w_R\, S_h((x - \mu)/\sigma_R))\) while the CDF exceeds \(1/2\) and \(\log(w_L + w_R\, F_h((x - \mu)/\sigma_R))\) otherwise, so that neither regime loses precision. See logpdf for the notation and mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Log cumulative probabilities. Shape follows JAX broadcasting rules.

logpdf

logpdf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal log probability density function.

Overview

Computes the natural logarithm of the probability density function of the split-normal distribution, a normal distribution with mode loc whose two halves have separate scales.

Mathematical Background

With mode \(\mu = \text{loc}\), left scale \(\sigma_L\) and right scale \(\sigma_R\), the density is

\[f(x) = \sqrt{\frac{2}{\pi}}\, \frac{1}{\sigma_L + \sigma_R} \begin{cases} e^{-(x - \mu)^2 / 2\sigma_L^2}, & x < \mu, \\ e^{-(x - \mu)^2 / 2\sigma_R^2}, & x \ge \mu, \end{cases}\]

which is continuous (with continuous derivative) at the mode. It reduces to \(N(\mu, \sigma^2)\) when \(\sigma_L = \sigma_R = \sigma\).

Equivalently, the split normal is a mixture of two half-normals with disjoint supports: with probability \(w_L = \sigma_L / (\sigma_L + \sigma_R)\), \(X = \mu - \sigma_L |Z|\), and with probability \(w_R = \sigma_R / (\sigma_L + \sigma_R)\), \(X = \mu + \sigma_R |Z|\). Writing \(F_h\) and \(S_h\) for the standard half-normal CDF and survival function, this gives

\[F(x) = \begin{cases} w_L\, S_h\!\left(\tfrac{\mu - x}{\sigma_L}\right), & x < \mu, \\ w_L + w_R\, F_h\!\left(\tfrac{x - \mu}{\sigma_R}\right), & x \ge \mu, \end{cases}\]

and the mirror image for \(S(x) = 1 - F(x)\). The quantile function is \(\mu - \sigma_L F_h^{-1}\!\left(\tfrac{w_L - q}{w_L}\right)\) for \(q < w_L\) and \(\mu + \sigma_R F_h^{-1}\!\left(\tfrac{q - w_L}{w_R} \right)\) otherwise, where \(F_h^{-1}(p) = \sqrt{2}\,\text{erfinv}(p) = -\Phi^{-1}\!\left(\tfrac{1 - p}{2}\right)\).

Every function in this module evaluates these in a form that is accurate in the relevant regime: tail probabilities are computed directly from the half-normal survival function (never as \(1 - \text{something}\)); logcdf and logsf use halfnorm.logsf on the side of the mode where they decay, so they stay accurate past where the probabilities underflow, and switch between \(\text{log1p}\) and a direct sum on the other side; the log-weights are evaluated as \(\log w_L = -\text{log1p}(\sigma_R/\sigma_L)\), accurate even when \(w_L\) is close to one; and ppf and isf, like halfnorm.ppf, use erfinv within the central half of each piece and \(\Phi^{-1}\) of the tail probability beyond it, so no regime loses precision to forming \(1 - q\).

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Log probability density values. Shape follows JAX broadcasting rules.

Example
import jax
import jax.numpy as jnp
import numerax

# A measurement of 3.0 with uncertainties -0.5 / +1.2
lp = numerax.stats.splitnorm.logpdf(3.4, loc=3.0, scale_left=0.5,
                                    scale_right=1.2)

# Vectorized
x_vals = jnp.array([-1.0, 0.0, 1.0, 5.0])
lps = numerax.stats.splitnorm.logpdf(x_vals, 0.0, 1.0, 2.0)

# Differentiable in x, loc, and both scales
grad_fn = jax.grad(numerax.stats.splitnorm.logpdf, argnums=(1, 2, 3))
d_loc, d_left, d_right = grad_fn(1.0, 0.0, 1.0, 2.0)
Notes
  • Differentiable: w.r.t. x, loc, scale_left and scale_right (and q for ppf/isf). Branch selections use safe substitutes so gradients stay NaN-free at finite points, including for extreme scale ratios. The density and its first derivative in x are continuous at the mode, and every function is continuous in all its arguments there, so first derivatives at the mode are two-sided. Second and higher derivatives in x jump at the mode; there the values for the side \(x \ge \mu\) are returned.
  • Precision: results follow the input dtype. Accuracy is close to machine precision in both float32 and float64; far in either tail pdf, cdf and sf are limited by the conditioning of \(e^{-y^2/2}\), about \(y^2\) ulps, as in halfnorm. Near \(q = w_L\) (ppf) or \(q = w_R\) (isf), the quantile is limited by the rounding of the weight itself.
  • Broadcasting: Supports JAX array broadcasting for all parameters.
  • Support: the whole real line. nan inputs propagate to nan.

logsf

logsf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal log survival function.

The mirror image of logcdf: above the mode, computes \(\log w_R + \log S_h((x - \mu)/\sigma_R)\) using halfnorm.logsf; below it, computes \(\text{log1p}(-w_L\, S_h((\mu - x)/\sigma_L))\) while the survival function exceeds \(1/2\) and \(\log(w_R + w_L\, F_h((\mu - x)/\sigma_L))\) otherwise. See logpdf for the notation and mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Log survival probabilities. Shape follows JAX broadcasting rules.

pdf

pdf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal probability density function.

Computes \(\sqrt{2/\pi}\, e^{-y^2/2} / (\sigma_L + \sigma_R)\) for \(y = (x - \text{loc})/\sigma\), where \(\sigma\) is scale_left below the mode and scale_right above it. This is exp(logpdf(...)); see logpdf for the full mathematical background and conventions.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Probability density values. Shape follows JAX broadcasting rules.

ppf

ppf(q: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal percent point function (inverse CDF).

Inverts the half-normal piece on the relevant side of the mode. In the central half of a piece (\(w_L/2 < q < w_L + w_R/2\)) it computes \(\mu + \sigma \sqrt{2}\, \text{erfinv}((q - w_L)/w)\), with \(\sigma\) and \(w\) the scale and weight of that side; in the lower tail \(\mu + \sigma_L \Phi^{-1}(q / 2w_L)\); and in the upper tail \(\mu - \sigma_R \Phi^{-1}((1 - q) / 2w_R)\), where \(1 - q\) is exact. Tiny \(q\), \(q\) close to one, and \(q\) on the far side of a small \(w_L\) all keep full precision. Returns -inf at \(q = 0\), inf at \(q = 1\), and nan outside \([0, 1]\). See logpdf for the notation and mathematical background.

Args
  • q: Probability values in \([0, 1]\). Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Quantiles \(x\) where \(P(X \leq x) = q\). Shape follows JAX broadcasting rules.

sf

sf(x: ArrayLike, loc: ArrayLike = 0, scale_left: ArrayLike = 1, scale_right: ArrayLike = 1) -> ArrayLike

Split-normal survival function (\(1 - \text{cdf}\)).

Computes \(w_R\, S_h((x - \mu)/\sigma_R)\) above the mode, which keeps relative accuracy in the upper tail, and \(w_R + w_L\, F_h((\mu - x)/\sigma_L)\) below it. See logpdf for the notation and mathematical background.

Args
  • x: Quantile values. Scalar or array.
  • loc: Location of the mode (default: 0). Scalar or array.
  • scale_left: Scale below the mode (must be positive, default: 1). Scalar or array.
  • scale_right: Scale above the mode (must be positive, default: 1). Scalar or array.
Returns

Survival probabilities. Shape follows JAX broadcasting rules.