MetalogFunctions

The basis functions underlying the metalog quantile function of Keelin (2016).

The metalog quantile function is a linear combination of basis terms in the cumulative probability y. Writing L for the logit ln(y/(1-y)) and c for the centered probability y - 0.5, the terms in order are 1, L, cL, c, c^2, c^2 L, c^3, c^3 L, and so on, alternating between a power of c and that power multiplied by the logit. Because the quantile function is linear in the coefficients, fitting reduces to least squares.

These functions accept any number of terms of at least two. It is the concrete distribution classes that fix the arity.

Terms are numbered from one, matching the indexing used in the paper, while coefficient arrays are indexed from zero in the usual way. So the coefficient at array index zero multiplies term one.

Properties

Link copied to clipboard
const val MIN_TERMS: Int = 2

The fewest terms that define a metalog. With two terms the distribution is a logistic.

Functions

Link copied to clipboard
fun basisTerm(i: Int, y: Double): Double

The i-th basis term evaluated at cumulative probability y, where i is numbered from one.

Link copied to clipboard

The derivative with respect to y of the i-th basis term, where i is numbered from one.

Link copied to clipboard
fun density(coefficients: DoubleArray, y: Double): Double

The metalog density in fitting space, which is the reciprocal of the quantile derivative. This is a density with respect to the fitting-space variable; multiply by the appropriate boundedness density factor to obtain a density on the support of the random variable.

Link copied to clipboard
fun designMatrix(probabilities: DoubleArray, numTerms: Int): Array<DoubleArray>

The design matrix of the metalog least squares problem. Row i holds the first numTerms basis terms evaluated at probabilities element i, so the matrix has one row per supplied probability and one column per term.

Link copied to clipboard

The limit of the quantile function in fitting space as the cumulative probability approaches one. See the companion function for why this can be finite even when the declared bounds are infinite.

Link copied to clipboard

The limit of the quantile function in fitting space as the cumulative probability approaches zero.

Link copied to clipboard

The logit of the supplied probability, the quantity Keelin writes as ln(y/(1-y)).

Link copied to clipboard
fun logitWeightAt(coefficients: DoubleArray, c: Double): Double

The combined weight on the logit at the supplied centered probability, formed by summing every coefficient whose basis term carries the logit, each scaled by the matching power of that centered probability. Terms two and three carry the logit, as does every even-numbered term from six onward.

Link copied to clipboard
fun nonLogitPartAt(coefficients: DoubleArray, c: Double): Double

The part of the quantile function that does not carry the logit, evaluated at the supplied centered probability. The first term contributes a constant, the fourth contributes the centered probability itself, and every odd-numbered term from five onward contributes a power of it.

Link copied to clipboard

The derivative of the cumulative probability with respect to its logit, which is the product of the probability and its complement. Written through the hyperbolic secant so that neither tail cancels.

Link copied to clipboard
fun quantile(coefficients: DoubleArray, y: Double): Double

The metalog quantile function evaluated in fitting space. For an unbounded metalog this is the quantile function of the random variable itself; for the other members it must be mapped through the appropriate boundedness transform.

Link copied to clipboard

The derivative with respect to y of the metalog quantile function. This is strictly positive throughout the open interval from zero to one exactly when the coefficients define a valid distribution, which is what MetalogFeasibilityChecker verifies.

Link copied to clipboard
fun quantileFromLogit(coefficients: DoubleArray, logit: Double): Double

The metalog quantile function evaluated in fitting space, parameterized by the logit of the cumulative probability rather than by the probability itself.