skaters 0.11.0 → 0.11.4

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.11.4
+
+Docs: lead the README with the live in-browser race demo
+(<https://skaters.microprediction.org/demos/race.html>) — the JS port racing
+`arima`, `@bsull/augurs` (ETS and MSTL), and Prophet (Stan compiled to WASM) on
+real FRED series, scored on held-out log-likelihood. No code changes.
+
+## 0.11.3
+
+Fix: `Dist.logpdf` returned `-Infinity` for finite inputs when the scale had
+collapsed near a Dirac (e.g. on a near-constant stream), because `log(sum(w *
+pdf))` underflowed each `exp(-z**2/2)` to `0`. A Gaussian mixture is strictly
+positive everywhere, so this is now computed as a log-sum-exp over the
+per-component log densities and is always finite for finite `x`. Numerically
+identical to the old path wherever it did not underflow (parity vectors
+unchanged); only the former `-Infinity` cases now return the correct large
+finite value.
+
+## 0.11.2
+
+Fix: RLS covariance windup in the `ar` and `grouped_ar` transforms. Under
+low-excitation input the RLS `P` matrix inflated by `1/lam` each step and
+eventually overflowed to `Inf` (~74k steps), giving `NaN` coefficients and a
+non-finite forecast. `P` is now reset if it grows implausibly large or turns
+non-finite (keeping the coefficients); it never triggers on well-excited data, so
+results and Python↔JS parity are unchanged.
+
+## 0.11.1
+
+Fix: the CRPS leaf's exponentiated-gradient weight update could overflow `exp()`
+to `Inf` on some streams, normalizing to `NaN` weights and throwing in the `Dist`
+constructor. The step is now stabilized by subtracting the max exponent
+(mathematically invariant, so results and Python↔JS parity are unchanged), with a
+guard that keeps the current weights on any degenerate update.
+
 ## 0.11.0
 
 Initial npm release of the JavaScript port. Zero-dependency ES modules for Node

package/README.md

@@ -4,6 +4,15 @@
 [![npm downloads](https://img.shields.io/npm/dm/skaters)](https://www.npmjs.com/package/skaters)
 [![license: MIT](https://img.shields.io/npm/l/skaters)](https://github.com/microprediction/skaters/blob/main/LICENSE)
 
+### ▶ [Watch it race live in your browser](https://skaters.microprediction.org/demos/race.html)
+
+The actual JavaScript port racing `arima`, `@bsull/augurs` (ETS and MSTL), and
+Prophet (Stan compiled to WASM) on 150 real FRED series — every method scored on
+held-out log-likelihood, rolling one-step-ahead, no server. `laplace` keeps up
+with a moving average while the refit baselines grind. **[Start here →](https://skaters.microprediction.org/demos/race.html)**
+
+---
+
 Fast univariate **online distributional** time-series forecasting. Zero
 dependencies, runs in Node or the browser. This is the JavaScript port of the
 Python [`skaters`](https://pypi.org/project/skaters/) package, numerically

package/dist.mjs

@@ -8,6 +8,7 @@
 
 const SQRT2 = Math.SQRT2;
 const SQRT2PI = Math.sqrt(2.0 * Math.PI);
+const LOG_SQRT2PI = 0.5 * Math.log(2.0 * Math.PI);
 const LGAMMA_HALF = 0.5723649429247001; // ln(Gamma(1/2)) = ln(sqrt(pi))
 
 // --- erf via the regularized lower incomplete gamma P(1/2, x^2) ---
@@ -134,8 +135,28 @@ export class Dist {
   }
 
   logpdf(x) {
-    const p = this.pdf(x);
-    return p > 0 ? Math.log(p) : -Infinity;
+    // Log density accumulated in log-space (log-sum-exp). A Gaussian mixture is
+    // strictly positive everywhere, so for finite x this is always finite;
+    // log(sum(w * pdf)) would underflow to -Infinity once x sits many standard
+    // deviations from every component (e.g. after the scale collapses on a
+    // near-constant stream), because each exp(-z*z/2) rounds to 0.
+    let best = -Infinity;
+    const terms = [];
+    for (const [w, m, s] of this.components) {
+      if (w <= 0.0) continue;
+      if (s <= 0.0) {
+        if (x === m) return Infinity;
+        continue;
+      }
+      const z = (x - m) / s;
+      const t = Math.log(w) - 0.5 * z * z - Math.log(s) - LOG_SQRT2PI;
+      terms.push(t);
+      if (t > best) best = t;
+    }
+    if (best === -Infinity) return -Infinity;
+    let acc = 0.0;
+    for (const t of terms) acc += Math.exp(t - best);
+    return best + Math.log(acc);
   }
 
   cdf(x) {

package/leaf.mjs

@@ -114,10 +114,21 @@ export function crpsLeaf(k = 1, eta = 1.0, scaleAlpha = 0.01, scales = FINE) {
       g[c] = absNormal(-z, C[c]) - dot;
     }
     const gm = fsum(g) / K;
+    // Exponentiated-gradient step, stabilized by subtracting the max exponent so
+    // exp() cannot overflow to Inf (which would normalize to NaN weights and
+    // crash Dist). Subtracting a constant from every exponent leaves the
+    // normalized weights unchanged.
+    const e = new Array(K);
+    for (let c = 0; c < K; c++) e[c] = -eta * (g[c] - gm);
+    let emax = -Infinity;
+    for (let c = 0; c < K; c++) if (e[c] > emax) emax = e[c];
     const nw = new Array(K);
-    let Z = 0.0;
-    for (let c = 0; c < K; c++) nw[c] = w[c] * Math.exp(-eta * (g[c] - gm));
-    Z = fsum(nw);
+    for (let c = 0; c < K; c++) nw[c] = w[c] * Math.exp(e[c] - emax);
+    let Z = fsum(nw);
+    if (!(Z > 0.0) || !Number.isFinite(Z)) {
+      for (let c = 0; c < K; c++) nw[c] = w[c];  // degenerate update: keep weights
+      Z = fsum(nw);
+    }
     state.w = nw.map((x) => x / Z);
     const comps = C.map((c, i) => [state.w[i], 0.0, c * sig]);
     return [new Array(k).fill(new Dist(comps)), state];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skaters",
-  "version": "0.11.0",
+  "version": "0.11.4",
   "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",

package/transform.mjs

@@ -461,6 +461,18 @@ export function ar(order = 2, lam = 0.99, ridge = 1.0, decay = 0.0) {
             P[i * p + j] = (P[i * p + j] - K[i] * Px[j]) / lam;
           }
         }
+        // Guard against RLS covariance windup (see the Python note): under
+        // low-excitation input P inflates by 1/lam each step and overflows to
+        // Inf, giving nan coefficients. Reset the covariance (keeping phi) if it
+        // grows implausibly large or non-finite. No effect on well-excited data.
+        let bad = false, pmax = 0.0;
+        for (let m = 0; m < P.length; m++) {
+          const v = P[m];
+          if (!Number.isFinite(v)) { bad = true; break; }
+          const av = Math.abs(v);
+          if (av > pmax) pmax = av;
+        }
+        if (bad || pmax > 1e10) { const np = initP(); for (let m = 0; m < P.length; m++) P[m] = np[m]; }
       }
     } else {
       residual = y;
@@ -555,6 +567,16 @@ export function groupedAr(maxLag = 16, lam = 0.99, ridge = 1.0) {
             P[i * nGroups + j] = (P[i * nGroups + j] - K[i] * Px[j]) / lam;
           }
         }
+        // RLS covariance windup guard (see ar()): reset P if it inflates
+        // implausibly or turns non-finite; keeps theta. No effect on well-excited data.
+        let bad = false, pmax = 0.0;
+        for (let m = 0; m < P.length; m++) {
+          const v = P[m];
+          if (!Number.isFinite(v)) { bad = true; break; }
+          const av = Math.abs(v);
+          if (av > pmax) pmax = av;
+        }
+        if (bad || pmax > 1e10) { const np = eye(nGroups, ridge); for (let m = 0; m < P.length; m++) P[m] = np[m]; }
       }
     } else {
       residual = y;