skaters 0.11.0

package/dist.mjs

@@ -0,0 +1,276 @@
+// Gaussian mixture distribution — JS port of skaters/dist.py.
+//
+// A Dist is a weighted mixture of Gaussians: components = [[w, m, s], ...].
+// Weights are positive and normalized to sum to 1; std is always > 0.
+// Pure JS, no dependencies. JS lacks Math.erf, so we provide a
+// high-accuracy erf (regularized incomplete gamma) to match Python's
+// math.erf closely enough for CDF/quantile parity.
+
+const SQRT2 = Math.SQRT2;
+const SQRT2PI = Math.sqrt(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) ---
+
+function _gser(a, x) {
+  // Series expansion for P(a, x), valid for x < a + 1.
+  let ap = a;
+  let sum = 1.0 / a;
+  let del = sum;
+  for (let i = 0; i < 300; i++) {
+    ap += 1.0;
+    del *= x / ap;
+    sum += del;
+    if (Math.abs(del) < Math.abs(sum) * 1e-17) break;
+  }
+  return sum * Math.exp(-x + a * Math.log(x) - LGAMMA_HALF);
+}
+
+function _gcf(a, x) {
+  // Continued fraction for Q(a, x) via the modified Lentz algorithm.
+  const TINY = 1e-300;
+  let b = x + 1.0 - a;
+  let c = 1.0 / TINY;
+  let d = 1.0 / b;
+  let h = d;
+  for (let i = 1; i <= 300; i++) {
+    const an = -i * (i - a);
+    b += 2.0;
+    d = an * d + b;
+    if (Math.abs(d) < TINY) d = TINY;
+    c = b + an / c;
+    if (Math.abs(c) < TINY) c = TINY;
+    d = 1.0 / d;
+    const del = d * c;
+    h *= del;
+    if (Math.abs(del - 1.0) < 1e-17) break;
+  }
+  return Math.exp(-x + a * Math.log(x) - LGAMMA_HALF) * h;
+}
+
+function _gammp(a, x) {
+  if (x <= 0.0) return 0.0;
+  if (x < a + 1.0) return _gser(a, x);
+  return 1.0 - _gcf(a, x);
+}
+
+export function erf(x) {
+  if (x === 0.0) return 0.0;
+  const r = _gammp(0.5, x * x);
+  return x < 0.0 ? -r : r;
+}
+
+// --- pure-JS Gaussian math (mirrors dist.py) ---
+
+function gaussianPdf(x, mean, std) {
+  if (std <= 0) return x === mean ? Infinity : 0.0;
+  const z = (x - mean) / std;
+  return Math.exp(-0.5 * z * z) / (std * SQRT2PI);
+}
+
+function gaussianCdf(x, mean, std) {
+  if (std <= 0) return x >= mean ? 1.0 : 0.0;
+  return 0.5 * (1.0 + erf((x - mean) / (std * SQRT2)));
+}
+
+function absExpectation(m, s) {
+  // E|N(m, s^2)| = m(2Φ(m/s) - 1) + 2s·φ(m/s).
+  if (s <= 0) return Math.abs(m);
+  const z = m / s;
+  return m * (2.0 * gaussianCdf(z, 0.0, 1.0) - 1.0) + 2.0 * s * gaussianPdf(z, 0.0, 1.0);
+}
+
+// Neumaier-compensated sum, matching CPython 3.12+'s built-in sum() on floats
+// (the Python reference uses sum() for Dist normalisation and moments; the port
+// must reproduce it bit-for-bit or pruning tie-breaks diverge).
+export function fsum(values) {
+  let s = 0.0, c = 0.0;
+  for (const x of values) {
+    const t = s + x;
+    if (Math.abs(s) >= Math.abs(x)) c += (s - t) + x;
+    else c += (x - t) + s;
+    s = t;
+  }
+  return s + c;
+}
+
+export class Dist {
+  // components: array of [weight, mean, std]
+  constructor(components) {
+    if (!components || components.length === 0) {
+      throw new Error("Dist requires at least one component");
+    }
+    const wTotal = fsum(components.map((c) => c[0]));
+    if (!(wTotal > 0)) throw new Error("Dist weights must sum to > 0");
+    this.components = components.map(([w, m, s]) => [w / wTotal, m, s]);
+  }
+
+  // --- constructors ---
+
+  static gaussian(mean = 0.0, std = 1.0) {
+    return new Dist([[1.0, mean, std]]);
+  }
+
+  static combine(dists, weights = null) {
+    const n = dists.length;
+    if (weights === null) weights = new Array(n).fill(1.0 / n);
+    const wTotal = fsum(weights);
+    const components = [];
+    for (let i = 0; i < n; i++) {
+      const wOuter = weights[i];
+      for (const [wInner, m, s] of dists[i].components) {
+        components.push([(wOuter / wTotal) * wInner, m, s]);
+      }
+    }
+    return new Dist(components);
+  }
+
+  // --- queries ---
+
+  pdf(x) {
+    let total = 0.0;
+    for (const [w, m, s] of this.components) total += w * gaussianPdf(x, m, s);
+    return total;
+  }
+
+  logpdf(x) {
+    const p = this.pdf(x);
+    return p > 0 ? Math.log(p) : -Infinity;
+  }
+
+  cdf(x) {
+    let total = 0.0;
+    for (const [w, m, s] of this.components) total += w * gaussianCdf(x, m, s);
+    return total;
+  }
+
+  crps(x) {
+    // Closed-form CRPS for a Gaussian mixture (Grimit et al. 2006).
+    const comps = this.components;
+    let t1 = 0.0;
+    for (const [w, m, s] of comps) t1 += w * absExpectation(m - x, s);
+    let t2 = 0.0;
+    for (const [wi, mi, si] of comps) {
+      for (const [wj, mj, sj] of comps) {
+        t2 += wi * wj * absExpectation(mi - mj, Math.sqrt(si * si + sj * sj));
+      }
+    }
+    return t1 - 0.5 * t2;
+  }
+
+  quantile(p, tol = 1e-9, maxIter = 100) {
+    if (!(p > 0 && p < 1)) throw new Error("quantile p must be in (0, 1)");
+    const mu = this.mean;
+    const sigma = Math.sqrt(this.var);
+    let lo = mu - 8 * sigma;
+    let hi = mu + 8 * sigma;
+    for (let i = 0; i < maxIter; i++) {
+      const mid = 0.5 * (lo + hi);
+      if (this.cdf(mid) < p) lo = mid;
+      else hi = mid;
+      if (hi - lo < tol) break;
+    }
+    return 0.5 * (lo + hi);
+  }
+
+  get mean() {
+    return fsum(this.components.map(([w, m]) => w * m));
+  }
+
+  get var() {
+    // centered form: avoids catastrophic cancellation when means are large
+    // relative to spreads (which would otherwise yield var=0, std=0).
+    const mu = this.mean;
+    return fsum(this.components.map(([w, m, s]) => w * (s * s + (m - mu) * (m - mu))));
+  }
+
+  get std() {
+    const v = this.var;
+    return v > 0 ? Math.sqrt(v) : 0.0;
+  }
+
+  // --- transform support ---
+
+  shift(delta) {
+    return new Dist(this.components.map(([w, m, s]) => [w, m + delta, s]));
+  }
+
+  scale(factor) {
+    if (factor === 0) throw new Error("scale factor must be nonzero");
+    const f = Math.abs(factor);
+    return new Dist(this.components.map(([w, m, s]) => [w, m * factor, s * f]));
+  }
+
+  affine(a, b) {
+    if (a === 0) throw new Error("affine a must be nonzero");
+    return new Dist(this.components.map(([w, m, s]) => [w, a * m + b, Math.abs(a) * s]));
+  }
+
+  // Number of mixture components (mirrors Python's __len__).
+  get length() {
+    return this.components.length;
+  }
+
+  // --- pruning ---
+
+  prune(maxComponents = 20) {
+    maxComponents = Math.max(1, maxComponents);   // a Dist needs >=1 component
+    if (this.components.length <= maxComponents) return this;
+    // Sort first so the merge path (and hence the result) is independent of
+    // component order — mixtures are order-free but the closest-pair scan
+    // is not, and ties at equal means are common (lattice atoms).
+    let comps = this.components.map((c) => c.slice())
+      .sort((a, b) => (a[1] - b[1]) || (a[2] - b[2]) || (a[0] - b[0]));
+    // Pair selection tolerates last-ulp noise in the means: pick the FIRST
+    // pair within a hair of the true minimum distance, so platforms that
+    // disagree at the ulp level (e.g. libm erf vs a polynomial) still merge
+    // the same pairs in the same order. Exact argmin would amplify ulp
+    // noise into macroscopically different mixtures.
+    const scale = Math.abs(comps[0][1]) + Math.abs(comps[comps.length - 1][1]) + 1e-12;
+    while (comps.length > maxComponents) {
+      let bestDist = Infinity;
+      for (let i = 0; i < comps.length; i++)
+        for (let j = i + 1; j < comps.length; j++) {
+          const d = Math.abs(comps[i][1] - comps[j][1]);
+          if (d < bestDist) bestDist = d;
+        }
+      const thresh = bestDist + 1e-9 * scale;
+      let bestI = null, bestJ = null;
+      outer:
+      for (let i = 0; i < comps.length; i++)
+        for (let j = i + 1; j < comps.length; j++)
+          if (Math.abs(comps[i][1] - comps[j][1]) <= thresh) { bestI = i; bestJ = j; break outer; }
+      const [wi, mi, si] = comps[bestI];
+      const [wj, mj, sj] = comps[bestJ];
+      const wNew = wi + wj;
+      let mNew, sNew;
+      if (wNew < 1e-300) {
+        mNew = 0.5 * (mi + mj);
+        sNew = Math.max(si, sj, 1e-12);
+      } else {
+        mNew = (wi * mi + wj * mj) / wNew;
+        const vNew =
+          (wi * (si * si + (mi - mNew) * (mi - mNew))
+            + wj * (sj * sj + (mj - mNew) * (mj - mNew))) / wNew;
+        sNew = Math.sqrt(Math.max(vNew, 0.0));
+      }
+      comps[bestI] = [wNew, mNew, sNew];
+      comps.splice(bestJ, 1);
+    }
+    return new Dist(comps);
+  }
+
+  // --- serialization ---
+
+  toDict() {
+    return { components: this.components.map((c) => c.slice()) };
+  }
+
+  static fromDict(d) {
+    return new Dist(d.components.map((c) => c.slice()));
+  }
+
+  get length() {
+    return this.components.length;
+  }
+}

package/ema.mjs

@@ -0,0 +1,12 @@
+// EMA skater — JS port of skaters/ema.py.
+// ema(alpha, k) = conjugate(leaf(k), emaTransform(alpha)).
+
+import { leaf } from "./leaf.mjs";
+import { emaTransform } from "./transform.mjs";
+import { conjugate } from "./conjugate.mjs";
+
+export function ema(alpha = 0.05, k = 1) {
+  const f = conjugate(leaf(k), emaTransform(alpha), k);
+  f.skaterName = `ema(alpha=${alpha}, k=${k})`;
+  return f;
+}

package/ensemble.mjs

@@ -0,0 +1,56 @@
+// Precision-weighted ensemble — JS port of skaters/ensemble.py.
+
+import { Dist } from "./dist.mjs";
+import { runningVarInit, runningVarUpdate, runningMseGet } from "./runstats.mjs";
+
+export function precisionWeightedEnsemble(skaters, k = 1, floor = 1e-6) {
+  const n = skaters.length;
+  if (n <= 0) throw new Error("ensemble needs at least one skater");
+
+  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 }, () => [])),
+        stats: Array.from({ length: n }, () =>
+          Array.from({ length: k }, () => runningVarInit())
+        ),
+      };
+    }
+
+    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);
+    }
+
+    for (let i = 0; i < n; i++) {
+      for (let h = 0; h < k; h++) {
+        const q = state.queues[i][h];
+        if (q.length) {
+          const predMean = q.shift();
+          const error = y - predMean;
+          state.stats[i][h] = runningVarUpdate(state.stats[i][h], error);
+        }
+        state.queues[i][h].push(allDists[i][h].mean);
+      }
+    }
+
+    const combined = [];
+    for (let h = 0; h < k; h++) {
+      const weights = [];
+      for (let i = 0; i < n; i++) {
+        const mse = runningMseGet(state.stats[i][h]);
+        let w = Number.isFinite(mse) && mse > 0 ? 1.0 / mse : floor;
+        weights.push(Math.max(w, floor));
+      }
+      const horizonDists = [];
+      for (let i = 0; i < n; i++) horizonDists.push(allDists[i][h]);
+      combined.push(Dist.combine(horizonDists, weights));
+    }
+    return [combined, state];
+  }
+  _skater.skaterName = `precision_weighted_ensemble(n=${n}, k=${k})`;
+  return _skater;
+}

package/index.mjs

@@ -0,0 +1,31 @@
+// skaters — fast univariate online time series models (JS port).
+// Faithful port of the Python package; numeric parity is enforced by
+// parity/check.mjs against the Python reference.
+
+export { Dist, erf } from "./dist.mjs";
+export {
+  runningVarInit, runningVarUpdate, runningVarGet, runningStdGet, runningMseGet,
+} from "./runstats.mjs";
+export { leaf, scaleMixtureLeaf, crpsLeaf, garchLeaf } from "./leaf.mjs";
+export { ema } from "./ema.mjs";
+export { conjugate } from "./conjugate.mjs";
+export {
+  difference, fractionalDifference, standardize, emaTransform, ouTransform, theta, drift,
+  holtLinear, garch, seasonalDifference, powerTransform, ar, groupedAr,
+} from "./transform.mjs";
+export { precisionWeightedEnsemble } from "./ensemble.mjs";
+export { bayesianEnsemble } from "./bayesian.mjs";
+export { terminalLeafEnsemble } from "./terminal.mjs";
+export { search, TRANSFORMS } from "./search.mjs";
+export { periodDetector, topPeriods, DEFAULT_LAGS } from "./periodicity.mjs";
+export {
+  buildCandidates, laplace,
+} from "./api.mjs";
+export { multiscale } from "./multiscale.mjs";
+export { sticky } from "./sticky.mjs";
+export {
+  build, name as specName, toJson, fromJson,
+  leafSpec, emaSpec, ensembleSpec, conjugateSpec,
+  diffSpec, fracSpec, stdSpec, emaTSpec,
+} from "./spec.mjs";
+export { runningCov, emaCov, ledoitWolfCov } from "./cov.mjs";

package/leaf.mjs

@@ -0,0 +1,211 @@
+// Residual distribution estimator (the leaf) — JS port of skaters/leaf.py.
+
+import { fsum, Dist, erf } from "./dist.mjs";
+import { runningVarInit, runningVarUpdate, runningVarGet } from "./runstats.mjs";
+
+// A skater is a function (y, state) -> [dists, state].
+// state is null on the first call.
+
+export function leaf(k = 1) {
+  function _leaf(y, state) {
+    if (state === null || state === undefined) {
+      state = { var: runningVarInit() };
+    }
+    state.var = runningVarUpdate(state.var, y);
+    const [, varr] = runningVarGet(state.var);
+
+    let std;
+    if (Number.isFinite(varr) && varr > 0) {
+      std = Math.sqrt(varr);
+    } else {
+      // Bootstrap: use |y| as a rough scale until we have data.
+      std = Math.max(Math.abs(y), 1e-8);
+    }
+
+    const d = Dist.gaussian(0.0, std);
+    const dists = new Array(k).fill(d);
+    return [dists, state];
+  }
+  _leaf.skaterName = `leaf(k=${k})`;
+  return _leaf;
+}
+
+const SCALE_BASIS = [0.7, 1.0, 1.6, 3.0, 6.0];
+
+// Fixed Gaussian scale mixture, online-EM weights + EWMA scale — the
+// "discrepancy from N(0,1)" leaf. JS port of scale_mixture_leaf.
+export function scaleMixtureLeaf(k = 1, gamma = 0.02, scaleAlpha = 0.01, scales = SCALE_BASIS) {
+  const C = scales.slice();
+  const K = C.length;
+  let oneIdx = 0;
+  let best = Infinity;
+  for (let i = 0; i < K; i++) {
+    const dd = Math.abs(C[i] - 1.0);
+    if (dd < best) { best = dd; oneIdx = i; }
+  }
+
+  function _leaf(y, state) {
+    if (state === null || state === undefined) {
+      const w = new Array(K).fill(1e-6);
+      w[oneIdx] = 1.0;
+      state = { v: 0.0, w, n: 0 };
+    }
+    state.n += 1;
+    const a = scaleAlpha > 1.0 / state.n ? scaleAlpha : 1.0 / state.n;
+    state.v = (1 - a) * state.v + a * y * y;
+    const varr = state.v;
+    const sigma = Number.isFinite(varr) && varr > 0 ? Math.sqrt(varr) : Math.max(Math.abs(y), 1e-8);
+    const z = y / sigma;
+    const w = state.w;
+    const dens = new Array(K);
+    for (let i = 0; i < K; i++) {
+      dens[i] = w[i] * Math.exp(-0.5 * z * z / (C[i] * C[i])) / C[i];
+    }
+    const total = fsum(dens);
+    if (total > 0) {
+      const g = gamma > 1.0 / state.n ? gamma : 1.0 / state.n;
+      state.w = w.map((wi, i) => (1 - g) * wi + g * dens[i] / total);
+    }
+    const comps = C.map((c, i) => [state.w[i], 0.0, c * sigma]);
+    const d = new Dist(comps);
+    return [new Array(k).fill(d), state];
+  }
+  _leaf.skaterName = `scale_mixture_leaf(k=${k})`;
+  return _leaf;
+}
+
+// CRPS leaf — JS port of skaters/leaf.py:crps_leaf. Same scale-mixture form,
+// weights fit by online CRPS-gradient (exponentiated gradient on the simplex).
+const S2 = Math.sqrt(2.0);
+const INV = 1.0 / Math.sqrt(2.0 * Math.PI);
+const A0 = 2.0 * INV;
+const FINE = [0.4, 0.512, 0.6554, 0.8389, 1.0737, 1.3744, 1.7592, 2.2518, 2.8823, 3.6893, 4.7224, 6.0446, 7.7371, 9.9035, 12.6765];
+
+function phiStd(x) { return Math.exp(-0.5 * x * x) * INV; }
+function PhiStd(x) { return 0.5 * (1.0 + erf(x / S2)); }
+function absNormal(m, s) {
+  if (s <= 0) return Math.abs(m);
+  const z = m / s;
+  return m * (2.0 * PhiStd(z) - 1.0) + 2.0 * s * phiStd(z);
+}
+
+export function crpsLeaf(k = 1, eta = 1.0, scaleAlpha = 0.01, scales = FINE) {
+  const C = scales.slice();
+  const K = C.length;
+  const B = C.map((ca) => C.map((cb) => Math.sqrt(ca * ca + cb * cb) * A0));
+  let oneIdx = 0, best = Infinity;
+  for (let i = 0; i < K; i++) { const d = Math.abs(C[i] - 1.0); if (d < best) { best = d; oneIdx = i; } }
+
+  function _leaf(y, state) {
+    if (state === null || state === undefined) {
+      const w = new Array(K).fill(1e-6); w[oneIdx] = 1.0;
+      state = { v: 0.0, w, n: 0 };
+    }
+    state.n += 1;
+    const a = scaleAlpha > 1.0 / state.n ? scaleAlpha : 1.0 / state.n;
+    state.v = (1 - a) * state.v + a * y * y;
+    const sig = Number.isFinite(state.v) && state.v > 0 ? Math.sqrt(state.v) : Math.max(Math.abs(y), 1e-8);
+    const z = y / sig;
+    const w = state.w;
+    const g = new Array(K);
+    for (let c = 0; c < K; c++) {
+      let dot = 0.0;
+      dot = fsum(w.map((wj, j) => wj * B[c][j]));
+      g[c] = absNormal(-z, C[c]) - dot;
+    }
+    const gm = fsum(g) / K;
+    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);
+    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];
+  }
+  _leaf.skaterName = `crps_leaf(k=${k}, eta=${eta})`;
+  return _leaf;
+}
+
+
+// GARCH(1,1)-t leaf — JS port of skaters/leaf.garch_leaf. Genuine GARCH
+// conditional variance (variance-targeted QMLE refit over a fixed grid) + the
+// same Gaussian-scale-mixture (Student-t) tails.
+const GARCH_AB_GRID = [];
+for (const a of [0.02, 0.04, 0.06, 0.09, 0.12, 0.16, 0.20]) {
+  for (const b of [0.72, 0.78, 0.84, 0.88, 0.92, 0.95, 0.97]) {
+    if (a + b < 0.999) GARCH_AB_GRID.push([a, b]);
+  }
+}
+const GARCH_OMEGA_MULT = [0.5, 0.7, 1.0, 1.4, 2.0];
+
+export function garchLeaf(k = 1, gamma = 0.02, refitEvery = 40, minObs = 80,
+                          window = 400, scales = SCALE_BASIS) {
+  const C = scales.slice();
+  const K = C.length;
+  let oneIdx = 0, best = Infinity;
+  for (let i = 0; i < K; i++) { const dd = Math.abs(C[i] - 1.0); if (dd < best) { best = dd; oneIdx = i; } }
+
+  function _leaf(y, state) {
+    if (state === null || state === undefined) {
+      const w = new Array(K).fill(1e-6); w[oneIdx] = 1.0;
+      state = { h: 0.0, s2: 0.0, n: 0, omega: 0.0, alpha: 0.05, beta: 0.90, buf: [], w, last_r2: 0.0 };
+    }
+    const s = state;
+    s.n += 1;
+    const a0 = 0.02 > 1.0 / s.n ? 0.02 : 1.0 / s.n;
+    s.s2 = (1 - a0) * s.s2 + a0 * y * y;
+    if (s.s2 <= 0) s.s2 = Math.max(y * y, 1e-12);
+
+    let h;
+    if (s.n === 1) h = s.s2;
+    else h = s.omega + s.alpha * s.last_r2 + s.beta * s.h;
+    if (h <= 1e-300) h = s.s2;
+    s.h = h;
+    s.last_r2 = y * y;
+    s.buf.push(y);
+    if (s.buf.length > window) s.buf.shift();
+
+    if (s.n >= minObs && s.n % refitEvery === 0 && s.buf.length >= minObs) {
+      const resid = s.buf;
+      const s2 = fsum(resid.map((r) => r * r)) / resid.length;
+      if (s2 > 0) {
+        // grid over (alpha, beta) AND a free omega multiplier (issue #25)
+        let bestV = Infinity, bom = s.omega, bal = s.alpha, bbe = s.beta;
+        for (let gi = 0; gi < GARCH_AB_GRID.length; gi++) {
+          const al = GARCH_AB_GRID[gi][0], be = GARCH_AB_GRID[gi][1];
+          const base = (1.0 - al - be) * s2;
+          for (let ci = 0; ci < GARCH_OMEGA_MULT.length; ci++) {
+            let om = base * GARCH_OMEGA_MULT[ci];
+            if (om <= 1e-12) om = 1e-12;
+            let hh = om / (1.0 - al - be);          // unconditional-variance init
+            let v = 0.0;
+            for (let i = 0; i < resid.length; i++) {
+              const r = resid[i];
+              hh = om + al * (r * r) + be * hh;
+              if (hh <= 1e-300) hh = 1e-300;
+              v += Math.log(hh) + (r * r) / hh;
+            }
+            if (v < bestV) { bestV = v; bom = om; bal = al; bbe = be; }   // first-wins on tie
+          }
+        }
+        s.alpha = bal; s.beta = bbe; s.omega = bom;
+      }
+    }
+
+    const sigma = (Number.isFinite(h) && h > 0) ? Math.sqrt(h) : Math.max(Math.abs(y), 1e-8);
+    const z = y / sigma;
+    const w = s.w;
+    const dens = new Array(K);
+    let total = 0.0;
+    for (let i = 0; i < K; i++) dens[i] = w[i] * Math.exp(-0.5 * z * z / (C[i] * C[i])) / C[i];
+    total = fsum(dens);
+    if (total > 0) {
+      const g = gamma > 1.0 / s.n ? gamma : 1.0 / s.n;
+      s.w = w.map((wi, i) => (1 - g) * wi + g * dens[i] / total);
+    }
+    const comps = C.map((c, i) => [s.w[i], 0.0, c * sigma]);
+    return [new Array(k).fill(new Dist(comps)), s];
+  }
+  _leaf.skaterName = `garch_leaf(k=${k})`;
+  return _leaf;
+}

package/multiscale.mjs

@@ -0,0 +1,70 @@
+// Multi-scale ensemble — JS port of skaters/multiscale.py.
+//
+// Combine forecasters running on decimated clocks: one base instance per
+// stride s (with s phase-shifted copies so the freshest coarse forecast is
+// always anchored at the current tick; exactly one copy steps per tick), and
+// per fine horizon h mix each eligible scale's (s <= h) predictive Dist under
+// likelihood softmax weights. Granularity is the one candidate axis that
+// cannot live inside the transform pool (decimation is many-ticks-to-one and
+// a coarse model emits no fine one-step predictive to weight), hence a
+// wrapper. With scales == [1] (e.g. k == 1) the base is returned unwrapped.
+
+import { Dist } from "./dist.mjs";
+
+const LOGPDF_FLOOR = -20.0;
+
+export function multiscale(base, k, { scales = null, forget = 0.99, maxComponents = 20 } = {}) {
+  if (scales === null) scales = [1, Math.ceil(Math.sqrt(k)), k];
+  scales = [...new Set(scales.map((s) => Math.trunc(s)).filter((s) => s >= 1 && s <= k))]
+    .sort((a, b) => a - b);
+  if (!(scales.length && scales[0] === 1)) throw new Error("scales must include 1");
+  if (scales.length === 1) return base(k);
+  const subs = {};
+  for (const s of scales) subs[s] = base(Math.max(1, Math.ceil(k / s)));
+
+  return function skater(y, state) {
+    if (state === null || state === undefined) {
+      state = { t: 0, phase: {}, pending: {}, latest: {}, score: {} };
+      for (const s of scales) {
+        state.phase[s] = new Array(s).fill(null);
+        state.pending[s] = new Array(s).fill(null);
+        state.score[s] = null;
+      }
+    }
+    const t = state.t;
+    for (const s of scales) {
+      const ph = t % s;
+      const prev = state.pending[s][ph];
+      if (prev !== null) {
+        const lp = Math.max(prev.logpdf(y), LOGPDF_FLOOR);
+        const m = state.score[s];
+        state.score[s] = m === null ? lp : forget * m + (1.0 - forget) * lp;
+      }
+      const [dists, st] = subs[s](y, state.phase[s][ph]);
+      state.phase[s][ph] = st;
+      state.pending[s][ph] = dists[0];
+      state.latest[s] = dists;
+    }
+    state.t = t + 1;
+
+    const ms = scales.map((s) => state.score[s]).filter((m) => m !== null);
+    const top = ms.length ? Math.max(...ms) : 0.0;
+    const out = [];
+    for (let h = 1; h <= k; h++) {
+      const fcs = [], wts = [];
+      for (const s of scales) {
+        if (s > h || !(s in state.latest)) continue;
+        const j = Math.max(1, Math.floor(h / s + 0.5));   // half-up, matches Python
+        const dists = state.latest[s];
+        if (j - 1 >= dists.length) continue;
+        fcs.push(dists[j - 1]);
+        const m = state.score[s];
+        wts.push(Math.exp((m === null ? top : m) - top));
+      }
+      // One eligible scale (e.g. h < every coarse stride): pass its Dist
+      // through untouched — no renormalise, no prune.
+      out.push(fcs.length === 1 ? fcs[0] : Dist.combine(fcs, wts).prune(maxComponents));
+    }
+    return [out, state];
+  };
+}