MetalogMoments

Moments of metalog distributions.

Because a metalog is defined by its quantile function, the k-th moment about the origin is the integral over the unit interval of the k-th power of that quantile function. Keelin (2016) section 3.4 gives closed-form polynomials for the low-order central moments of the unbounded metalog with five or fewer terms, and those are used where they apply. Everything else, including every bounded or semi-bounded case, is integrated numerically.

The closed forms also serve as the validation oracle for the numerical path, since the two must agree wherever both are available.

Numerical integration is segmented geometrically toward each endpoint. The quantile function of an unbounded metalog diverges logarithmically at zero and one, which is integrable but poorly served by a single quadrature rule spanning the whole interval.

Properties

Link copied to clipboard
const val DEFAULT_ENDPOINT_TOLERANCE: Double = 1.0E-15

How close to each endpoint the numerical integration reaches. The remaining tail is negligible for a logarithmic divergence.

Link copied to clipboard

The number of Gauss-Legendre points used on each segment.

Link copied to clipboard
const val MAX_CLOSED_FORM_TERMS: Int = 5

The largest number of terms for which the closed-form moment expressions apply.

Link copied to clipboard
const val MAX_LOGIT_LIMIT: Double = 36.0

The furthest out in the logit variable that integration can go. Beyond this the recovered probability rounds to exactly one and the quantile function is no longer defined there.

Link copied to clipboard

The furthest out in the logit variable that integration can go when the quantile function is parameterized by the probability rather than by the logit.

Link copied to clipboard

The largest product of moment order and tail weight for which a quadrature moment of a semi-bounded metalog is accurate to better than roughly one part in ten million. Past this the moment still exists, but the far tail contributes more than the reachable range of a double can capture.

Functions

Link copied to clipboard
fun centralMomentByQuadrature(j: Int, mean: Double, endpointTolerance: Double = DEFAULT_ENDPOINT_TOLERANCE, quantileFunction: (Double) -> Double): Double

The j-th moment about the supplied mean of a distribution described by the supplied quantile function.

Link copied to clipboard
fun centralMomentInLogit(j: Int, mean: Double, endpointTolerance: Double = DEFAULT_ENDPOINT_TOLERANCE, quantileOfLogit: (Double) -> Double): Double

The j-th moment about the supplied mean, for a quantile function parameterized by the logit of the cumulative probability. See the companion function for why this is preferred when the tails matter.

Link copied to clipboard
fun hasClosedForm(numTerms: Int, boundedness: MetalogBoundedness): Boolean

True when a closed-form expression covers the supplied arity and boundedness. Only the unbounded member with five or fewer terms qualifies.

Link copied to clipboard

The combined weight on the logit as the cumulative probability approaches zero, formed the same way as the upper tail weight but at a centered probability of minus one half.

Link copied to clipboard
fun momentExists(j: Int, coefficients: DoubleArray, boundedness: MetalogBoundedness): Boolean

Whether the moment of the given order is finite.

Link copied to clipboard
fun momentIsReliable(j: Int, coefficients: DoubleArray, boundedness: MetalogBoundedness): Boolean

Whether a numerically computed moment of the given order can be trusted to the accuracy the quadrature normally achieves.

Link copied to clipboard
fun rawMomentByQuadrature(j: Int, endpointTolerance: Double = DEFAULT_ENDPOINT_TOLERANCE, quantileFunction: (Double) -> Double): Double

The j-th moment about the origin of a distribution described by the supplied quantile function, computed as the integral of the j-th power of that function over the unit interval.

Link copied to clipboard
fun rawMomentInLogit(j: Int, endpointTolerance: Double = DEFAULT_ENDPOINT_TOLERANCE, quantileOfLogit: (Double) -> Double): Double

The j-th moment about the origin, for a quantile function parameterized by the logit of the cumulative probability rather than by the probability.

Link copied to clipboard
fun unboundedMean(coefficients: DoubleArray): Double

The mean of an unbounded metalog with five or fewer terms, from Keelin (2016) section 3.4. Coefficients beyond those supplied are treated as zero, which is why the same expression covers two through five terms.

Link copied to clipboard

The variance of an unbounded metalog with five or fewer terms, from Keelin (2016) section 3.4. Coefficients beyond those supplied are treated as zero.

Link copied to clipboard

The combined weight on the logit as the cumulative probability approaches one, which is the sum of every coefficient that multiplies the logit, each evaluated at the centered probability of one half. This governs how fast the quantile function grows in the upper tail: the quantile behaves like the reciprocal of one minus the probability, raised to this weight.