peeksafe 0.1.0 → 0.3.0

package/src/stats.ts

@@ -23,7 +23,9 @@
 import {
   PeeksafeError,
   requireCounts,
+  requireErrorRates,
   requireOpenProbability,
+  requirePairedCounts,
   requireProbability,
 } from "./errors.js";
 
@@ -36,6 +38,16 @@ const LANCZOS = [
 
 /** Lanczos approximation to log Γ(x), x > 0. ~15 significant digits. */
 export function logGamma(x: number): number {
+  // Below 0 the reflection answered finite values at the poles, 37.78 at x = -1, and Infinity answered NaN.
+  if (!(x > 0) || x === Infinity) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `logGamma: x must be finite and positive, got ${x}`,
+      {
+        detail: { x },
+      },
+    );
+  }
   if (x < 0.5) {
     // reflection: Γ(x)Γ(1-x) = π / sin(πx)
     return Math.log(Math.PI / Math.abs(Math.sin(Math.PI * x))) - logGamma(1 - x);
@@ -86,7 +98,14 @@ function gammaQContinued(a: number, x: number): number {
 
 /** Regularized lower incomplete gamma P(a,x), accurate to ~1e-15. */
 export function gammaP(a: number, x: number): number {
+  // A shape at or below 0 answered a negative probability, and x = Infinity fed Infinity - Infinity to exp.
+  if (!(a > 0) || !Number.isFinite(a) || Number.isNaN(x)) {
+    throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", "gammaP: need finite a > 0 and a number x", {
+      detail: { a, x },
+    });
+  }
   if (x <= 0) return 0;
+  if (x === Infinity) return 1;
   return x < a + 1 ? gammaPSeries(a, x) : 1 - gammaQContinued(a, x);
 }
 
@@ -106,6 +125,16 @@ export const normalCdf = (x: number): number => 0.5 * (1 + erf(x / Math.SQRT2));
 
 /** Φ⁻¹(p): Acklam's inverse normal CDF, refined by one Halley step. */
 export function normalQuantile(p: number): number {
+  // Every branch below compares false for NaN, so it fell through to the tail formula and came back NaN.
+  if (Number.isNaN(p)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "normalQuantile: p must be a number, got NaN",
+      {
+        detail: { p },
+      },
+    );
+  }
   if (p <= 0) return -Infinity;
   if (p >= 1) return Infinity;
   const a = [
@@ -244,6 +273,20 @@ export interface Interval {
   observations?: number;
 }
 
+// A negative z swapped the bounds and a non-finite one made them NaN; checked before the empty-arm returns.
+function requireZ(z: number, where: string): void {
+  if (!Number.isFinite(z) || z < 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: z must be finite and ≥ 0, got ${z}`,
+      {
+        detail: { z, where },
+        hint: "a standard normal quantile, such as 1.96 for a 95% interval",
+      },
+    );
+  }
+}
+
 /**
  * Wilson score interval for a binomial proportion.
  * Correct at the boundaries (0/n and n/n) where Wald is degenerate, which is
@@ -251,6 +294,7 @@ export interface Interval {
  */
 export function wilsonInterval(successes: number, n: number, z = 1.959963984540054): Interval {
   requireCounts(successes, n, "wilsonInterval");
+  requireZ(z, "wilsonInterval");
   // No data is not "p = 0.5". The interval is the whole line and the point
   // estimate is NaN-free only because callers must check `n`, which is why
   // `n` is echoed back in `observations`.
@@ -321,6 +365,12 @@ export function betaQuantile(alpha: number, beta: number, q: number): number {
       },
     );
   }
+  // The clamps below are kept, but a NaN fails every comparison in the bisection and came back near 0.
+  if (Number.isNaN(q)) {
+    throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", "betaQuantile: q must be a number, got NaN", {
+      detail: { alpha, beta, q },
+    });
+  }
   if (q <= 0) return 0;
   if (q >= 1) return 1;
   let lo = 0,
@@ -376,6 +426,8 @@ export function tQuantile(p: number, df: number): number {
 
 /** Equal-tailed credible interval of a Beta posterior. */
 export function betaCredibleInterval(post: BetaPosterior, level = 0.95): Interval {
+  // betaQuantile clamps q to [0, 1], so a level of 95 or -1 came back as [0, 1] or [1, 0].
+  requireOpenProbability(level, "level", "betaCredibleInterval");
   const tail = (1 - level) / 2;
   return {
     low: betaQuantile(post.alpha, post.beta, tail),
@@ -416,6 +468,7 @@ export function diffInterval(
 ): Interval {
   requireCounts(s1, n1, "diffInterval(arm 1)");
   requireCounts(s2, n2, "diffInterval(arm 2)");
+  requireZ(z, "diffInterval");
   // With an empty arm there is no difference to estimate. Saying so beats
   // reporting `p2 − 0` as if the missing arm had scored zero.
   if (n1 === 0 || n2 === 0) return { low: -1, high: 1, point: 0, observations: 0 };
@@ -551,8 +604,9 @@ export function sprtDecision(opts: SprtOpts): SprtResult {
   // against a wall that is not a number. An alpha of 0 puts `upper` at
   // Infinity, which no evidence ever crosses. Open at both ends: an error rate
   // of 0 is a test that never decides and one of 1 is a test that always does.
-  requireOpenProbability(alpha, "alpha", "sprtDecision");
-  requireOpenProbability(beta, "beta", "sprtDecision");
+  // At `alpha + beta >= 1` the walls meet or cross, so a test at 0 runs and a
+  // log likelihood ratio of 0 already sat on the H1 wall and answered ACCEPT_H1.
+  requireErrorRates(alpha, beta, "sprtDecision");
   const e = 1e-12;
   const cl = (x: number) => Math.min(1 - e, Math.max(e, x));
   const q0 = cl(p0),
@@ -630,8 +684,9 @@ export function sprtExpectedN(p: number, p0: number, p1: number, alpha = 0.05, b
   // and quote `maxTrials` when that fails, which both answers do, so a plan
   // built on an out-of-range error rate priced every case at the per-case cap
   // and reported it as a budget, with nothing to say it was not a real answer.
-  requireOpenProbability(alpha, "alpha", "sprtExpectedN");
-  requireOpenProbability(beta, "beta", "sprtExpectedN");
+  // At `alpha + beta >= 1` the test decides before its first run, and this
+  // answered 0 or a small positive number instead of saying so.
+  requireErrorRates(alpha, beta, "sprtExpectedN");
   const A = Math.log((1 - beta) / alpha);
   const B = Math.log(beta / (1 - alpha));
   const logR1 = Math.log(p1 / p0);
@@ -641,16 +696,6 @@ export function sprtExpectedN(p: number, p0: number, p1: number, alpha = 0.05, b
   // p0 === p1 leaves every trial uninformative, so the drift and the curvature
   // are both 0 and no number of runs ends the test.
   if (second === 0) return Infinity;
-  // `A === B` is `alpha + beta === 1`: both walls sit at a log likelihood ratio
-  // of 0, which is where the test starts, so it decides before it has seen
-  // anything and the expected sample number is 0. The general form is
-  // `(L1·(A − B) + B) / drift`, which is 0 whatever `L1` is, but it computes
-  // `L1` as `(1 − B^h) / (A^h − B^h)`, a genuine 0/0 here, and so returned NaN
-  // for in-domain error rates: (0.5, 0.5) and (0.25, 0.75) both landed on it.
-  // The neighbouring configurations already converge to 0 from both sides.
-  // Only the pairs where both logs round to exactly 0 were affected, which is
-  // why this survived the error-rate guards above.
-  if (A === B) return 0;
   // The ASN is 0/0 where the tilt vanishes, and that limit is the one place
   // Wald's formula needs a different expression. What decides whether the
   // quotient is really 0/0 is the *tilt*, not the drift: near the zero
@@ -684,9 +729,8 @@ export function sprtExpectedN(p: number, p0: number, p1: number, alpha = 0.05, b
  * outside the two hypotheses, so the two powers are evaluated relative to
  * whichever of them is largest. Written as plain `exp`, a tilt of −662, which is
  * p = 0.0025 against p₀ = 0.999 and p₁ = 0.99, overflows `B^h` to Infinity and
- * the ratio comes back NaN; `expectedSequentialSamples` and
- * `typicalObservationsPerCase` both test the result for `> 0`, so a NaN there
- * silently prices the case at `maxTrials`.
+ * the ratio comes back NaN, which a caller testing the result for `> 0` reads
+ * as no estimate at all.
  */
 function sprtAcceptH1(h: number, A: number, B: number, drift: number): number {
   // No tilt exists at p = 0 or p = 1: one outcome is impossible, so the drift
@@ -791,6 +835,41 @@ function requireConcentration(k: number, name: string, where: string): void {
   }
 }
 
+/**
+ * The most runs a sample-size search may try. Below 1, or NaN, the doubling
+ * loop never ran and the search answered Infinity, "no number of runs will
+ * do", for a design that needs a few hundred.
+ */
+function requireSearchCap(cap: number, name: string, where: string): void {
+  if (!(cap >= 1) || !Number.isFinite(cap)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: ${name} must be finite and at least 1, got ${cap}`,
+      {
+        detail: { [name]: cap, where },
+      },
+    );
+  }
+}
+
+/**
+ * The log e-value bar a sample-size search sizes a study to. A NaN bar loses
+ * every comparison the searches make, so one answered a single pair and the
+ * other Infinity, "no number of runs will do", for the same mistake.
+ */
+function requireLogThreshold(logThreshold: number, where: string): void {
+  if (!Number.isFinite(logThreshold)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: logThreshold must be finite, got ${logThreshold}`,
+      {
+        detail: { logThreshold },
+        hint: "this is a log e-value bar, such as Math.log(ebhSoloThreshold(m, fdr))",
+      },
+    );
+  }
+}
+
 // Below 1 a shape piles alternative mass onto 0 or 1, which pushed type I error past alpha for thin baselines.
 const ALT_SHAPE_FLOOR = 1;
 
@@ -907,8 +986,25 @@ export function ebhCorrect(evalues: number[], q = 0.05): EbhResult {
   return { rejected, discoveries: kStar, threshold: kStar > 0 ? m / (q * kStar) : m / q };
 }
 
-/** The e-value a case must reach to be certain of rejection whatever the others do. */
-export const ebhSoloThreshold = (m: number, q = 0.05): number => m / q;
+/**
+ * The e-value a case must reach to be certain of rejection whatever the others do.
+ *
+ * `q` is checked as `ebhCorrect` checks it, so a level of 0 answers Infinity.
+ */
+export function ebhSoloThreshold(m: number, q = 0.05): number {
+  if (!Number.isInteger(m) || m < 1) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `ebhSoloThreshold: m must be a positive integer, got ${m}`,
+      {
+        detail: { m },
+        hint: "m is the number of cases in the e-BH family",
+      },
+    );
+  }
+  requireProbability(q, "q", "ebhSoloThreshold");
+  return m / q;
+}
 
 /* ──────────────────────────────── planning ──────────────────────────── */
 
@@ -937,6 +1033,16 @@ export function sampleSizeTwoProportion(
   // naive design costs.
   requireOpenProbability(alpha, "alpha", "sampleSizeTwoProportion");
   requireOpenProbability(beta, "beta", "sampleSizeTwoProportion");
+  // Both comparisons below are false for NaN, so it fell through to the formula and came back NaN.
+  if (Number.isNaN(delta)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "sampleSizeTwoProportion: delta must be a number, got NaN",
+      {
+        detail: { p0, delta },
+      },
+    );
+  }
   if (delta <= 0 || delta >= p0) return Infinity;
   const p1 = p0 - delta;
   const pbar = (p0 + p1) / 2;
@@ -1230,6 +1336,8 @@ export function samplesForEvidence(
   maxN = 100_000,
   altConcentration = 8,
 ): number {
+  requireSearchCap(maxN, "maxN", "samplesForEvidence");
+  requireLogThreshold(logThreshold, "samplesForEvidence");
   const ceiling = evidenceCeilingLogE(
     pTrue,
     baselineSuccesses,
@@ -1373,7 +1481,10 @@ export interface PairedCounts {
   bothFail: number;
 }
 
-export const discordant = (p: PairedCounts): number => p.worse + p.better;
+export function discordant(p: PairedCounts): number {
+  requirePairedCounts(p, "discordant");
+  return p.worse + p.better;
+}
 
 /**
  * Phi coefficient of the 2×2 pair table, how well the pairing actually
@@ -1383,23 +1494,8 @@ export const discordant = (p: PairedCounts): number => p.worse + p.better;
  * not assumed.
  */
 export function pairPhi(p: PairedCounts): number {
+  requirePairedCounts(p, "pairPhi");
   const { bothPass: a, worse: b, better: cc, bothFail: d } = p;
-  for (const [name, v] of [
-    ["bothPass", a],
-    ["worse", b],
-    ["better", cc],
-    ["bothFail", d],
-  ] as const) {
-    if (!Number.isInteger(v) || v < 0) {
-      throw new PeeksafeError(
-        "PEEKSAFE_E_STAT_DOMAIN",
-        `pairPhi: ${name} must be a non-negative integer, got ${v}`,
-        {
-          detail: { counts: p },
-        },
-      );
-    }
-  }
   const n = a + b + cc + d;
   if (n === 0) return 0;
   const den = Math.sqrt((a + b) * (cc + d) * (a + cc) * (b + d));
@@ -1488,21 +1584,8 @@ export function mcnemarSamplesForEvidence(
   concentration = 6,
 ): number {
   requireConcentration(concentration, "concentration", "mcnemarSamplesForEvidence");
-  // Every comparison below is a `<` against `logThreshold`, and a NaN loses all
-  // of them: the doubling loop exited on its first test, the Infinity guard did
-  // not fire, and the bisection returned its own starting point. The answer
-  // came back as one pair, where the same design at a real 15pt effect needs
-  // 172. `samplesForEvidence` writes its guard negated and so refuses instead.
-  if (!Number.isFinite(logThreshold)) {
-    throw new PeeksafeError(
-      "PEEKSAFE_E_STAT_DOMAIN",
-      `mcnemarSamplesForEvidence: logThreshold must be finite, got ${logThreshold}`,
-      {
-        detail: { logThreshold },
-        hint: "this is a log e-value bar, such as Math.log(ebhSoloThreshold(m, fdr))",
-      },
-    );
-  }
+  requireSearchCap(maxPairs, "maxPairs", "mcnemarSamplesForEvidence");
+  requireLogThreshold(logThreshold, "mcnemarSamplesForEvidence");
   const { rate, theta } = pairedDiscordance(pBaseline, mde, rho);
   if (rate <= 0 || theta <= 0.5) return Infinity;
   const a1 = Math.max(0.35, concentration * theta);

package/src/stop.ts

@@ -60,7 +60,7 @@ import {
   requireEvidence,
   toEvalue,
 } from "./evidence.js";
-import { cannotDropBy, DEFAULT_GATE_OPTIONS } from "./gate.js";
+import { cannotDropBy, DEFAULT_GATE_OPTIONS, definedOptions } from "./gate.js";
 import {
   discordant,
   ebhSoloThreshold,
@@ -160,7 +160,19 @@ const zFor = (confidence: number): number => {
       },
     );
   }
-  return normalQuantile(1 - (1 - confidence) / 2);
+  const z = normalQuantile(1 - (1 - confidence) / 2);
+  // At the largest double below 1 the upper tail rounds to 1, and an infinite z reached the ceiling as NaN.
+  if (!Number.isFinite(z)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_CONFIG",
+      `shouldStop: futilityConfidence ${confidence} is too close to 1 for a finite interval`,
+      {
+        detail: { futilityConfidence: confidence },
+        hint: "a two-sided confidence level such as 0.95; higher makes futility fire later",
+      },
+    );
+  }
+  return z;
 };
 
 /**
@@ -180,7 +192,7 @@ export function shouldStop(
   baseline: BaselineStat,
   options: StopOptions,
 ): StopDecision {
-  const opts = { ...DEFAULT_STOP_OPTIONS, ...options };
+  const opts = { ...DEFAULT_STOP_OPTIONS, ...definedOptions(options) };
   requireCounts(observed.successes, observed.trials, "shouldStop");
   requireCounts(baseline.successes, baseline.trials, "shouldStop.baseline");
   requireOpenProbability(opts.mde, "mde", "shouldStop");
@@ -363,7 +375,7 @@ export function shouldStopPaired(
   counts: PairedCounts,
   options: PairedStopOptions,
 ): PairedStopDecision {
-  const opts = { ...DEFAULT_STOP_OPTIONS, ...options };
+  const opts = { ...DEFAULT_STOP_OPTIONS, ...definedOptions(options) };
   requirePairedCounts(counts, "shouldStopPaired");
   requireOpenProbability(opts.mde, "mde", "shouldStopPaired");
   requireOpenProbability(opts.fdr, "fdr", "shouldStopPaired");