@mark1russell7/rigor-statistics 0.1.27 → 0.1.29

package/build/index.js

@@ -3844,7 +3844,7 @@ function ratingToStrength(rating, options = {}) {
 */
 const ARMIJO = 1e-4;
 const HALVINGS = 60;
-const ROUNDING = 64 * Number.EPSILON;
+const ROUNDING$1 = 64 * Number.EPSILON;
 function checkedTerms(n, comparisons, ties) {
 	const terms = [];
 	for (const [i, comparison] of comparisons.entries()) {
@@ -3866,7 +3866,7 @@ function checkedTerms(n, comparisons, ties) {
 	}
 	return terms;
 }
-function positiveOption(label, value) {
+function positiveOption$1(label, value) {
 	if (!(value > 0 && Number.isFinite(value))) throw new RangeError(`bradleyTerry: ${label} is a finite number above 0, not ${value}.`);
 }
 /**
@@ -3883,9 +3883,9 @@ function bradleyTerry(items, comparisons, options = {}) {
 	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);
+	positiveOption$1("the prior SD", priorSd);
+	positiveOption$1("the tie prior SD", tiePriorSd);
+	positiveOption$1("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);
@@ -3913,7 +3913,7 @@ function bradleyTerry(items, comparisons, options = {}) {
 		let t = 1;
 		let next = moved(x, step, t);
 		let nextValue = objective(model, next);
-		const slack = ROUNDING * (Math.abs(value) + 1);
+		const slack = ROUNDING$1 * (Math.abs(value) + 1);
 		for (let h = 0; h < HALVINGS && !(nextValue <= value + ARMIJO * t * slope + slack); h++) {
 			t /= 2;
 			next = moved(x, step, t);
@@ -4056,6 +4056,519 @@ function inverseDiagonal(hessian, k) {
 	}
 	return out;
 }
-export { EMPTY_RUNNING, KENDALL_EXACT, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, SIGN_FLIP_EXACT_LIMIT, SIGN_FLIP_EXACT_MAX, U_STATISTIC_TIGHT_MIN_SAMPLE, Z95, addToRunning, bestSmoothLaw, binomialInterval, binomialTest, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapStrata, bootstrapTwo, bradleyTerry, brier, calibration, cohenKappa, compareRatios, coverageMinSample, eloExpected, eloUpdate, fitResponse, glicko2Idle, glicko2Update, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, logLoss, mean, median, medianInterval, mergeRunning, modeCount, negativeBinomialInterval, noiseFloor, noiseVerdict, normalCdf, normalQuantile, optionFloor, pairProbabilities, pairedPermutation, parseResponseRecord, partialConjunction, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, ratingToStrength, responseCells, ridgeSolve, runningMean, runningOf, runningSd, sampleTotalInterval, sd, signFlipTest, signTest, signTestPower, sliceResponse, smoothLawScores, sobolIndices, sorted, spearman, strengthToRating, summarize, surfaceResponse, tQuantile, twoSamplePermutation, uStatisticInterval, whenHolds, wilson, wilsonSampleSize };
+// src/bradley-terry-sparse.ts
+/** The largest number of items. The key of a pair is `low * items + high`, and it must be a safe integer. */
+const MAX_ITEMS = Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER));
+const ROUNDING = 64 * Number.EPSILON;
+const NAME = "bradleyTerrySparse";
+function positiveOption(label, value) {
+	if (!(value > 0 && Number.isFinite(value))) throw new RangeError(`${NAME}: ${label} is a finite number above 0, not ${value}.`);
+}
+/** This function checks the comparisons, and sums them for each distinct pair. A comparison with the weight 0 adds nothing. */
+function pairsOf(items, comparisons, ties) {
+	const index = /* @__PURE__ */ new Map();
+	const low = [];
+	const high = [];
+	const total = [];
+	const net = [];
+	const tie = [];
+	for (const [i, comparison] of comparisons.entries()) {
+		const { a, b, outcome } = comparison;
+		const w = comparison.weight ?? 1;
+		for (const item of [a, b]) if (!Number.isSafeInteger(item) || item < 0 || item >= items) throw new RangeError(`${NAME}: comparison ${i} has the index ${item}, and the indexes are whole numbers from 0 to ${items - 1}.`);
+		if (a === b) throw new RangeError(`${NAME}: comparison ${i} compares the item ${a} with itself.`);
+		if (outcome !== "a" && outcome !== "b" && outcome !== "tie") throw new RangeError(`${NAME}: comparison ${i} has the outcome ${String(outcome)}.`);
+		if (!(w >= 0 && Number.isFinite(w))) throw new RangeError(`${NAME}: comparison ${i} has the weight ${w}, and a weight is a finite number of 0 or more.`);
+		if (w === 0) continue;
+		const lo = Math.min(a, b);
+		const hi = Math.max(a, b);
+		const key = lo * items + hi;
+		let p = index.get(key);
+		if (p === void 0) {
+			p = low.length;
+			index.set(key, p);
+			low.push(lo);
+			high.push(hi);
+			total.push(0);
+			net.push(0);
+			tie.push(0);
+		}
+		total[p] = total[p] + w;
+		if (outcome === "tie") {
+			if (ties === "davidson") tie[p] = tie[p] + w;
+		} else {
+			const winner = outcome === "a" ? a : b;
+			net[p] = net[p] + (winner === lo ? w : -w);
+		}
+	}
+	return {
+		count: low.length,
+		low: Int32Array.from(low),
+		high: Int32Array.from(high),
+		total: Float64Array.from(total),
+		net: Float64Array.from(net),
+		ties: Float64Array.from(tie)
+	};
+}
+/** The connected groups of the items: the group of each item, and the size of each group. */
+function groupsOf(items, pairs) {
+	const parent = new Int32Array(items);
+	for (let i = 0; i < items; i++) parent[i] = i;
+	const root = (i) => {
+		let r = i;
+		while (parent[r] !== r) r = parent[r];
+		for (let j = i; parent[j] !== r;) {
+			const next = parent[j];
+			parent[j] = r;
+			j = next;
+		}
+		return r;
+	};
+	for (let p = 0; p < pairs.count; p++) {
+		const x = root(pairs.low[p]);
+		const y = root(pairs.high[p]);
+		if (x !== y) parent[Math.max(x, y)] = Math.min(x, y);
+	}
+	const group = new Int32Array(items).fill(-1);
+	const ids = new Int32Array(items).fill(-1);
+	let count = 0;
+	for (let i = 0; i < items; i++) {
+		const r = root(i);
+		if (ids[r] === -1) ids[r] = count++;
+		group[i] = ids[r];
+	}
+	const size = new Float64Array(count);
+	for (let i = 0; i < items; i++) size[group[i]] = size[group[i]] + 1;
+	return {
+		group,
+		size,
+		count
+	};
+}
+/**
+* The probabilities of the three outcomes of a pair with the difference `d` of the log-strengths, and the log of the
+* denominator `exp(d / 2) + exp(-d / 2) + nu`. The function writes them into `out`, so the loops make no objects.
+*/
+function outcomes(d, logNu, out) {
+	const half = d / 2;
+	const top = Math.max(Math.abs(half), logNu);
+	const ea = Math.exp(half - top);
+	const eb = Math.exp(-half - top);
+	const et = Math.exp(logNu - top);
+	const sum = ea + eb + et;
+	out[0] = ea / sum;
+	out[1] = eb / sum;
+	out[2] = et / sum;
+	out[3] = top + Math.log(sum);
+}
+/**
+* The minimum over `z` of `s * exp(z) + tau * (lambda + z) ^ 2 / 2 - t * z`: the root of
+* `s * exp(z) + tau * z = t - tau * lambda`. The left side increases and is convex. Newton steps from a point right of
+* the root thus go down to the root, and they do not go past it.
+*/
+function tieStep(s, t, tau, lambda) {
+	const c = t - tau * lambda;
+	if (s === 0) return c / tau;
+	let z = c > 0 ? Math.max(0, Math.log(c / s)) : 0;
+	for (let step = 0; step < 200; step++) {
+		const ez = s * Math.exp(z);
+		const move = (ez + tau * z - c) / (ez + tau);
+		z -= move;
+		if (!(Math.abs(move) > ROUNDING * (1 + Math.abs(z)))) break;
+	}
+	return z;
+}
+/**
+* The sparse Bradley-Terry fit of `comparisons` among `items` items. It has the model, the options and the checks of
+* `bradleyTerry`, and its memory is in proportion to `items` plus the distinct pairs. The function does not sort or
+* change its inputs. It throws a RangeError for a bad index, a bad outcome, a bad weight and a bad option.
+*/
+function bradleyTerrySparse(items, comparisons, options = {}) {
+	if (!Number.isSafeInteger(items) || items < 1 || items > MAX_ITEMS) throw new RangeError(`${NAME}: the number of items is a whole number from 1 to ${MAX_ITEMS}, 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 ?? 1e4;
+	const tolerance = options.tolerance ?? 1e-8;
+	if (!Number.isFinite(priorMean)) throw new RangeError(`${NAME}: 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(`${NAME}: the tie model is "davidson" or "half", not ${String(ties)}.`);
+	if (!Number.isSafeInteger(maxIterations) || maxIterations < 1) throw new RangeError(`${NAME}: maxIterations is a whole number of 1 or more, not ${maxIterations}.`);
+	const pairs = pairsOf(items, comparisons, ties);
+	const { group, size, count: groupCount } = groupsOf(items, pairs);
+	const p = 1 / (priorSd * priorSd);
+	const tau = 1 / (tiePriorSd * tiePriorSd);
+	let tieWeight = 0;
+	let totalWeight = 0;
+	const weight = new Float64Array(items);
+	for (let q = 0; q < pairs.count; q++) {
+		tieWeight += pairs.ties[q];
+		totalWeight += pairs.total[q];
+		weight[pairs.low[q]] = weight[pairs.low[q]] + pairs.total[q];
+		weight[pairs.high[q]] = weight[pairs.high[q]] + pairs.total[q];
+	}
+	const fitTie = tieWeight > 0;
+	const smallest = fitTie ? Math.min(p, tau) : p;
+	const floor = 4 * Number.EPSILON * (totalWeight + 1);
+	const s = new Float64Array(items).fill(priorMean);
+	const gradient = new Float64Array(items);
+	const sums = new Float64Array(groupCount);
+	const out = /* @__PURE__ */ new Float64Array(4);
+	let lambda = 0;
+	let iterations = 0;
+	let bound = Number.POSITIVE_INFINITY;
+	let rounded = false;
+	for (;;) {
+		const logNu = fitTie ? lambda : Number.NEGATIVE_INFINITY;
+		for (let i = 0; i < items; i++) gradient[i] = p * (s[i] - priorMean);
+		let tieGradient = fitTie ? tau * lambda - tieWeight : 0;
+		for (let q = 0; q < pairs.count; q++) {
+			const lo = pairs.low[q];
+			const hi = pairs.high[q];
+			const total = pairs.total[q];
+			outcomes(s[lo] - s[hi], logNu, out);
+			const g = total * ((out[0] - out[1]) / 2) - pairs.net[q] / 2;
+			gradient[lo] = gradient[lo] + g;
+			gradient[hi] = gradient[hi] - g;
+			if (fitTie) tieGradient += total * out[2];
+		}
+		let norm = tieGradient * tieGradient;
+		for (let i = 0; i < items; i++) norm += gradient[i] ** 2;
+		norm = Math.sqrt(norm);
+		bound = norm / smallest;
+		rounded = norm <= floor;
+		if (bound <= tolerance || rounded || iterations >= maxIterations) break;
+		iterations++;
+		for (let i = 0; i < items; i++) s[i] = s[i] - gradient[i] / (weight[i] / 2 + p);
+		sums.fill(0);
+		for (let i = 0; i < items; i++) sums[group[i]] = sums[group[i]] + s[i];
+		for (let i = 0; i < items; i++) s[i] = s[i] + priorMean - sums[group[i]] / size[group[i]];
+		if (fitTie) {
+			let expected = 0;
+			for (let q = 0; q < pairs.count; q++) {
+				outcomes(s[pairs.low[q]] - s[pairs.high[q]], lambda, out);
+				expected += pairs.total[q] * out[2];
+			}
+			lambda += tieStep(expected, tieWeight, tau, lambda);
+		}
+	}
+	const logNu = fitTie ? lambda : Number.NEGATIVE_INFINITY;
+	const diagonal = new Float64Array(items).fill(p);
+	let logLikelihood = 0;
+	for (let q = 0; q < pairs.count; q++) {
+		const lo = pairs.low[q];
+		const hi = pairs.high[q];
+		const total = pairs.total[q];
+		const d = s[lo] - s[hi];
+		outcomes(d, logNu, out);
+		const half = (out[0] - out[1]) / 2;
+		const curvature = total * ((out[0] + out[1]) / 4 - half * half);
+		diagonal[lo] = diagonal[lo] + curvature;
+		diagonal[hi] = diagonal[hi] + curvature;
+		logLikelihood += pairs.net[q] / 2 * d - total * out[3] + (fitTie ? pairs.ties[q] * lambda : 0);
+	}
+	const se = Array.from(s, (_, i) => {
+		const n = size[group[i]];
+		return Math.sqrt(1 / (n * p) + (1 - 1 / n) / diagonal[i]);
+	});
+	return {
+		strengths: Array.from(s),
+		se,
+		tie: fitTie ? Math.exp(lambda) : 0,
+		logLikelihood,
+		iterations,
+		converged: bound <= tolerance || rounded,
+		bound,
+		pairs: pairs.count
+	};
+}
+// src/rating-models.ts
+/**
+* The rating models of a log of picks. The Elo and the Glicko-2 replays read the picks in their order. The
+* Bradley-Terry fit reads the whole log at one time. The choice of a model compares the log-loss of each model on the
+* last picks of the log. Each function is pure: the same log gives the same result.
+*/
+/** The score of the first item of a pick: 1 for a win, 0.5 for a tie and 0 for a loss. */
+const SCORE = {
+	a: 1,
+	b: 0,
+	tie: .5
+};
+/** This function checks the indexes and the outcomes of `comparisons`. With `ordered`, it also refuses a weight other than 1. */
+function checkedPicks(name, items, comparisons, ordered) {
+	if (!Number.isSafeInteger(items) || items < 0) throw new RangeError(`${name}: the number of items is a whole number of 0 or more, not ${items}.`);
+	for (const [i, { a, b, outcome, weight }] of comparisons.entries()) {
+		for (const index of [a, b]) if (!Number.isSafeInteger(index) || index < 0 || index >= items) throw new RangeError(`${name}: pick ${i} has the index ${index}, and the indexes are whole numbers from 0 to ${items - 1}.`);
+		if (a === b) throw new RangeError(`${name}: pick ${i} compares the item ${a} with itself.`);
+		if (outcome !== "a" && outcome !== "b" && outcome !== "tie") throw new RangeError(`${name}: pick ${i} has the outcome ${String(outcome)}.`);
+		if (ordered && weight !== void 0 && weight !== 1) throw new RangeError(`${name}: pick ${i} has the weight ${weight}. An ordered replay makes one update for each pick, so each weight is 1.`);
+	}
+}
+/**
+* The Elo ratings of `items` items after each pick of `comparisons`, in the order of the list. Each item starts at
+* `start`. The update of each pick is `eloUpdate` with the options. The order of the picks changes the result.
+*/
+function eloReplay(items, comparisons, options = {}) {
+	checkedPicks("eloReplay", items, comparisons, true);
+	const start = options.start ?? 1500;
+	if (!Number.isFinite(start)) throw new RangeError(`eloReplay: the start rating is a finite number, not ${start}.`);
+	eloUpdate(start, start, .5, options);
+	const ratings = new Array(items).fill(start);
+	for (const { a, b, outcome } of comparisons) {
+		const next = eloUpdate(ratings[a], ratings[b], SCORE[outcome], options);
+		ratings[a] = next.a;
+		ratings[b] = next.b;
+	}
+	return ratings;
+}
+/**
+* The Glicko-2 ratings of `items` items after each pick of `comparisons`, in the order of the list. Each pick is one
+* rating period of its two items. Each item of a pick gets `glicko2Update` against the rating of the other item before
+* the pick. An item that is not in a pick does not change in that period. The order of the picks changes the result.
+*/
+function glicko2Replay(items, comparisons, options = {}) {
+	checkedPicks("glicko2Replay", items, comparisons, true);
+	const start = options.start ?? {
+		rating: 1500,
+		rd: 350,
+		volatility: .06
+	};
+	glicko2Update(start, [], options);
+	const players = Array.from({ length: items }, () => ({
+		rating: start.rating,
+		rd: start.rd,
+		volatility: start.volatility
+	}));
+	for (const { a, b, outcome } of comparisons) {
+		const pa = players[a];
+		const pb = players[b];
+		players[a] = glicko2Update(pa, [{
+			rating: pb.rating,
+			rd: pb.rd,
+			score: SCORE[outcome]
+		}], options);
+		players[b] = glicko2Update(pb, [{
+			rating: pa.rating,
+			rd: pa.rd,
+			score: 1 - SCORE[outcome]
+		}], options);
+	}
+	return players;
+}
+/** The default largest number of items of the dense Bradley-Terry fit in `fitRatings`. */
+const BRADLEY_TERRY_DENSE_LIMIT = 200;
+/**
+* The log-strengths of `items` items with one rating model. The model `"bradley-terry"` uses `bradleyTerry`, or
+* `bradleyTerrySparse` above `denseLimit` items. The models `"elo"` and `"glicko2"` use `eloReplay` and
+* `glicko2Replay`, and they refuse a weight other than 1. A log of 0 items gives empty lists.
+*/
+function fitRatings(model, items, comparisons, options = {}) {
+	checkedPicks("fitRatings", items, comparisons, model !== "bradley-terry");
+	const denseLimit = options.denseLimit ?? 200;
+	if (!(denseLimit >= 0)) throw new RangeError(`fitRatings: denseLimit is a number of 0 or more, not ${denseLimit}.`);
+	if (items === 0) return {
+		strengths: [],
+		se: [],
+		tie: 0
+	};
+	switch (model) {
+		case "bradley-terry": {
+			const fit = items <= denseLimit ? bradleyTerry(items, comparisons, options.bradleyTerry) : bradleyTerrySparse(items, comparisons, options.bradleyTerry);
+			return {
+				strengths: fit.strengths,
+				se: fit.se,
+				tie: fit.tie
+			};
+		}
+		case "elo": {
+			const ratings = eloReplay(items, comparisons, options.elo);
+			return {
+				strengths: ratings.map((rating) => ratingToStrength(rating, options.elo)),
+				se: ratings.map(() => void 0),
+				tie: 0
+			};
+		}
+		case "glicko2": {
+			const players = glicko2Replay(items, comparisons, options.glicko2);
+			return {
+				strengths: players.map((player) => ratingToStrength(player.rating)),
+				se: players.map((player) => ratingToStrength(1500 + player.rd)),
+				tie: 0
+			};
+		}
+		default: throw new RangeError(`fitRatings: the model is "bradley-terry", "elo" or "glicko2", not ${String(model)}.`);
+	}
+}
+/** The lowest probability of a forecast. An outcome with a probability of 0 gives a log-loss of Infinity. */
+const FORECAST_FLOOR = 1e-9;
+/**
+* The choice of a rating model by the log-loss on held-out picks. Each model learns from the first picks of the log
+* and forecasts the last `holdout` part. All models use the tie parameter of the Bradley-Terry fit of the first picks.
+* Thus the strengths are the only difference. Two equal scores keep the order of `models`. Each pick has the weight 1.
+*/
+function selectRatingModel(items, comparisons, options = {}) {
+	checkedPicks("selectRatingModel", items, comparisons, true);
+	const holdout = options.holdout ?? .2;
+	const minimum = options.minimum ?? 30;
+	const models = options.models ?? [
+		"bradley-terry",
+		"elo",
+		"glicko2"
+	];
+	if (!(holdout > 0 && holdout < 1)) throw new RangeError(`selectRatingModel: the holdout is above 0 and below 1, not ${holdout}.`);
+	if (!Number.isSafeInteger(minimum) || minimum < 0) throw new RangeError(`selectRatingModel: the minimum is a whole number of 0 or more, not ${minimum}.`);
+	if (models.length === 0) throw new RangeError("selectRatingModel: the list of models is empty.");
+	for (const model of models) if (model !== "bradley-terry" && model !== "elo" && model !== "glicko2") throw new RangeError(`selectRatingModel: a model is "bradley-terry", "elo" or "glicko2", not ${String(model)}.`);
+	const tested = Math.floor(comparisons.length * holdout);
+	if (comparisons.length < minimum || tested < 1) return {
+		model: "bradley-terry",
+		scores: [],
+		trained: comparisons.length,
+		tested: 0
+	};
+	const train = comparisons.slice(0, comparisons.length - tested);
+	const test = comparisons.slice(comparisons.length - tested);
+	const bradley = fitRatings("bradley-terry", items, train, options);
+	const scores = models.map((model) => {
+		const { strengths } = model === "bradley-terry" ? bradley : fitRatings(model, items, train, options);
+		return {
+			model,
+			logLoss: logLoss(test.map(({ a, b, outcome }) => {
+				const p = pairProbabilities(strengths[a], strengths[b], bradley.tie)[outcome];
+				return {
+					p: Math.max(p, FORECAST_FLOOR),
+					hit: true
+				};
+			}))
+		};
+	});
+	scores.sort((x, y) => x.logLoss - y.logLoss);
+	return {
+		model: scores[0].model,
+		scores,
+		trained: train.length,
+		tested
+	};
+}
+// src/pair-choice.ts
+/**
+* The choice of the next pair of a duel. A good pair has a result that is not sure: two items with near ratings, or
+* items with few picks. The choice uses a seed of `@mark1russell7/rigor-generators`, so a seed gives the same pair again.
+*/
+/**
+* The uncertainty of an item with no standard error and no picks, in rating points. It is the first RD of Glicko-2.
+* An item with no standard error has the uncertainty `350 / sqrt(1 + picks)`.
+*/
+const RATING_START_UNCERTAINTY = 350;
+/** The largest pool of items for a full search of a pair that is not recent. */
+const PAIR_FULL_SEARCH = 64;
+/** The uncertainty of a rating, in rating points: its standard error, or `RATING_START_UNCERTAINTY / sqrt(1 + picks)`. */
+function ratingUncertainty(item) {
+	return item.se ?? 350 / Math.sqrt(1 + item.picks);
+}
+/**
+* The expected information of a pick between two items: `p * (1 - p) * (ua^2 + ub^2)`. Here `p` is `eloExpected` of
+* the two ratings, and `ua` and `ub` are the uncertainties. The value is high when the result is not sure (a `p` near
+* 0.5) and the two ratings are not sure.
+*/
+function pairInformation(a, b, options = {}) {
+	const p = eloExpected(a.rating, b.rating, options);
+	return p * (1 - p) * (ratingUncertainty(a) ** 2 + ratingUncertainty(b) ** 2);
+}
+const pairKey = (a, b) => a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+/**
+* The indexes of the second items to examine: the neighbors in the order, and random items. Only the indexes in
+* `allowed` are candidates.
+*/
+function candidatesOf(first, allowed, size, count, draw) {
+	if (allowed.size <= count) return [...allowed].sort((x, y) => x - y);
+	const chosen = /* @__PURE__ */ new Set();
+	const near = Math.ceil(count / 2);
+	for (let step = 1; chosen.size < near && step < size; step++) {
+		if (allowed.has(first - step)) chosen.add(first - step);
+		if (chosen.size < near && allowed.has(first + step)) chosen.add(first + step);
+	}
+	while (chosen.size < count) {
+		const index = draw(size);
+		if (allowed.has(index)) chosen.add(index);
+	}
+	return [...chosen];
+}
+/**
+* The choice of the next pair of a duel from a pool of rated items. The pool goes in the order of the ratings, from
+* the highest. These are the steps:
+*
+* 1. A draw selects the first item. The weight of an item is `1 / (1 + picks)`, so the items with few picks come first.
+*    An item with no permitted pair leaves the draw.
+* 2. The second item is the candidate with the most information. The candidates are the neighbors of the first item in
+*    the order, and random items, each in a permitted pair. A recent pair loses to each pair that is not recent.
+* 3. A draw selects the left and the right side, so the side does not change the picks.
+*
+* In a pool of `PAIR_FULL_SEARCH` items or fewer, a recent pair comes only when each permitted pair is recent. The
+* function gives `undefined` when there is no permitted pair. Each step has its own stream of the seed.
+*/
+function choosePair(items, options) {
+	const candidates = options.candidates ?? 24;
+	if (!Number.isSafeInteger(candidates) || candidates < 1) throw new RangeError(`choosePair: candidates is a whole number of 1 or more, not ${candidates}.`);
+	for (const item of items) {
+		if (!Number.isFinite(item.rating)) throw new RangeError(`choosePair: the item ${item.id} has the rating ${item.rating}, and a rating is a finite number.`);
+		if (!Number.isSafeInteger(item.picks) || item.picks < 0) throw new RangeError(`choosePair: the item ${item.id} has ${item.picks} picks, and a count of picks is a whole number of 0 or more.`);
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const pool = items.filter((item) => !seen.has(item.id) && seen.add(item.id)).sort((x, y) => y.rating - x.rating);
+	if (pool.length < 2) return void 0;
+	const draw = random(options.seed);
+	const recent = new Set((options.recent ?? []).map(([a, b]) => pairKey(a, b)));
+	const at = (i) => pool[i];
+	const isRecent = (i, j) => recent.has(pairKey(at(i).id, at(j).id));
+	const information = options.information ?? ((a, b) => pairInformation(a, b));
+	const informationOf = (i, j) => {
+		const value = information(at(i), at(j));
+		if (value !== void 0 && !Number.isFinite(value)) throw new RangeError(`choosePair: the information of ${at(i).id} and ${at(j).id} is ${value}, and it is a finite number or undefined.`);
+		return value;
+	};
+	const jitter = draw.fork("jitter");
+	let best;
+	const consider = (i, j, score) => {
+		if (score === void 0) return;
+		const option = {
+			i,
+			j,
+			fresh: !isRecent(i, j),
+			score,
+			tie: jitter.next()
+		};
+		if (best === void 0 || option.fresh && !best.fresh || option.fresh === best.fresh && (option.score > best.score || option.score === best.score && option.tie > best.tie)) best = option;
+	};
+	const weights = pool.map((item) => 1 / (1 + item.picks));
+	const firstDraw = draw.fork("first");
+	let first = -1;
+	const scores = /* @__PURE__ */ new Map();
+	while (first < 0 && weights.some((weight) => weight > 0)) {
+		const index = firstDraw.weighted(weights);
+		for (let j = 0; j < pool.length; j++) {
+			const score = j === index ? void 0 : informationOf(index, j);
+			if (score !== void 0) scores.set(j, score);
+		}
+		if (scores.size > 0) first = index;
+		else weights[index] = 0;
+	}
+	if (first < 0) return void 0;
+	const second = draw.fork("second");
+	const allowed = new Set(scores.keys());
+	for (const j of candidatesOf(first, allowed, pool.length, candidates, (n) => second.below(n))) consider(first, j, scores.get(j));
+	if (!best.fresh && pool.length <= 64) for (let i = 0; i < pool.length; i++) for (let j = i + 1; j < pool.length; j++) consider(i, j, informationOf(i, j));
+	const { i, j, score } = best;
+	const [left, right] = draw.fork("side").chance(.5) ? [at(j), at(i)] : [at(i), at(j)];
+	return {
+		a: left.id,
+		b: right.id,
+		information: score
+	};
+}
+export { BRADLEY_TERRY_DENSE_LIMIT, EMPTY_RUNNING, KENDALL_EXACT, PAIR_FULL_SEARCH, RATING_START_UNCERTAINTY, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, SIGN_FLIP_EXACT_LIMIT, SIGN_FLIP_EXACT_MAX, U_STATISTIC_TIGHT_MIN_SAMPLE, Z95, addToRunning, bestSmoothLaw, binomialInterval, binomialTest, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapStrata, bootstrapTwo, bradleyTerry, bradleyTerrySparse, brier, calibration, choosePair, cohenKappa, compareRatios, coverageMinSample, eloExpected, eloReplay, eloUpdate, fitRatings, fitResponse, glicko2Idle, glicko2Replay, glicko2Update, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, logLoss, mean, median, medianInterval, mergeRunning, modeCount, negativeBinomialInterval, noiseFloor, noiseVerdict, normalCdf, normalQuantile, optionFloor, pairInformation, pairProbabilities, pairedPermutation, parseResponseRecord, partialConjunction, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, ratingToStrength, ratingUncertainty, responseCells, ridgeSolve, runningMean, runningOf, runningSd, sampleTotalInterval, sd, selectRatingModel, signFlipTest, signTest, signTestPower, sliceResponse, smoothLawScores, sobolIndices, sorted, spearman, strengthToRating, summarize, surfaceResponse, tQuantile, twoSamplePermutation, uStatisticInterval, whenHolds, wilson, wilsonSampleSize };
 
 //# sourceMappingURL=index.js.map