skaters 0.11.4 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ tracks the Python [`skaters`](https://pypi.org/project/skaters/) package and is
 kept numerically identical to it within `1e-6`, enforced by the parity checker on
 every release.
 
+## 0.12.0
+
+Better default forecaster. `laplace`'s terminal-leaf `scaleAlpha` (the residual-variance
+EWMA rate — how fast the predictive scale tracks changing volatility) now defaults to
+**0.03** instead of 0.01. On the continuous FRED universe this beats the old default on
+held-out **log-likelihood** (~+0.02 nats, ~79% of series) **and CRPS** (~80% of series), on
+both non-price and price series — validated out-of-sample (see
+`benchmarks/leaf_experiments/`). New optional `scaleAlpha` argument on `laplace`; pass
+`scaleAlpha: 0.01` to reproduce the previous default. Minor bump because default predictions
+change; Python/JS parity re-verified to 1e-6.
+
 ## 0.11.4
 
 Docs: lead the README with the live in-browser race demo

package/api.mjs

@@ -8,6 +8,7 @@ import { terminalLeafEnsemble } from "./terminal.mjs";
 import { bayesianEnsemble } from "./bayesian.mjs";
 import { sticky as project } from "./sticky.mjs";
 import { multiscale } from "./multiscale.mjs";
+import { parade } from "./parade.mjs";
 import {
   difference, fractionalDifference, standardize, emaTransform, ouTransform, drift,
   holtLinear, ar, theta, seasonalDifference, garch, powerTransform, yeoJohnson,
@@ -142,16 +143,16 @@ export function buildCandidates(k) {
 // Policies
 // ---------------------------------------------------------------------------
 
-function objectiveLeaf(objective) {
-  if (objective === "crps") return crpsLeaf;
-  if (objective === "likelihood") return scaleMixtureLeaf;
+function objectiveLeaf(objective, scaleAlpha) {
+  if (objective === "crps") return (k) => crpsLeaf(k, undefined, scaleAlpha);
+  if (objective === "likelihood") return (k) => scaleMixtureLeaf(k, undefined, scaleAlpha);
   throw new Error(`objective must be 'crps' or 'likelihood', got ${objective}`);
 }
 
-function laplaceSingleScale(k, objective, sticky) {
+function laplaceSingleScale(k, objective, sticky, scaleAlpha) {
   const [candidates, depths] = buildCandidates(k);
   let f = terminalLeafEnsemble(candidates, {
-    k, leafFn: objectiveLeaf(objective), learningRate: 0.8, complexityPenalty: 0.005, depths, maxComponents: 20,
+    k, leafFn: objectiveLeaf(objective, scaleAlpha), learningRate: 0.8, complexityPenalty: 0.005, depths, maxComponents: 20,
     forget: 0.99,
   });
   if (sticky) f = project(f, k);
@@ -161,8 +162,14 @@ function laplaceSingleScale(k, objective, sticky) {
 // Multi-scale by default at k > 1: one instance per decimation stride
 // (default {1, ceil(sqrt(k)), k}), horizons mix eligible scales by likelihood.
 // Pass scales = [1] for the single-scale (native fan-out) variant.
-export function laplace(k = 1, objective = "crps", sticky = true, scales = null) {
-  const f = multiscale((kk) => laplaceSingleScale(kk, objective, sticky), k, { scales });
+//
+// scaleAlpha is the terminal leaf's residual-variance EWMA rate (how fast the
+// predictive scale tracks volatility). Default 0.03 beats the older 0.01 on
+// held-out log-likelihood AND CRPS across the continuous FRED universe; pass
+// scaleAlpha = 0.01 to reproduce the earlier default.
+export function laplace(k = 1, objective = "crps", sticky = true, scales = null, scaleAlpha = 0.03) {
+  // parade adds state.pit / state.z calibration diagnostics (see parade.mjs)
+  const f = parade(multiscale((kk) => laplaceSingleScale(kk, objective, sticky, scaleAlpha), k, { scales }), k);
   f.skaterName = `laplace(k=${k})`;
   return f;
 }

package/index.mjs

@@ -22,6 +22,7 @@ export {
   buildCandidates, laplace,
 } from "./api.mjs";
 export { multiscale } from "./multiscale.mjs";
+export { parade } from "./parade.mjs";
 export { sticky } from "./sticky.mjs";
 export {
   build, name as specName, toJson, fromJson,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skaters",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "Fast univariate online distributional time-series forecasting: a zero-dependency JavaScript port of the Python skaters package, numerically identical to 1e-6.",
   "type": "module",
   "main": "./index.mjs",
@@ -35,7 +35,10 @@
     "garch",
     "zero-dependency",
     "browser",
-    "microprediction"
+    "microprediction",
+    "anomaly-detection",
+    "calibration",
+    "pit"
   ],
   "homepage": "https://skaters.microprediction.org",
   "repository": {

package/parade.mjs

@@ -0,0 +1,45 @@
+// The prediction parade — JS port of skaters/parade.py.
+//
+// Resolve each arriving observation against the predictions previously made
+// for it: state.pit[m-1] is the PIT of y under the m-step-ahead predictive
+// issued m steps ago (roughly Uniform(0,1) when calibrated); state.z[m-1] is
+// the same through the standard-normal quantile (roughly N(0,1)). Entries are
+// null until horizon m has matured. Pass-through for the forecasts themselves.
+// Named for the prediction parade of the timemachines package.
+
+import { Dist } from "./dist.mjs";
+
+const STD_NORMAL = Dist.gaussian(0.0, 1.0);
+// Clamp the PIT away from {0,1}: |z| is then bounded by ~7.03 and the
+// bisection in Dist.quantile stays inside its +-8 sigma bracket. No input can
+// produce an infinite z. Non-finite CDF values leave the entry null.
+const EPS = 1e-12;
+
+export function parade(base, k) {
+  return function skater(y, state) {
+    if (state === null || state === undefined) {
+      state = { base: null, pending: [], pit: new Array(k).fill(null), z: new Array(k).fill(null) };
+    }
+    const pend = state.pending;
+    const n = pend.length;
+    const pit = new Array(k).fill(null);
+    const z = new Array(k).fill(null);
+    for (let m = 1; m <= k; m++) {
+      if (m <= n) {
+        const d = pend[n - m][m - 1];      // issued m steps ago, horizon m
+        let u = d.cdf(y);
+        if (!Number.isFinite(u)) continue; // degenerate predictive or bad y
+        u = Math.min(Math.max(u, EPS), 1.0 - EPS);
+        pit[m - 1] = u;
+        z[m - 1] = STD_NORMAL.quantile(u);
+      }
+    }
+    const [dists, st] = base(y, state.base);
+    state.base = st;
+    pend.push(dists.slice());
+    if (pend.length > k) pend.shift();
+    state.pit = pit;
+    state.z = z;
+    return [dists, state];
+  };
+}