@takk/bayesoutputgate 1.0.0

package/dist/calibration/index.js

@@ -0,0 +1,333 @@
+// src/errors.ts
+var BayesOutputGateError = class _BayesOutputGateError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BayesOutputGateError";
+    this.code = code;
+    Object.setPrototypeOf(this, _BayesOutputGateError.prototype);
+  }
+};
+function invariant(condition, code, message) {
+  if (!condition) {
+    throw new BayesOutputGateError(code, message);
+  }
+}
+
+// src/dimensions/index.ts
+function dependenceDiagnostic(history, options = {}) {
+  const threshold = options.threshold ?? 0.5;
+  invariant(
+    Number.isFinite(threshold) && threshold >= 0 && threshold <= 1,
+    "INVALID_CONFIG",
+    `threshold must be in [0, 1], got ${threshold}`
+  );
+  invariant(
+    history.length >= 2,
+    "INVALID_OBSERVATION",
+    "dependence diagnostic needs at least two score vectors"
+  );
+  const dimensionSet = /* @__PURE__ */ new Set();
+  for (const vector of history) {
+    for (const score of vector) {
+      dimensionSet.add(score.dimension);
+    }
+  }
+  const dimensions = [...dimensionSet].sort();
+  const rows = history.map((vector) => {
+    const map = /* @__PURE__ */ new Map();
+    for (const score of vector) {
+      map.set(score.dimension, score.value);
+    }
+    return map;
+  });
+  const pairs = [];
+  for (let i = 0; i < dimensions.length; i++) {
+    for (let j = i + 1; j < dimensions.length; j++) {
+      const a = dimensions[i];
+      const b = dimensions[j];
+      const xs = [];
+      const ys = [];
+      for (const row of rows) {
+        const x = row.get(a);
+        const y = row.get(b);
+        if (x !== void 0 && y !== void 0) {
+          xs.push(x);
+          ys.push(y);
+        }
+      }
+      if (xs.length >= 2) {
+        const correlation = pearson(xs, ys);
+        if (Number.isFinite(correlation)) {
+          pairs.push({ a, b, correlation, samples: xs.length });
+        }
+      }
+    }
+  }
+  pairs.sort((left, right) => Math.abs(right.correlation) - Math.abs(left.correlation));
+  const maxAbsCorrelation = pairs.length > 0 ? Math.abs(pairs[0].correlation) : 0;
+  const flagged = pairs.filter((pair) => Math.abs(pair.correlation) >= threshold);
+  return {
+    dimensions,
+    pairs,
+    flagged,
+    maxAbsCorrelation,
+    independenceAssumptionSafe: flagged.length === 0
+  };
+}
+function pearson(xs, ys) {
+  const n = xs.length;
+  let sumX = 0;
+  let sumY = 0;
+  for (let i = 0; i < n; i++) {
+    sumX += xs[i];
+    sumY += ys[i];
+  }
+  const meanX = sumX / n;
+  const meanY = sumY / n;
+  let covariance = 0;
+  let varianceX = 0;
+  let varianceY = 0;
+  for (let i = 0; i < n; i++) {
+    const dx = xs[i] - meanX;
+    const dy = ys[i] - meanY;
+    covariance += dx * dy;
+    varianceX += dx * dx;
+    varianceY += dy * dy;
+  }
+  if (varianceX === 0 || varianceY === 0) {
+    return 0;
+  }
+  return covariance / Math.sqrt(varianceX * varianceY);
+}
+
+// src/mathspecial.ts
+var LN_SQRT_2PI = 0.9189385332046728;
+var LANCZOS_G = 7;
+var LANCZOS_COEFFICIENTS = [
+  0.9999999999998099,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9984369578019572e-21,
+  15056327351493116e-23
+];
+function lgamma(x) {
+  if (!Number.isFinite(x) || x <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `lgamma requires a positive finite argument, got ${x}`
+    );
+  }
+  const z = x - 1;
+  let acc = LANCZOS_COEFFICIENTS[0];
+  for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+    acc += LANCZOS_COEFFICIENTS[i] / (z + i);
+  }
+  const t = z + LANCZOS_G + 0.5;
+  return LN_SQRT_2PI + (z + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+function regularizedIncompleteBeta(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `incomplete beta requires positive shapes, got a=${a}, b=${b}`
+    );
+  }
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const logFront = lgamma(a + b) - lgamma(a) - lgamma(b) + a * Math.log(x) + b * Math.log1p(-x);
+  const front = Math.exp(logFront);
+  if (x < (a + 1) / (a + b + 2)) {
+    return front * betaContinuedFraction(x, a, b) / a;
+  }
+  return 1 - front * betaContinuedFraction(1 - x, b, a) / b;
+}
+function betaCdf(x, a, b) {
+  return regularizedIncompleteBeta(x, a, b);
+}
+function betaContinuedFraction(x, a, b) {
+  const maxIterations = 200;
+  const epsilon = 3e-12;
+  const tiny = 1e-300;
+  const qab = a + b;
+  const qap = a + 1;
+  const qam = a - 1;
+  let c = 1;
+  let d = 1 - qab * x / qap;
+  if (Math.abs(d) < tiny) d = tiny;
+  d = 1 / d;
+  let h = d;
+  for (let m = 1; m <= maxIterations; m++) {
+    const m2 = 2 * m;
+    let aa = m * (b - m) * x / ((qam + m2) * (a + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < tiny) d = tiny;
+    c = 1 + aa / c;
+    if (Math.abs(c) < tiny) c = tiny;
+    d = 1 / d;
+    h *= d * c;
+    aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < tiny) d = tiny;
+    c = 1 + aa / c;
+    if (Math.abs(c) < tiny) c = tiny;
+    d = 1 / d;
+    const delta = d * c;
+    h *= delta;
+    if (Math.abs(delta - 1) < epsilon) {
+      break;
+    }
+  }
+  return h;
+}
+
+// src/calibration/index.ts
+function goodnessOfFit(samples, params, alpha = 0.05) {
+  invariant(
+    samples.length >= 5,
+    "INVALID_OBSERVATION",
+    "goodnessOfFit needs at least five samples"
+  );
+  invariant(params.a > 0 && params.b > 0, "INVALID_CONFIG", "Beta parameters must be positive");
+  const sorted = [...samples].sort((left, right) => left - right);
+  const n = sorted.length;
+  let ks = 0;
+  for (let i = 0; i < n; i++) {
+    const value = sorted[i];
+    invariant(
+      Number.isFinite(value) && value >= 0 && value <= 1,
+      "INVALID_SCORE",
+      `samples must be finite and in [0, 1], got ${value}`
+    );
+    const cdf = betaCdf(value, params.a, params.b);
+    const upper = (i + 1) / n - cdf;
+    const lower = cdf - i / n;
+    ks = Math.max(ks, upper, lower);
+  }
+  const coefficient = alpha <= 0.01 ? 1.628 : alpha <= 0.05 ? 1.358 : 1.224;
+  const criticalValue = coefficient / Math.sqrt(n);
+  return { ksStatistic: ks, criticalValue, adequate: ks <= criticalValue, samples: n };
+}
+function brierScore(predictions) {
+  invariant(
+    predictions.length > 0,
+    "INVALID_OBSERVATION",
+    "brierScore needs at least one prediction"
+  );
+  let sum = 0;
+  for (const prediction of predictions) {
+    validatePrediction(prediction);
+    sum += (prediction.probability - prediction.outcome) ** 2;
+  }
+  return sum / predictions.length;
+}
+function reliability(predictions, bins = 10) {
+  invariant(
+    Number.isInteger(bins) && bins >= 1,
+    "INVALID_CONFIG",
+    `bins must be a positive integer, got ${bins}`
+  );
+  invariant(
+    predictions.length > 0,
+    "INVALID_OBSERVATION",
+    "reliability needs at least one prediction"
+  );
+  const sums = new Array(bins).fill(0);
+  const hits = new Array(bins).fill(0);
+  const counts = new Array(bins).fill(0);
+  for (const prediction of predictions) {
+    validatePrediction(prediction);
+    const index = Math.min(bins - 1, Math.floor(prediction.probability * bins));
+    sums[index] = sums[index] + prediction.probability;
+    hits[index] = hits[index] + prediction.outcome;
+    counts[index] = counts[index] + 1;
+  }
+  const out = [];
+  for (let b = 0; b < bins; b++) {
+    const count = counts[b];
+    out.push({
+      lower: b / bins,
+      upper: (b + 1) / bins,
+      count,
+      meanPredicted: count > 0 ? sums[b] / count : 0,
+      empiricalRate: count > 0 ? hits[b] / count : 0
+    });
+  }
+  return out;
+}
+function expectedCalibrationError(predictions, bins = 10) {
+  const diagram = reliability(predictions, bins);
+  const total = predictions.length;
+  let ece = 0;
+  for (const bin of diagram) {
+    if (bin.count > 0) {
+      ece += bin.count / total * Math.abs(bin.empiricalRate - bin.meanPredicted);
+    }
+  }
+  return ece;
+}
+function scoresForDimension(history, dimension, label) {
+  const out = [];
+  for (const observation of history) {
+    if (observation.label !== label) {
+      continue;
+    }
+    for (const score of observation.scores) {
+      if (score.dimension === dimension) {
+        out.push(score.value);
+      }
+    }
+  }
+  return out;
+}
+function assessAssumptions(history, models, options = {}) {
+  const alpha = options.alpha ?? 0.05;
+  const minSamples = options.minSamples ?? 5;
+  const inadequateDimensions = [];
+  for (const model of models) {
+    const high = scoresForDimension(history, model.dimension, "high");
+    const low = scoresForDimension(history, model.dimension, "low");
+    const highBad = high.length >= minSamples && !goodnessOfFit(high, model.high, alpha).adequate;
+    const lowBad = low.length >= minSamples && !goodnessOfFit(low, model.low, alpha).adequate;
+    if (highBad || lowBad) {
+      inadequateDimensions.push(model.dimension);
+    }
+  }
+  const vectors = history.map((observation) => observation.scores);
+  let independenceAssumptionSafe = true;
+  const dependentPairs = [];
+  if (vectors.length >= 2) {
+    const diagnostic = dependenceDiagnostic(
+      vectors,
+      options.dependenceThreshold !== void 0 ? { threshold: options.dependenceThreshold } : {}
+    );
+    independenceAssumptionSafe = diagnostic.independenceAssumptionSafe;
+    for (const pair of diagnostic.flagged) {
+      dependentPairs.push(`${pair.a}~${pair.b}`);
+    }
+  }
+  return {
+    goodnessOfFitAdequate: inadequateDimensions.length === 0,
+    independenceAssumptionSafe,
+    inadequateDimensions,
+    dependentPairs
+  };
+}
+function validatePrediction(prediction) {
+  invariant(
+    Number.isFinite(prediction.probability) && prediction.probability >= 0 && prediction.probability <= 1,
+    "INVALID_SCORE",
+    `prediction probability must be in [0, 1], got ${prediction.probability}`
+  );
+  invariant(
+    prediction.outcome === 0 || prediction.outcome === 1,
+    "INVALID_OBSERVATION",
+    `prediction outcome must be 0 or 1, got ${prediction.outcome}`
+  );
+}
+
+export { assessAssumptions, brierScore, expectedCalibrationError, goodnessOfFit, reliability };