peeksafe 0.2.0 → 0.4.0

package/src/stats.ts

@@ -115,13 +115,30 @@ export function gammaP(a: number, x: number): number {
  * approximation is visible in a p-value and we compare p-values to thresholds.
  */
 export function erf(x: number): number {
+  requireNumber(x, "x", "erf");
   if (x === 0) return 0;
   const p = gammaP(0.5, x * x);
   return x > 0 ? p : -p;
 }
 
 /** Φ(x): standard normal CDF. */
-export const normalCdf = (x: number): number => 0.5 * (1 + erf(x / Math.SQRT2));
+export function normalCdf(x: number): number {
+  requireNumber(x, "x", "normalCdf");
+  return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+
+/** Refuses NaN only: erf and normalCdf answer the infinities as their limits. */
+function requireNumber(x: number, name: string, where: string): void {
+  if (Number.isNaN(x)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: ${name} must be a number, got NaN`,
+      {
+        detail: { [name]: x },
+      },
+    );
+  }
+}
 
 /** Φ⁻¹(p): Acklam's inverse normal CDF, refined by one Halley step. */
 export function normalQuantile(p: number): number {
@@ -330,10 +347,16 @@ export function betaPosterior(
   prior: { alpha: number; beta: number } = { alpha: 1, beta: 1 },
 ): BetaPosterior {
   requireCounts(successes, successes + failures, "betaPosterior");
-  if (!(prior.alpha > 0) || !(prior.beta > 0)) {
+  // An infinite shape passed `> 0` and came back as NaN moments.
+  if (
+    !(prior.alpha > 0) ||
+    !(prior.beta > 0) ||
+    !Number.isFinite(prior.alpha) ||
+    !Number.isFinite(prior.beta)
+  ) {
     throw new PeeksafeError(
       "PEEKSAFE_E_STAT_DOMAIN",
-      "betaPosterior: prior parameters must be positive",
+      "betaPosterior: prior parameters must be finite and positive",
       {
         detail: { prior },
       },
@@ -424,8 +447,27 @@ export function tQuantile(p: number, df: number): number {
   return Math.sqrt((df * (1 - x)) / x);
 }
 
+// A posterior built by hand reached betaQuantile or ibeta unchecked and was refused in their name.
+function requirePosteriorShape(post: BetaPosterior, where: string): void {
+  if (
+    !(post.alpha > 0) ||
+    !(post.beta > 0) ||
+    !Number.isFinite(post.alpha) ||
+    !Number.isFinite(post.beta)
+  ) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: posterior alpha and beta must be finite and positive`,
+      {
+        detail: { alpha: post.alpha, beta: post.beta },
+      },
+    );
+  }
+}
+
 /** Equal-tailed credible interval of a Beta posterior. */
 export function betaCredibleInterval(post: BetaPosterior, level = 0.95): Interval {
+  requirePosteriorShape(post, "betaCredibleInterval");
   // 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;
@@ -438,6 +480,7 @@ export function betaCredibleInterval(post: BetaPosterior, level = 0.95): Interva
 
 /** P(a < θ < b) under a Beta posterior. */
 export function betaMassBetween(post: BetaPosterior, a: number, b: number): number {
+  requirePosteriorShape(post, "betaMassBetween");
   requireProbability(a, "a", "betaMassBetween");
   requireProbability(b, "b", "betaMassBetween");
   if (a > b) {
@@ -729,9 +772,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
@@ -1071,6 +1113,8 @@ export function bernoulliEntropy(p: number): number {
 /** log of the Beta(a,b) density at p. */
 export function logBetaPdf(p: number, a: number, b: number): number {
   requireProbability(p, "p", "logBetaPdf");
+  requireConcentration(a, "a", "logBetaPdf");
+  requireConcentration(b, "b", "logBetaPdf");
   if (p <= 0 || p >= 1) {
     // density is 0 or ∞ at the boundary depending on the shape; the planner
     // only ever evaluates strictly inside, so clamp rather than return ±∞.
@@ -1146,6 +1190,9 @@ export function evidenceCeilingLogE(
   altConcentration = 8,
 ): number {
   requireProbability(pTrue, "pTrue", "evidenceCeilingLogE");
+  requireCounts(baselineSuccesses, baselineTrials, "evidenceCeilingLogE");
+  requireConcentration(altConcentration, "altConcentration", "evidenceCeilingLogE");
+  requireOpenProbability(mde, "mde", "evidenceCeilingLogE");
   const { nullPrior, altPrior } = twoSamplePriors(
     baselineSuccesses,
     baselineTrials,
@@ -1213,6 +1260,8 @@ export function evidenceCeilingAsymptotic(
 ): number {
   requireCounts(baselineSuccesses, baselineTrials, "evidenceCeilingAsymptotic");
   requireProbability(pTrue, "pTrue", "evidenceCeilingAsymptotic");
+  requireConcentration(altConcentration, "altConcentration", "evidenceCeilingAsymptotic");
+  requireOpenProbability(mde, "mde", "evidenceCeilingAsymptotic");
   if (baselineTrials === 0) {
     throw new PeeksafeError(
       "PEEKSAFE_E_STAT_DOMAIN",
@@ -1274,6 +1323,9 @@ export function expectedLogE(
       detail: { n },
     });
   }
+  requireCounts(baselineSuccesses, baselineTrials, "expectedLogE");
+  requireConcentration(altConcentration, "altConcentration", "expectedLogE");
+  requireOpenProbability(mde, "mde", "expectedLogE");
   const { nullPrior: n0, altPrior: a1 } = twoSamplePriors(
     baselineSuccesses,
     baselineTrials,
@@ -1307,6 +1359,9 @@ export function expectedLogEExact(
       { detail: { n } },
     );
   }
+  requireCounts(baselineSuccesses, baselineTrials, "expectedLogEExact");
+  requireConcentration(altConcentration, "altConcentration", "expectedLogEExact");
+  requireOpenProbability(mde, "mde", "expectedLogEExact");
   let acc = 0;
   for (let s = 0; s <= n; s++) {
     const logW =
@@ -1339,6 +1394,10 @@ export function samplesForEvidence(
 ): number {
   requireSearchCap(maxN, "maxN", "samplesForEvidence");
   requireLogThreshold(logThreshold, "samplesForEvidence");
+  requireProbability(pTrue, "pTrue", "samplesForEvidence");
+  requireCounts(baselineSuccesses, baselineTrials, "samplesForEvidence");
+  requireConcentration(altConcentration, "altConcentration", "samplesForEvidence");
+  requireOpenProbability(mde, "mde", "samplesForEvidence");
   const ceiling = evidenceCeilingLogE(
     pTrue,
     baselineSuccesses,
@@ -1407,6 +1466,8 @@ export function universalTwoSampleLogE(
 ): number {
   requireCounts(candidateSuccesses, candidateTrials, "universalTwoSampleLogE(candidate)");
   requireCounts(baselineSuccesses, baselineTrials, "universalTwoSampleLogE(baseline)");
+  requireConcentration(altConcentration, "altConcentration", "universalTwoSampleLogE");
+  requireOpenProbability(mde, "mde", "universalTwoSampleLogE");
   if (baselineTrials === 0) {
     throw new PeeksafeError(
       "PEEKSAFE_E_STAT_DOMAIN",
@@ -1587,6 +1648,9 @@ export function mcnemarSamplesForEvidence(
   requireConcentration(concentration, "concentration", "mcnemarSamplesForEvidence");
   requireSearchCap(maxPairs, "maxPairs", "mcnemarSamplesForEvidence");
   requireLogThreshold(logThreshold, "mcnemarSamplesForEvidence");
+  requireProbability(pBaseline, "pBaseline", "mcnemarSamplesForEvidence");
+  requireProbability(rho, "rho", "mcnemarSamplesForEvidence");
+  requireOpenProbability(mde, "mde", "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

@@ -449,7 +449,7 @@ export function shouldStopPaired(
 }
 
 // Mean of prod(1 - lambda (D - mde)) over fixed bets, D = +1 worse, -1 better; a supermartingale whenever E[D] >= mde.
-export function settleLogE(c: PairedCounts, mde: number): number {
+function settleLogE(c: PairedCounts, mde: number): number {
   const terms: number[] = [];
   for (let k = 1; k <= 9; k++) {
     const lambda = k / 10 / (1 - mde);