skaters 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to the `skaters` npm package (the JavaScript port). The port
+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.0
+
+Initial npm release of the JavaScript port. Zero-dependency ES modules for Node
+and the browser. Exports `laplace` and `buildCandidates`, the `Dist` object,
+transforms (`difference`, `standardize`, `garch`, `ar`, `holtLinear`,
+`powerTransform`, …), ensembles, leaves (`scaleMixtureLeaf`, `crpsLeaf`,
+`garchLeaf`), `multiscale`, `sticky`, periodicity and covariance helpers, and the
+spec (de)serialisers. Version chosen to align with the Python package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Cotton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# skaters
+
+[![npm version](https://img.shields.io/npm/v/skaters)](https://www.npmjs.com/package/skaters)
+[![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)
+
+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
+identical to it within `1e-6` (enforced on every release by a parity checker
+against the Python reference).
+
+Every prediction is a full predictive **distribution** (a `Dist`), so it can be
+scored on log-likelihood — not just a point or an interval.
+
+## Install
+
+```
+npm install skaters
+```
+
+## Quickstart
+
+```js
+import { laplace } from "skaters";
+
+const f = laplace(1);          // online, O(1) per step, the general-purpose default
+let state = null;
+for (const y of stream) {
+  let dists;
+  [dists, state] = f(y, state);
+  const d = dists[0];
+  d.mean;             // point forecast
+  d.std;              // uncertainty
+  d.quantile(0.975);  // 97.5th percentile
+  d.logpdf(y);        // a real density — scorable on log-likelihood
+  d.crps(y);          // ...and on CRPS
+}
+```
+
+In the browser, import the hosted module directly — no build step:
+
+```html
+<script type="module">
+  import { laplace } from "https://skaters.microprediction.org/js/skaters/index.mjs";
+</script>
+```
+
+## What's exported
+
+`laplace` and `buildCandidates`; the `Dist` object; transforms (`difference`,
+`standardize`, `garch`, `ar`, `holtLinear`, `powerTransform`, …); ensembles
+(`precisionWeightedEnsemble`, `bayesianEnsemble`, `terminalLeafEnsemble`); leaves
+(`scaleMixtureLeaf`, `crpsLeaf`, `garchLeaf`); `multiscale`, `sticky`, periodicity
+and covariance helpers; and spec (de)serialisers. See `index.mjs` for the full
+surface.
+
+## Notes
+
+- `laplace` is the general-purpose default; its signature is
+  `laplace(k = 1, objective = "crps", sticky = true, scales = null)`. On
+  price/return series with volatility clustering there is no free lunch — a
+  dedicated GARCH-t model is the right tool there.
+- The port is a faithful mirror of the Python package; the two agree to `1e-6`.
+
+## Links
+
+- Docs & benchmarks: <https://skaters.microprediction.org>
+- Paper: *Transforms All the Way Down — Automatic Online Distributional Forecasting by Conjugation*
+- Python package: <https://pypi.org/project/skaters/>
+- Source: <https://github.com/microprediction/skaters>
+
+MIT © Peter Cotton

package/api.mjs

@@ -0,0 +1,168 @@
+// User-facing API — JS port of skaters/api.py (named search policies).
+//
+// One forecaster: laplace (general). Volatility/mean-reversion are composable transforms.
+
+import { leaf, scaleMixtureLeaf, crpsLeaf } from "./leaf.mjs";
+import { conjugate } from "./conjugate.mjs";
+import { terminalLeafEnsemble } from "./terminal.mjs";
+import { bayesianEnsemble } from "./bayesian.mjs";
+import { sticky as project } from "./sticky.mjs";
+import { multiscale } from "./multiscale.mjs";
+import {
+  difference, fractionalDifference, standardize, emaTransform, ouTransform, drift,
+  holtLinear, ar, theta, seasonalDifference, garch, powerTransform, yeoJohnson,
+} from "./transform.mjs";
+
+// ---------------------------------------------------------------------------
+// Shared candidate population
+// ---------------------------------------------------------------------------
+
+export function buildCandidates(k) {
+  const candidates = [];
+  const depths = [];
+  const groups = {};
+  const families = [];                 // human family label per candidate (for introspection)
+  const push = (c, d, fam) => {
+    candidates.push(c);
+    depths.push(d);
+    families.push(fam);
+    return candidates.length - 1;
+  };
+
+  // Depth 0: baseline noise
+  push(leaf(k), 0, "baseline");
+
+  // Depth 1: single EMA at various speeds
+  for (const alpha of [0.01, 0.05, 0.1, 0.3]) push(conjugate(leaf(k), emaTransform(alpha), k), 1, "EMA");
+
+  // Depth 1: differencing (pure random walk)
+  groups.diff = [];
+  groups.diff.push(push(conjugate(leaf(k), difference(), k), 1, "random walk"));
+
+  // Depth 1: drift (random walk with adaptive drift)
+  groups.drift = [];
+  for (const [a, s] of [[0.05, 0.01], [0.01, 0.002], [0.002, 0.001], [0.0005, 0.0002]]) {
+    groups.drift.push(push(conjugate(leaf(k), drift(a, s), k), 1, "drift"));
+  }
+
+  // Depth 1: Theta
+  for (const a of [0.05, 0.1, 0.3]) push(conjugate(leaf(k), theta(a), k), 1, "Theta");
+
+  // Depth 1: AR
+  push(conjugate(leaf(k), ar(1), k), 1, "AR");
+  push(conjugate(leaf(k), ar(2, 0.99, 1.0, 1), k), 1, "AR");
+
+  // Depth 1: Holt linear
+  groups.holt = [];
+  for (const [a, b] of [[0.1, 0.02], [0.1, 0.05], [0.3, 0.1]]) {
+    groups.holt.push(push(conjugate(leaf(k), holtLinear(a, b), k), 1, "Holt trend"));
+  }
+
+  // Depth 1: Seasonal differencing
+  for (const period of [7, 12, 24]) push(conjugate(leaf(k), seasonalDifference(period), k), 1, "seasonal");
+
+  // Depth 2: Seasonal differencing + EMA
+  for (const period of [7, 12, 24]) {
+    for (const alpha of [0.05, 0.1]) {
+      push(conjugate(conjugate(leaf(k), emaTransform(alpha), k), seasonalDifference(period), k), 2, "seasonal → EMA");
+    }
+  }
+
+  // Depth 2: differencing + EMA
+  for (const alpha of [0.05, 0.1, 0.3]) {
+    groups.diff.push(push(conjugate(conjugate(leaf(k), emaTransform(alpha), k), difference(), k), 2, "random walk → EMA"));
+  }
+
+  // Depth 2: standardize + EMA
+  for (const alpha of [0.05, 0.1]) {
+    push(conjugate(conjugate(leaf(k), emaTransform(alpha), k), standardize(), k), 2, "standardize → EMA");
+  }
+
+  // Depth 2: fractional diff + EMA
+  groups.frac = [];
+  for (const d of [0.2, 0.4]) {
+    groups.frac.push(push(conjugate(conjugate(leaf(k), emaTransform(0.1), k), fractionalDifference(d, 30), k), 2, "frac-diff → EMA"));
+  }
+
+  // Depth 2: drift + EMA
+  for (const [aDrift, sDrift] of [[0.002, 0.001], [0.0005, 0.0002]]) {
+    for (const aEma of [0.05, 0.1]) {
+      groups.drift.push(push(conjugate(conjugate(leaf(k), emaTransform(aEma), k), drift(aDrift, sDrift), k), 2, "drift → EMA"));
+    }
+  }
+
+  // Depth 2: drift + Holt linear
+  {
+    const idx = push(conjugate(conjugate(leaf(k), holtLinear(0.1, 0.05), k), drift(0.001, 0.0005), k), 2, "drift → Holt");
+    groups.drift.push(idx);
+    groups.holt.push(idx);
+  }
+
+  // Depth 2: GARCH + EMA
+  push(conjugate(conjugate(leaf(k), emaTransform(0.1), k), garch(), k), 2, "GARCH vol → EMA");
+
+  // Depth 2: power transform + EMA
+  push(conjugate(conjugate(leaf(k), emaTransform(0.1), k), powerTransform(0.5), k), 2, "power → EMA");
+
+  // Depth 2: thinking fast and slow (fast tracker outside, slow scale inside)
+  const fastTrackers = () => [
+    emaTransform(0.3), emaTransform(0.5), holtLinear(0.4, 0.2), ar(1), drift(0.05, 0.01), difference(),
+  ];
+  groups.fast_slow = [];
+  for (const scaleAlpha of [0.02, 0.05]) {
+    for (const tracker of fastTrackers()) {
+      groups.fast_slow.push(push(conjugate(conjugate(leaf(k), standardize(scaleAlpha), k), tracker, k), 2, "fast/slow"));
+    }
+  }
+
+  // Coordinate prior (Yeo-Johnson): learn the coordinate the series is simple in.
+  groups.coordinate = [];
+  for (const L of [0.0, 0.5]) {
+    for (const innerTx of [difference(), emaTransform(0.1)]) {
+      groups.coordinate.push(push(conjugate(conjugate(leaf(k), innerTx, k), yeoJohnson(L), k), 2, "coordinate (Yeo-Johnson)"));
+    }
+  }
+
+  // Mean-reversion prior (Ornstein-Uhlenbeck), MULTI-STEP ONLY: redundant with
+  // the ema/random-walk mix at one step, so gated on k > 1 (see api.py).
+  groups.mean_revert = [];
+  if (k > 1) {
+    for (const L of [0.0, 0.5]) {
+      for (const kappa of [0.03, 0.1, 0.3]) {
+        groups.mean_revert.push(push(
+          conjugate(conjugate(leaf(k), ouTransform(kappa, 0.02), k), yeoJohnson(L), k), 2, "mean reversion (OU)"));
+      }
+    }
+  }
+
+  return [candidates, depths, groups, families];
+}
+
+// ---------------------------------------------------------------------------
+// Policies
+// ---------------------------------------------------------------------------
+
+function objectiveLeaf(objective) {
+  if (objective === "crps") return crpsLeaf;
+  if (objective === "likelihood") return scaleMixtureLeaf;
+  throw new Error(`objective must be 'crps' or 'likelihood', got ${objective}`);
+}
+
+function laplaceSingleScale(k, objective, sticky) {
+  const [candidates, depths] = buildCandidates(k);
+  let f = terminalLeafEnsemble(candidates, {
+    k, leafFn: objectiveLeaf(objective), learningRate: 0.8, complexityPenalty: 0.005, depths, maxComponents: 20,
+    forget: 0.99,
+  });
+  if (sticky) f = project(f, k);
+  return f;
+}
+
+// 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 });
+  f.skaterName = `laplace(k=${k})`;
+  return f;
+}

package/bayesian.mjs

@@ -0,0 +1,84 @@
+// Bayesian model-averaging ensemble — JS port of skaters/bayesian.py.
+//
+// Weights models by cumulative shrunk log-likelihood minus a per-depth
+// complexity penalty, combining predictions via Dist.combine with softmax
+// weights (XGBoost-inspired regularization).
+
+import { Dist } from "./dist.mjs";
+
+export function bayesianEnsemble(
+  skaters,
+  {
+    k = 1,
+    learningRate = 0.5,
+    complexityPenalty = 0.0,
+    depths = null,
+    priorLogWeights = null,
+    maxComponents = 20,
+  } = {}
+) {
+  const n = skaters.length;
+  if (n <= 0) throw new Error("ensemble needs at least one skater");
+  if (!(learningRate > 0 && learningRate <= 1)) throw new Error("learningRate in (0,1]");
+  if (complexityPenalty < 0) throw new Error("complexityPenalty >= 0");
+
+  const d = depths === null ? new Array(n).fill(0) : depths;
+  const prior = priorLogWeights === null ? new Array(n).fill(0.0) : priorLogWeights;
+
+  function _skater(y, state) {
+    if (state === null || state === undefined) {
+      state = {
+        sub: new Array(n).fill(null),
+        queues: Array.from({ length: n }, () => Array.from({ length: k }, () => [])),
+        log_w: Array.from({ length: n }, (_, i) => new Array(k).fill(prior[i])),
+        n_obs: 0,
+      };
+    }
+    state.n_obs += 1;
+
+    const allDists = [];
+    for (let i = 0; i < n; i++) {
+      const [distsI, sub] = skaters[i](y, state.sub[i]);
+      state.sub[i] = sub;
+      allDists.push(distsI);
+    }
+
+    // Resolve pending predictions: score each model's past Dist against y.
+    for (let i = 0; i < n; i++) {
+      for (let h = 0; h < k; h++) {
+        const q = state.queues[i][h];
+        if (q.length) {
+          const pastDist = q.shift();
+          let lp = pastDist.logpdf(y);
+          lp = Math.max(lp, -20.0); // bounded loss (mixability)
+          state.log_w[i][h] += learningRate * lp - complexityPenalty * d[i];
+        }
+      }
+    }
+
+    // Enqueue current predictions for future scoring.
+    for (let i = 0; i < n; i++) {
+      for (let h = 0; h < k; h++) state.queues[i][h].push(allDists[i][h]);
+    }
+
+    // Softmax weights per horizon, then combine.
+    const combined = [];
+    for (let h = 0; h < k; h++) {
+      const logWs = [];
+      for (let i = 0; i < n; i++) logWs.push(state.log_w[i][h]);
+      const maxLw = Math.max(...logWs);
+      let weights;
+      if (Number.isFinite(maxLw)) weights = logWs.map((lw) => Math.exp(lw - maxLw));
+      else weights = new Array(n).fill(1.0);
+
+      const horizonDists = [];
+      for (let i = 0; i < n; i++) horizonDists.push(allDists[i][h]);
+      let dist = Dist.combine(horizonDists, weights);
+      if (dist.length > maxComponents) dist = dist.prune(maxComponents);
+      combined.push(dist);
+    }
+    return [combined, state];
+  }
+  _skater.skaterName = `bayesian_ensemble(n=${n}, k=${k}, eta=${learningRate})`;
+  return _skater;
+}

package/conjugate.mjs

@@ -0,0 +1,23 @@
+// Conjugation — JS port of skaters/conjugate.py.
+//
+// Given an invertible transform T = {forward, inverseK} and a skater f,
+// produce a new skater that transforms each observation, predicts in the
+// transformed space, and inverts the predictions back.
+
+export function conjugate(skater, transform, k = 1) {
+  const { forward, inverseK } = transform;
+
+  function _conjugated(y, state) {
+    if (state === null || state === undefined) {
+      state = { tState: null, sState: null };
+    }
+    const [yPrime, tState] = forward(y, state.tState);
+    state.tState = tState;
+    const [distsPrime, sState] = skater(yPrime, state.sState);
+    state.sState = sState;
+    const dists = inverseK(distsPrime, state.tState);
+    return [dists, state];
+  }
+  _conjugated.skaterName = `conjugate(${skater.skaterName || "?"})`;
+  return _conjugated;
+}

package/cov.mjs

@@ -0,0 +1,95 @@
+// Online covariance estimators — JS port of skaters/cov/*.py.
+//
+// API: [mean, cov, state] = f(y, state)
+// y is an array of floats; cov is a flat row-major n*n array.
+
+export function runningCov(y, state) {
+  const n = y.length;
+  if (state === null || state === undefined) {
+    state = { n: 0, mean: new Array(n).fill(0.0), C: new Array(n * n).fill(0.0) };
+  }
+  state.n += 1;
+  const k = state.n;
+  const mean = state.mean;
+  const C = state.C;
+
+  const delta = new Array(n);
+  for (let i = 0; i < n; i++) delta[i] = y[i] - mean[i];
+  for (let i = 0; i < n; i++) mean[i] += delta[i] / k;
+  const delta2 = new Array(n);
+  for (let i = 0; i < n; i++) delta2[i] = y[i] - mean[i];
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) C[i * n + j] += delta[i] * delta2[j];
+  }
+
+  let cov;
+  if (k < 2) cov = new Array(n * n).fill(0.0);
+  else cov = C.map((c) => c / (k - 1));
+  return [mean.slice(), cov, state];
+}
+
+export function emaCov(y, state, alpha = 0.05) {
+  const n = y.length;
+  if (state === null || state === undefined) {
+    state = { mean: y.slice(), cov: new Array(n * n).fill(0.0), n: 1 };
+    return [y.slice(), new Array(n * n).fill(0.0), state];
+  }
+  const mean = state.mean;
+  const cov = state.cov;
+  state.n += 1;
+
+  const delta = new Array(n);
+  for (let i = 0; i < n; i++) delta[i] = y[i] - mean[i];
+  for (let i = 0; i < n; i++) mean[i] += alpha * delta[i];
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      cov[i * n + j] = (1 - alpha) * (cov[i * n + j] + alpha * delta[i] * delta[j]);
+    }
+  }
+  return [mean.slice(), cov.slice(), state];
+}
+
+export function ledoitWolfCov(y, state, alpha = 0.05, shrinkage = 0.5) {
+  const n = y.length;
+  if (state === null || state === undefined) {
+    const corr = new Array(n * n);
+    for (let i = 0; i < n; i++) for (let j = 0; j < n; j++) corr[i * n + j] = i === j ? 1.0 : 0.0;
+    state = { mean: y.slice(), var: new Array(n).fill(0.0), corr, n: 1 };
+    return [y.slice(), new Array(n * n).fill(0.0), state];
+  }
+  const mean = state.mean;
+  const varr = state.var;
+  const corr = state.corr;
+  state.n += 1;
+
+  const delta = new Array(n);
+  for (let i = 0; i < n; i++) delta[i] = y[i] - mean[i];
+  for (let i = 0; i < n; i++) mean[i] += alpha * delta[i];
+  const delta2 = new Array(n);
+  for (let i = 0; i < n; i++) delta2[i] = y[i] - mean[i];
+  for (let i = 0; i < n; i++) varr[i] = (1 - alpha) * varr[i] + alpha * delta[i] * delta2[i];
+
+  for (let i = 0; i < n; i++) {
+    const si = varr[i] > 1e-16 ? Math.sqrt(varr[i]) : 1e-8;
+    for (let j = i + 1; j < n; j++) {
+      const sj = varr[j] > 1e-16 ? Math.sqrt(varr[j]) : 1e-8;
+      const zCross = (delta[i] / si) * (delta[j] / sj);
+      const idx = i * n + j;
+      let c = (1 - alpha) * corr[idx] + alpha * zCross;
+      c = Math.max(-1.0, Math.min(1.0, c));
+      corr[idx] = c;
+      corr[j * n + i] = c;
+    }
+  }
+
+  const shrunkCov = new Array(n * n).fill(0.0);
+  for (let i = 0; i < n; i++) {
+    const si = varr[i] > 1e-16 ? Math.sqrt(varr[i]) : 1e-8;
+    for (let j = 0; j < n; j++) {
+      const sj = varr[j] > 1e-16 ? Math.sqrt(varr[j]) : 1e-8;
+      if (i === j) shrunkCov[i * n + j] = varr[i];
+      else shrunkCov[i * n + j] = (1 - shrinkage) * corr[i * n + j] * si * sj;
+    }
+  }
+  return [mean.slice(), shrunkCov, state];
+}