Simplify logstatsexp reductions: length-aware iterators and direct normalization

[Copilot]

Simplify the logstatsexp reductions and add the combined mean+variance / mean+std functions, while keeping the numerically-stable behavior and being allocation-conscious.

Functions

• logmeanexp, logvarexp, logstdexp — log of the mean / variance / std of exp.(X).
• logmeanexp_and_logvarexp, logmeanexp_and_logstdexp — compute both at once, reusing the mean to center the variance (cheaper than two separate calls).

All accept either a general iterator or an AbstractArray with a dims keyword, and a corrected keyword for the variance/std.

Numerical stability

The variance uses the centered formula

log var = logsumexp(2 * logsubexp(xᵢ, logmean)) - log(n - corrected)

i.e. the log of ∑ᵢ (exp(xᵢ) - mean)² divided by the count. Centering is essential: the raw-second-moment alternative logsubexp(∑exp(2xᵢ), (∑exp(xᵢ))²/n) cancels catastrophically when the variance is small relative to the mean (and can even overflow to Inf for nearly-equal inputs). Because the variance needs the mean first, logmeanexp_and_logvarexp is the primitive and logvarexp / logstdexp / logmeanexp_and_logstdexp are derived from it. Correctness on hard cases (tight clusters, over/underflowing magnitudes, huge dynamic range) is checked against BigFloat references in the tests.

Iterator / reduction strategy

• Mean (logmeanexp) is a single pass that counts the elements as it goes, so an iterator is traversed exactly once (single-use iterators are handled correctly). Empty inputs throw.
• Variance is centered, so it needs two traversals (mean, then deviations). Re-iterability cannot be detected from IteratorSize (Iterators.Stateful reports HasLength on some Julia versions yet is single-use), so a generic iterator is collected once; known re-iterable containers (AbstractArray, Tuple, NamedTuple, AbstractRange) are traversed in place.

Allocations

• The scalar (dims = :) variance accumulates in a single pass (_centered_logsqdev) with no intermediate array.
• The dims variance reduces 2 .* logsubexp.(X, logmean) with logsumexp(...; dims). That allocates one temporary the size of the input — the same intermediate Statistics.var(exp.(X); dims) itself forms. (An earlier lazy-reduction variant that avoided this temporary was dropped: it returned silently wrong results for arrays with non-1-based axes and threw for abstract element types — simplicity and correctness won.)
• Normalization uses log(n) in the input's own (real) floating-point type, so Float32 stays Float32 (no silent Float64 promotion).

Edge cases

var/std semantics are matched on the awkward inputs: an empty reduction yields NaN (not an error) for every corrected, an empty non-reduced dimension yields an empty result, non-1-based axes (OffsetArrays) match the 1-based result, abstract element types work, and complex inputs are rejected with a clear ArgumentError on every variance/std path.

Tests

Cover arrays and iterators (incl. one-shot Stateful and a single-use length-reporting iterator), dims and promotion, the combined functions, type-stability / @inferred, allocation non-scaling for the full reductions, the edge cases above, empty-input errors, real-input enforcement for variance/std, and the BigFloat numerical-robustness suite. Verified on Julia 1.10 and 1.12 (full Pkg.test, including JET and Aqua).

[Copilot]

Pull request overview

This PR introduces stable “log of exp-statistics” utilities to LogExpFunctions.jl, adding public APIs for log-mean/variance/std of exp(X) across both array reductions (dims) and non-array iterables, with accompanying tests and documentation wiring.

Changes:

• Add logmeanexp, logvarexp, and logstdexp to the public API (exports + module include).
• Add a new implementation file for these functions and wire them into the docs index.
• Add a new test file covering array dims behavior and some iterable inputs, plus test dependency updates.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/LogExpFunctions.jl	Exports and includes the new log*exp statistics functions.
src/logstatsexp.jl	Implements logmeanexp / logvarexp / logstdexp for arrays and iterables.
test/runtests.jl	Adds the new logstatsexp.jl testset to the test suite.
test/Project.toml	Adds Statistics as a test dependency.
test/logstatsexp.jl	Adds tests for the new functionality (arrays + some iterators).
docs/src/index.md	Adds the new API entries to the documentation index.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.