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:
In practice, we work with the log-likelihood \(\ell(\boldsymbol{\theta}, \boldsymbol{\lambda}) = \log L(\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 ¶
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:
For the location-scale family:
The percent point function is computed as:
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 ¶
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 ¶
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 ¶
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 ¶
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
with distribution and survival functions
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, andscale(andqforppf/isf). Branch selections use safe substitutes so gradients (and second derivatives) stay NaN-free at finite points. At \(x = \text{loc}\),cdf,sfandlogsfreturn 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
sfandpdfare 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
(
logpdfreturns-inf), matchingscipy.stats.halfnorm. \(x = \text{loc}\) is in the support, where the density is \(\sqrt{2/\pi}/\text{scale}\).naninputs propagate tonan.
logsf ¶
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
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 ¶
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 ¶
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 ¶
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\):
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
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:
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:
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 == 0reduces 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, andscale. Not differentiable w.r.t.df--dffeeds the order of the underlyingive, which has no order-derivative, so differentiating w.r.t.dfraisesTypeErrorrather than returning a silently-wrong value. - Gradient at \(\text{nc} = 0\): the gradient w.r.t.
ncis correct for every \(\text{nc} > 0\), but at exactly \(\text{nc} = 0\) it returns0rather 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
ivefor \(\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 (
logpdfreturns-inf), matchingscipy.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, andscale; differentiating w.r.t.dfraisesTypeError. The gradient w.r.t.ncreturns0at exactlync = 0(a domain boundary). Seelogpdffor 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
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
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_leftandscale_right(andqforppf/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 inxare 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 inxjump 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,cdfandsfare limited by the conditioning of \(e^{-y^2/2}\), about \(y^2\) ulps, as inhalfnorm. 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.
naninputs propagate tonan.
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.