Skip to content

Add Laplace distribution functions - #244

Merged
devmotion merged 4 commits into
masterfrom
dmw/laplace
Nov 17, 2026
Merged

devmotion merged 4 commits into
masterfrom
dmw/laplace

Conversation

@devmotion

Copy link
Copy Markdown
Member

This PR adds laplace{pdf,logpdf,cdf,ccdf,logcdf,logccdf,invcdf,invccdf,invlogcdf,invlogccdf} in standard and (μ, θ, x) form.

Motivation

#240 (tdistinvlogcdf) and JuliaStats/Distributions.jl#2115 (invlogcdf(::Laplace, ...)) contain the same branches for computing, from lp = log(p),

L(lp) = p ≤ 1/2 ? log(2p) : -log(2(1 - p))

This is the Laplace quantile at exp(lp). LogExpFunctions' log2mexp contains a third copy of the high/low split of log(2) that it needs. With laplaceinvlogcdf here, the callers have no branches:

  • t: l = laplaceinvlogcdf(logp); copysign(sqrt(fdistinvlogccdf(1, ν, -abs(l))), l) (this PR; it replaces the tdist.jl part of Improve accuracy of fdist and tdist quantiles in the upper tail #240, whose F-quantile and test changes are independent)
  • Distributions: invlogcdf(d::Laplace, lp) = laplaceinvlogcdf(d.μ, d.θ, lp) and so on (follow-up PR)

StatsFuns no longer uses log2mexp internally, but still reexports it. I plan to deprecate it in LogExpFunctions.

Implementation

  • laplaceinvlogcdf: y = (lp + T(logtwo)) + _logtwo_lo(T) is log(2p), accurate even at lp == T(loghalf), where its sign decides the side. For y > 0, the result is -log1p(-expm1(y)) near the median and -log(-2 * expm1(lp)) in the upper tail.
  • laplacelogcdf: log1p(-exp(-z) / 2) for z ≥ 0 is well conditioned.
  • The (μ, θ, x) methods of logpdf and of the inverse functions promote their arguments first.
  • A ChainRules rule for laplacelogpdf, and InverseFunctions pairs for all four cdf/inverse pairs.
  • The extensions are renamed to ChainRulesCoreExt and InverseFunctionsExt.

Accuracy

Maximum error in ulps against 1024-bit BigFloat closed forms, over about 3e5 samples per function covering the tails, the median and the branch cutoff. "Distributions" is the current Laplace implementation in Distributions master (with LogExpFunctions 1.0.6):

Float64: Distributions → this PR Float32 Float16
pdf, logpdf, cdf, ccdf, invcdf, invccdf ≤ 0.76 → ≤ 0.76 ≤ 0.82 → ≤ 0.82 ≤ 0.93 → ≤ 0.93
logcdf, logccdf 9.0e15 → 1.29 1.7e7 → 1.44 3.1e3 → 1.25
invlogcdf, invlogccdf 7.5e15 → 2.01 8.6e6 → 1.48 1.8e3 → 1.45
  • logcdf: Distributions' loghalf + log2mexp(-z) cancels completely for large z and returns 0 instead of about -exp(-z) / 2.
  • invlogcdf: logtwo + lp lacks the low part of log(2), which dominates the result near the median.

ForwardDiff through the primals yields the exact closed forms of the derivatives (1, u / (2 - u) and p / (1 - p)), with maximum errors of 2.84 (d logcdf) and 2.58 (d invlogcdf) ulps for Float64. So no hand-written rules are needed for the cdf and quantile functions.

Tests

Rmath has no Laplace distribution. The new tests compare against closed forms in BigFloat (for Float16, Float32, Float64 and BigFloat), check special values and promotion, and compare ForwardDiff derivatives. laplace is also added to the generic Dual, ChainRules and InverseFunctions tests.

🤖 Generated with Claude Code

devmotion and others added 2 commits November 16, 2026 14:45
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the full pdf/cdf/quantile API for the Laplace distribution, in standard
and location-scale form. `laplaceinvlogcdf` splits `log(2)` into a high and a
low part so that it stays accurate around the median, and `tdistinvlogcdf` now
calls it instead of `log2mexp`, which drops its branches. There is no Rmath
reference, so the tests compare against closed forms in `BigFloat`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.22%. Comparing base (255db57) to head (32e69b6).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #244      +/-   ##
==========================================
+ Coverage   75.85%   77.22%   +1.37%     
==========================================
  Files          23       24       +1     
  Lines        1147     1190      +43     
==========================================
+ Hits          870      919      +49     
+ Misses        277      271       -6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devmotion
devmotion merged commit 5bd890a into master Nov 17, 2026
14 checks passed
@devmotion
devmotion deleted the dmw/laplace branch November 17, 2026 00:15
devmotion added a commit that referenced this pull request Nov 17, 2026
`fdistinvlogccdf` is now the reciprocal of `fdistinvlogcdf` with swapped
degrees of freedom (`1 / F ~ F(ν2, ν1)`), which removes the metaprogramming.
The new tests cover `tdistinvcdf`/`tdistinvccdf`, which also benefit from the
F quantile changes, and the tdistinvlogcdf test from #244 is merged into the
more extensive one here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
devmotion added a commit that referenced this pull request Nov 17, 2026
* Rename extensions to ChainRulesCoreExt and InverseFunctionsExt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Add Laplace distribution functions

Adds the full pdf/cdf/quantile API for the Laplace distribution, in standard
and location-scale form. `laplaceinvlogcdf` splits `log(2)` into a high and a
low part so that it stays accurate around the median, and `tdistinvlogcdf` now
calls it instead of `log2mexp`, which drops its branches. There is no Rmath
reference, so the tests compare against closed forms in `BigFloat`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Test the low part of log(2)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Test promotion of all quantile functions and tdistinvlogcdf

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Compare fdist and tdist with Rmath in the tests again

Since the tests call Rmath directly, `rmathcomp` looked up `Rmath.dfdist`
and `Rmath.dtdist`, which do not exist (the Rmath names are `df`, `pf`,
`qf` and `dt`, `pt`, `qt`), so the "RMath fdist" and "RMath tdist" test
items silently ran no tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Improve accuracy of fdist quantiles in the upper tail

The F quantile `ν2 * x / (ν1 * (1 - x))` for the quantile `x` of the beta
variate `u ~ Beta(ν1 / 2, ν2 / 2)` cancelled catastrophically for `x`
close to 1. Now `1 - x` is computed directly: `beta_inc_inv` returns it
alongside `x`, and for the log-probability versions the quantile of
whichever of `u` and `1 - u ~ Beta(ν2 / 2, ν1 / 2)` is at most 1/2 is
computed, which is decided upfront from `P(u ≤ 1/2)`.

The handling of degenerate beta distributions in `betainvcdf` and
`betainvccdf` (`beta_inc_inv` does not return for them, #154) is moved
to a helper that returns both `x` and `1 - x` and is used by the F
quantiles as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Test tdistinvlogcdf also for Float16

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Simplify log F quantiles and test tdistinvcdf tails

`fdistinvlogccdf` is now the reciprocal of `fdistinvlogcdf` with swapped
degrees of freedom (`1 / F ~ F(ν2, ν1)`), which removes the metaprogramming.
The new tests cover `tdistinvcdf`/`tdistinvccdf`, which also benefit from the
F quantile changes, and the tdistinvlogcdf test from #244 is merged into the
more extensive one here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Bump version from 2.3.0 to 2.3.1

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants