@mark1russell7/rigor-statistics 0.1.20 → 0.1.21

package/build/index.js

@@ -2882,6 +2882,17 @@ function brier(forecasts) {
 	for (const f of forecasts) sum += (f.p - (f.hit ? 1 : 0)) ** 2;
 	return sum / forecasts.length;
 }
+/**
+* The log-loss of predictions: the mean of `-ln(p)` for a hit and `-ln(1 - p)` for a miss. 0 is perfect, and
+* `ln(2)` is a constant 0.5. Lower is better. A p of 0 for a hit gives Infinity. For an outcome of three values,
+* give the probability of the observed outcome as `p`, with `hit` true.
+*/
+function logLoss(forecasts) {
+	checkedForecasts("logLoss", forecasts);
+	let sum = 0;
+	for (const f of forecasts) sum -= Math.log(f.hit ? f.p : 1 - f.p);
+	return sum / forecasts.length;
+}
 /** The hit rate of each stated level, from the lowest level. */
 function calibration(forecasts) {
 	checkedForecasts("calibration", forecasts);
@@ -3287,6 +3298,416 @@ function choose(n, k) {
 	for (let j = 0; j < k; j++) c = c * (n - j) / (j + 1);
 	return c;
 }
-export { KENDALL_EXACT, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, U_STATISTIC_TIGHT_MIN_SAMPLE, Z95, bestSmoothLaw, binomialInterval, binomialTest, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapTwo, brier, calibration, cohenKappa, compareRatios, coverageMinSample, fitResponse, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, mean, median, medianInterval, modeCount, negativeBinomialInterval, noiseFloor, noiseVerdict, optionFloor, pairedPermutation, parseResponseRecord, partialConjunction, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, responseCells, ridgeSolve, sampleTotalInterval, sd, signTest, signTestPower, sliceResponse, smoothLawScores, sorted, spearman, summarize, surfaceResponse, tQuantile, twoSamplePermutation, uStatisticInterval, whenHolds, wilson, wilsonSampleSize };
+// src/rating.ts
+function finite(name, label, value) {
+	if (!Number.isFinite(value)) throw new RangeError(`${name}: ${label} is a finite number, not ${value}.`);
+}
+function positive(name, label, value) {
+	if (!(value > 0 && Number.isFinite(value))) throw new RangeError(`${name}: ${label} is a finite number above 0, not ${value}.`);
+}
+function checkedScale(name, options) {
+	const center = options.center ?? 1500;
+	const scale = options.scale ?? 400;
+	const base = options.base ?? 10;
+	finite(name, "the center", center);
+	positive(name, "the scale", scale);
+	if (!(base > 1 && Number.isFinite(base))) throw new RangeError(`${name}: the base is a finite number above 1, not ${base}.`);
+	return {
+		center,
+		scale,
+		base
+	};
+}
+/**
+* The expected score of the first item against the second item: `1 / (1 + base ** ((rb - ra) / scale))`. A win
+* counts 1, a tie 0.5 and a loss 0. The expected score of the second item is 1 minus this value.
+*/
+function eloExpected(ra, rb, options = {}) {
+	finite("eloExpected", "the first rating", ra);
+	finite("eloExpected", "the second rating", rb);
+	const { scale, base } = checkedScale("eloExpected", options);
+	return 1 / (1 + base ** ((rb - ra) / scale));
+}
+/**
+* The Elo update of a pair after one result. The `score` is the score of the first item: 1 for a win, 0.5 for a tie
+* and 0 for a loss. Each rating moves by `k` times the difference between the score and the expected score. Thus
+* the sum of the two ratings does not change.
+*/
+function eloUpdate(ra, rb, score, options = {}) {
+	if (!(score >= 0 && score <= 1)) throw new RangeError(`eloUpdate: the score is from 0 to 1, not ${score}.`);
+	const k = options.k ?? 32;
+	if (!(k >= 0 && Number.isFinite(k))) throw new RangeError(`eloUpdate: k is a finite number of 0 or more, not ${k}.`);
+	const expected = eloExpected(ra, rb, options);
+	const change = k * (score - expected);
+	return {
+		a: ra + change,
+		b: rb - change,
+		expected
+	};
+}
+/** The factor between the Glicko scale and the Glicko-2 scale: `400 / ln(10)`, to 4 places as in the paper. */
+const GLICKO2_FACTOR = 173.7178;
+const GLICKO2_CENTER = 1500;
+const VOLATILITY_STEPS = 1e3;
+function checkedRating(name, player) {
+	finite(name, "the rating", player.rating);
+	positive(name, "the RD", player.rd);
+	positive(name, "the volatility", player.volatility);
+}
+/**
+* The Glicko-2 update of one player after one rating period (Glickman, "Example of the Glicko-2 system", 2012). The
+* function uses the Illinois algorithm for the new volatility. The games use the ratings of the opponents from the
+* start of the period. An empty list of games gives `glicko2Idle(player)`.
+*/
+function glicko2Update(player, games, options = {}) {
+	checkedRating("glicko2Update", player);
+	const tau = options.tau ?? .5;
+	const tolerance = options.tolerance ?? 1e-6;
+	positive("glicko2Update", "tau", tau);
+	positive("glicko2Update", "the tolerance", tolerance);
+	for (const game of games) {
+		finite("glicko2Update", "the rating of an opponent", game.rating);
+		positive("glicko2Update", "the RD of an opponent", game.rd);
+		if (!(game.score >= 0 && game.score <= 1)) throw new RangeError(`glicko2Update: a score is from 0 to 1, not ${game.score}.`);
+	}
+	if (games.length === 0) return glicko2Idle(player);
+	const mu = (player.rating - GLICKO2_CENTER) / GLICKO2_FACTOR;
+	const phi = player.rd / GLICKO2_FACTOR;
+	const sigma = player.volatility;
+	let information = 0;
+	let improvement = 0;
+	for (const game of games) {
+		const muJ = (game.rating - GLICKO2_CENTER) / GLICKO2_FACTOR;
+		const phiJ = game.rd / GLICKO2_FACTOR;
+		const g = 1 / Math.sqrt(1 + 3 * phiJ * phiJ / (Math.PI * Math.PI));
+		const e = 1 / (1 + Math.exp(-g * (mu - muJ)));
+		information += g * g * e * (1 - e);
+		improvement += g * (game.score - e);
+	}
+	const v = 1 / information;
+	const newSigma = newVolatility(phi, sigma, v, v * improvement, tau, tolerance);
+	const phiStar = Math.sqrt(phi * phi + newSigma * newSigma);
+	const newPhi = 1 / Math.sqrt(1 / (phiStar * phiStar) + 1 / v);
+	const newMu = mu + newPhi * newPhi * improvement;
+	return {
+		rating: GLICKO2_FACTOR * newMu + GLICKO2_CENTER,
+		rd: GLICKO2_FACTOR * newPhi,
+		volatility: newSigma
+	};
+}
+/** Step 5 of the paper: the new volatility, by the Illinois algorithm on `x = ln(sigma^2)`. */
+function newVolatility(phi, sigma, v, delta, tau, tolerance) {
+	const a = Math.log(sigma * sigma);
+	const phi2 = phi * phi;
+	const delta2 = delta * delta;
+	const f = (x) => {
+		const ex = Math.exp(x);
+		const sum = phi2 + v + ex;
+		return ex * (delta2 - phi2 - v - ex) / (2 * sum * sum) - (x - a) / (tau * tau);
+	};
+	let lowEnd = a;
+	let highEnd;
+	if (delta2 > phi2 + v) highEnd = Math.log(delta2 - phi2 - v);
+	else {
+		let k = 1;
+		while (f(a - k * tau) < 0 && k < VOLATILITY_STEPS) k++;
+		highEnd = a - k * tau;
+	}
+	let fLow = f(lowEnd);
+	let fHigh = f(highEnd);
+	for (let step = 0; Math.abs(highEnd - lowEnd) > tolerance && step < VOLATILITY_STEPS; step++) {
+		const c = lowEnd + (lowEnd - highEnd) * fLow / (fHigh - fLow);
+		const fC = f(c);
+		if (fC * fHigh <= 0) {
+			lowEnd = highEnd;
+			fLow = fHigh;
+		} else fLow /= 2;
+		highEnd = c;
+		fHigh = fC;
+	}
+	return Math.exp(lowEnd / 2);
+}
+/**
+* The Glicko-2 rating of a player after a rating period with no games. The rating and the volatility stay the same.
+* The RD grows to `sqrt(RD^2 + (173.7178 * volatility)^2)`.
+*/
+function glicko2Idle(player) {
+	checkedRating("glicko2Idle", player);
+	const phi = player.rd / GLICKO2_FACTOR;
+	const rd = GLICKO2_FACTOR * Math.sqrt(phi * phi + player.volatility * player.volatility);
+	return {
+		rating: player.rating,
+		rd,
+		volatility: player.volatility
+	};
+}
+/**
+* This function gives the three probabilities of a pair from the log-strengths `sa` and `sb` and the Davidson tie
+* parameter `nu`. The denominator is `exp(d / 2) + exp(-d / 2) + nu`, with `d = sa - sb`. The function does no
+* checks, because the fit uses it in its inner loop.
+*/
+function pairOutcomes(sa, sb, nu) {
+	const half = (sa - sb) / 2;
+	const top = Math.max(Math.abs(half), nu > 0 ? Math.log(nu) : Number.NEGATIVE_INFINITY);
+	const ea = Math.exp(half - top);
+	const eb = Math.exp(-half - top);
+	const et = nu > 0 ? Math.exp(Math.log(nu) - top) : 0;
+	const sum = ea + eb + et;
+	return {
+		a: ea / sum,
+		b: eb / sum,
+		tie: et / sum
+	};
+}
+/**
+* The probabilities of a pair under the Bradley-Terry model with Davidson (1970) ties. The inputs are the
+* log-strengths of the two items and the tie parameter `tie` of `bradleyTerry`. With `tie` 0, the probability that
+* the first item wins is `1 / (1 + exp(sb - sa))`. A constant added to the two strengths changes no probability.
+*/
+function pairProbabilities(sa, sb, tie = 0) {
+	finite("pairProbabilities", "the first strength", sa);
+	finite("pairProbabilities", "the second strength", sb);
+	if (!(tie >= 0 && Number.isFinite(tie))) throw new RangeError(`pairProbabilities: the tie parameter is a finite number of 0 or more, not ${tie}.`);
+	return pairOutcomes(sa, sb, tie);
+}
+/**
+* The rating of a log-strength: `center + scale * strength / ln(base)`. The defaults give
+* `1500 + 400 * log10(e) * strength`. Thus `eloExpected` of two ratings is the Bradley-Terry win probability.
+*/
+function strengthToRating(strength, options = {}) {
+	finite("strengthToRating", "the strength", strength);
+	const { center, scale, base } = checkedScale("strengthToRating", options);
+	return center + scale * strength / Math.log(base);
+}
+/** The log-strength of a rating. It is the inverse of `strengthToRating` with the same options. */
+function ratingToStrength(rating, options = {}) {
+	finite("ratingToStrength", "the rating", rating);
+	const { center, scale, base } = checkedScale("ratingToStrength", options);
+	return (rating - center) * Math.log(base) / scale;
+}
+// src/bradley-terry.ts
+/**
+* The Bradley-Terry fit of pairwise comparisons among `n` items. Each item has a log-strength. The fit is the
+* maximum a posteriori estimate with a normal (ridge) prior on each log-strength. Thus an item with only wins has a
+* finite strength, and the strengths have one solution.
+*
+* Ties use the Davidson (1970) model, or count as half a win and half a loss. The fit uses Newton steps with a line search on the negative log posterior. This function is
+* convex, so the steps go to its one minimum.
+*/
+const ARMIJO = 1e-4;
+const HALVINGS = 60;
+const ROUNDING = 64 * Number.EPSILON;
+function checkedTerms(n, comparisons, ties) {
+	const terms = [];
+	for (const [i, comparison] of comparisons.entries()) {
+		const { a, b, outcome } = comparison;
+		const w = comparison.weight ?? 1;
+		for (const index of [a, b]) if (!Number.isSafeInteger(index) || index < 0 || index >= n) throw new RangeError(`bradleyTerry: comparison ${i} has the index ${index}, and the indexes are whole numbers from 0 to ${n - 1}.`);
+		if (a === b) throw new RangeError(`bradleyTerry: comparison ${i} compares the item ${a} with itself.`);
+		if (outcome !== "a" && outcome !== "b" && outcome !== "tie") throw new RangeError(`bradleyTerry: comparison ${i} has the outcome ${String(outcome)}.`);
+		if (!(w >= 0 && Number.isFinite(w))) throw new RangeError(`bradleyTerry: comparison ${i} has the weight ${w}, and a weight is a finite number of 0 or more.`);
+		if (w === 0) continue;
+		const c = outcome === "a" ? .5 : outcome === "b" ? -.5 : 0;
+		terms.push({
+			a,
+			b,
+			w,
+			c,
+			tie: outcome === "tie" && ties === "davidson" ? 1 : 0
+		});
+	}
+	return terms;
+}
+function positiveOption(label, value) {
+	if (!(value > 0 && Number.isFinite(value))) throw new RangeError(`bradleyTerry: ${label} is a finite number above 0, not ${value}.`);
+}
+/**
+* The Bradley-Terry fit of `comparisons` among `items` items. The function does not sort or change its inputs. An
+* empty list of comparisons gives the prior for each item. The function throws a RangeError for a bad index, a bad
+* outcome, a bad weight and a bad option.
+*/
+function bradleyTerry(items, comparisons, options = {}) {
+	if (!Number.isSafeInteger(items) || items < 1) throw new RangeError(`bradleyTerry: the number of items is a whole number of 1 or more, not ${items}.`);
+	const priorMean = options.priorMean ?? 0;
+	const priorSd = options.priorSd ?? 1;
+	const ties = options.ties ?? "davidson";
+	const tiePriorSd = options.tiePriorSd ?? 10;
+	const maxIterations = options.maxIterations ?? 100;
+	const tolerance = options.tolerance ?? 1e-10;
+	if (!Number.isFinite(priorMean)) throw new RangeError(`bradleyTerry: the prior mean is a finite number, not ${priorMean}.`);
+	positiveOption("the prior SD", priorSd);
+	positiveOption("the tie prior SD", tiePriorSd);
+	positiveOption("the tolerance", tolerance);
+	if (ties !== "davidson" && ties !== "half") throw new RangeError(`bradleyTerry: the tie model is "davidson" or "half", not ${String(ties)}.`);
+	if (!Number.isSafeInteger(maxIterations) || maxIterations < 1) throw new RangeError(`bradleyTerry: maxIterations is a whole number of 1 or more, not ${maxIterations}.`);
+	const terms = checkedTerms(items, comparisons, ties);
+	const fitTie = terms.some((t) => t.tie === 1);
+	const k = fitTie ? items + 1 : items;
+	const model = {
+		items,
+		terms,
+		fitTie,
+		priorMean,
+		priorPrecision: 1 / (priorSd * priorSd),
+		tiePrecision: 1 / (tiePriorSd * tiePriorSd)
+	};
+	const x = new Float64Array(k).fill(priorMean);
+	if (fitTie) x[items] = 0;
+	let iterations = 0;
+	let converged = false;
+	let value = objective(model, x);
+	while (iterations < maxIterations) {
+		iterations++;
+		const { gradient, hessian } = derivatives(model, x);
+		const step = solve(hessian, gradient, k);
+		let slope = 0;
+		for (let i = 0; i < k; i++) slope += gradient[i] * step[i];
+		let t = 1;
+		let next = moved(x, step, t);
+		let nextValue = objective(model, next);
+		const slack = ROUNDING * (Math.abs(value) + 1);
+		for (let h = 0; h < HALVINGS && !(nextValue <= value + ARMIJO * t * slope + slack); h++) {
+			t /= 2;
+			next = moved(x, step, t);
+			nextValue = objective(model, next);
+		}
+		let largest = 0;
+		for (let i = 0; i < k; i++) largest = Math.max(largest, Math.abs(step[i]));
+		if (nextValue <= value + slack) {
+			x.set(next);
+			value = nextValue;
+		}
+		if (largest <= tolerance) {
+			converged = true;
+			break;
+		}
+	}
+	const { hessian } = derivatives(model, x);
+	const variance = inverseDiagonal(hessian, k);
+	const nu = fitTie ? Math.exp(x[items]) : 0;
+	let logLikelihood = 0;
+	for (const term of terms) logLikelihood += term.w * termLogLikelihood(term, x[term.a], x[term.b], nu);
+	return {
+		strengths: Array.from(x.subarray(0, items)),
+		se: Array.from(variance.subarray(0, items), (v) => Math.sqrt(v)),
+		tie: nu,
+		logLikelihood,
+		iterations,
+		converged
+	};
+}
+function moved(x, step, t) {
+	const out = new Float64Array(x.length);
+	for (let i = 0; i < x.length; i++) out[i] = x[i] + t * step[i];
+	return out;
+}
+/** The log of the denominator `exp(d / 2) + exp(-d / 2) + nu`, with no overflow. */
+function logDenominator(d, logNu) {
+	const half = Math.abs(d) / 2;
+	const top = Math.max(half, logNu);
+	return top + Math.log(Math.exp(half - top) + Math.exp(-half - top) + Math.exp(logNu - top));
+}
+/** The log-likelihood of one comparison with weight 1. A `"half"` tie has the coefficient 0: the mean of the two log-probabilities of a win. */
+function termLogLikelihood(term, sa, sb, nu) {
+	const d = sa - sb;
+	const logNu = nu > 0 ? Math.log(nu) : Number.NEGATIVE_INFINITY;
+	const logD = logDenominator(d, logNu);
+	return term.tie === 1 ? logNu - logD : term.c * d - logD;
+}
+/** The negative log posterior at `x`. */
+function objective(model, x) {
+	const logNu = model.fitTie ? x[model.items] : Number.NEGATIVE_INFINITY;
+	let sum = 0;
+	for (const term of model.terms) {
+		const d = x[term.a] - x[term.b];
+		sum += term.w * (logDenominator(d, logNu) - term.c * d - (term.tie === 1 ? logNu : 0));
+	}
+	for (let i = 0; i < model.items; i++) sum += model.priorPrecision * (x[i] - model.priorMean) ** 2 / 2;
+	if (model.fitTie) sum += model.tiePrecision * logNu * logNu / 2;
+	return sum;
+}
+/** The gradient and the Hessian (in row order) of the negative log posterior at `x`. */
+function derivatives(model, x) {
+	const k = x.length;
+	const n = model.items;
+	const gradient = new Float64Array(k);
+	const hessian = new Float64Array(k * k);
+	const nu = model.fitTie ? Math.exp(x[n]) : 0;
+	for (const term of model.terms) {
+		const { a, b, w } = term;
+		const p = pairOutcomes(x[a], x[b], nu);
+		const q = (p.a - p.b) / 2;
+		const gd = w * (q - term.c);
+		const hdd = w * ((p.a + p.b) / 4 - q * q);
+		gradient[a] = gradient[a] + gd;
+		gradient[b] = gradient[b] - gd;
+		hessian[a * k + a] = hessian[a * k + a] + hdd;
+		hessian[b * k + b] = hessian[b * k + b] + hdd;
+		hessian[a * k + b] = hessian[a * k + b] - hdd;
+		hessian[b * k + a] = hessian[b * k + a] - hdd;
+		if (model.fitTie) {
+			const hdl = -w * q * p.tie;
+			gradient[n] = gradient[n] + w * (p.tie - term.tie);
+			hessian[n * k + n] = hessian[n * k + n] + w * p.tie * (1 - p.tie);
+			hessian[a * k + n] = hessian[a * k + n] + hdl;
+			hessian[n * k + a] = hessian[n * k + a] + hdl;
+			hessian[b * k + n] = hessian[b * k + n] - hdl;
+			hessian[n * k + b] = hessian[n * k + b] - hdl;
+		}
+	}
+	for (let i = 0; i < n; i++) {
+		gradient[i] = gradient[i] + model.priorPrecision * (x[i] - model.priorMean);
+		hessian[i * k + i] = hessian[i * k + i] + model.priorPrecision;
+	}
+	if (model.fitTie) {
+		gradient[n] = gradient[n] + model.tiePrecision * x[n];
+		hessian[n * k + n] = hessian[n * k + n] + model.tiePrecision;
+	}
+	return {
+		gradient,
+		hessian
+	};
+}
+/** The Cholesky factor of a copy of the Hessian. The priors make the Hessian positive definite. */
+function factored(hessian, k) {
+	const l = Float64Array.from(hessian);
+	if (!factor(l, k)) throw new RangeError("bradleyTerry: the Hessian is not positive definite. Make the prior SD smaller.");
+	return l;
+}
+/** The Newton step: the solution of `hessian * step = -gradient`. */
+function solve(hessian, gradient, k) {
+	const l = factored(hessian, k);
+	const y = new Float64Array(k);
+	for (let i = 0; i < k; i++) {
+		let s = -gradient[i];
+		for (let j = 0; j < i; j++) s -= l[i * k + j] * y[j];
+		y[i] = s / l[i * k + i];
+	}
+	for (let i = k - 1; i >= 0; i--) {
+		let s = y[i];
+		for (let j = i + 1; j < k; j++) s -= l[j * k + i] * y[j];
+		y[i] = s / l[i * k + i];
+	}
+	return y;
+}
+/** The diagonal of the inverse of the Hessian: the column sums of the squares of the inverse of its Cholesky factor. */
+function inverseDiagonal(hessian, k) {
+	const l = factored(hessian, k);
+	const out = new Float64Array(k);
+	const column = new Float64Array(k);
+	for (let c = 0; c < k; c++) {
+		column.fill(0);
+		for (let i = c; i < k; i++) {
+			let s = i === c ? 1 : 0;
+			for (let j = c; j < i; j++) s -= l[i * k + j] * column[j];
+			column[i] = s / l[i * k + i];
+		}
+		let sum = 0;
+		for (let i = c; i < k; i++) sum += column[i] ** 2;
+		out[c] = sum;
+	}
+	return out;
+}
+export { KENDALL_EXACT, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, U_STATISTIC_TIGHT_MIN_SAMPLE, Z95, bestSmoothLaw, binomialInterval, binomialTest, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapTwo, bradleyTerry, brier, calibration, cohenKappa, compareRatios, coverageMinSample, eloExpected, eloUpdate, fitResponse, glicko2Idle, glicko2Update, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, logLoss, mean, median, medianInterval, modeCount, negativeBinomialInterval, noiseFloor, noiseVerdict, optionFloor, pairProbabilities, pairedPermutation, parseResponseRecord, partialConjunction, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, ratingToStrength, responseCells, ridgeSolve, sampleTotalInterval, sd, signTest, signTestPower, sliceResponse, smoothLawScores, sorted, spearman, strengthToRating, summarize, surfaceResponse, tQuantile, twoSamplePermutation, uStatisticInterval, whenHolds, wilson, wilsonSampleSize };
 
 //# sourceMappingURL=index.js.map