skaters 0.11.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "skaters",
+  "version": "0.11.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",
+  "module": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./package.json": "./package.json",
+    "./*.mjs": "./*.mjs",
+    "./*": "./*.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "time-series",
+    "forecasting",
+    "online",
+    "distributional",
+    "probabilistic",
+    "density",
+    "quantile",
+    "crps",
+    "log-likelihood",
+    "laplace",
+    "garch",
+    "zero-dependency",
+    "browser",
+    "microprediction"
+  ],
+  "homepage": "https://skaters.microprediction.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microprediction/skaters.git",
+    "directory": "docs/js/skaters"
+  },
+  "bugs": {
+    "url": "https://github.com/microprediction/skaters/issues"
+  },
+  "author": "Peter Cotton",
+  "license": "MIT"
+}

package/periodicity.mjs

@@ -0,0 +1,58 @@
+// Online periodicity detection — JS port of skaters/periodicity.py.
+
+export const DEFAULT_LAGS = [2, 3, 4, 5, 6, 7, 12, 14, 24, 28, 30, 52, 60, 90, 168, 365];
+
+export function periodDetector(lags = null, alpha = 0.01, minObservations = 50) {
+  if (lags === null) lags = DEFAULT_LAGS.slice();
+  const maxLag = Math.max(...lags);
+
+  function _detect(y, state) {
+    if (state === null || state === undefined) {
+      const cross = {};
+      for (const L of lags) cross[L] = 0.0;
+      state = { buffer: [], n: 0, mean: 0.0, var: 0.0, cross };
+    }
+    const buf = state.buffer;
+    buf.push(y);
+    state.n += 1;
+
+    const diff = y - state.mean;
+    state.mean += alpha * diff;
+    state.var = (1 - alpha) * (state.var + alpha * diff * diff);
+
+    const mu = state.mean;
+    const varr = state.var;
+
+    for (const L of lags) {
+      if (buf.length > L) {
+        const yLagged = buf[buf.length - 1 - L];
+        const cross = (y - mu) * (yLagged - mu);
+        state.cross[L] = (1 - alpha) * state.cross[L] + alpha * cross;
+      }
+    }
+
+    if (buf.length > maxLag + 1) buf.shift();
+
+    if (state.n < minObservations || varr < 1e-12) return [[], state];
+
+    const scores = [];
+    for (let li = 0; li < lags.length; li++) {
+      const L = lags[li];
+      if (state.n > L) {
+        const acf = varr > 0 ? state.cross[L] / varr : 0.0;
+        scores.push([L, acf, li]); // li carried to keep the stable-sort order
+      }
+    }
+    // Sort by |acf| descending, ties keep original (lags) order.
+    scores.sort((a, b) => {
+      const d = Math.abs(b[1]) - Math.abs(a[1]);
+      return d !== 0 ? d : a[2] - b[2];
+    });
+    return [scores.map(([L, acf]) => [L, acf]), state];
+  }
+  return _detect;
+}
+
+export function topPeriods(scores, threshold = 0.3, maxPeriods = 3) {
+  return scores.slice(0, maxPeriods).filter(([, acf]) => Math.abs(acf) >= threshold).map(([lag]) => lag);
+}

package/runstats.mjs

@@ -0,0 +1,33 @@
+// Lightweight online running statistics — JS port of skaters/runstats.py.
+// Welford's algorithm for mean/variance. Pure JS, no dependencies.
+
+export function runningVarInit() {
+  return { n: 0, mean: 0.0, m2: 0.0 };
+}
+
+export function runningVarUpdate(state, x) {
+  const n = state.n + 1;
+  const delta = x - state.mean;
+  const mean = state.mean + delta / n;
+  const delta2 = x - mean;
+  const m2 = state.m2 + delta * delta2;
+  return { n, mean, m2 };
+}
+
+export function runningVarGet(state) {
+  // Returns [mean, variance]. Variance is +Infinity until n >= 2.
+  if (state.n < 2) return [state.mean, Infinity];
+  return [state.mean, state.m2 / (state.n - 1)];
+}
+
+export function runningStdGet(state) {
+  const [, v] = runningVarGet(state);
+  return Number.isFinite(v) ? Math.sqrt(v) : Infinity;
+}
+
+export function runningMseGet(state) {
+  if (state.n < 1) return Infinity;
+  const [mean, v] = runningVarGet(state);
+  if (!Number.isFinite(v)) return Infinity;
+  return mean * mean + v;
+}

package/search.mjs

@@ -0,0 +1,236 @@
+// Adaptive search over the transform tree — JS port of skaters/search.py.
+
+import { Dist } from "./dist.mjs";
+import { leaf } from "./leaf.mjs";
+import { conjugate } from "./conjugate.mjs";
+import {
+  difference, fractionalDifference, standardize, emaTransform, garch,
+  seasonalDifference, powerTransform, ar, groupedAr, drift, holtLinear, theta,
+} from "./transform.mjs";
+import { periodDetector, topPeriods } from "./periodicity.mjs";
+
+// Grammar: [name, factory, costPerObs]. Order matters for parity.
+export const TRANSFORMS = [
+  ["ema_t(0.05)", () => emaTransform(0.05), 1],
+  ["ema_t(0.1)", () => emaTransform(0.1), 1],
+  ["ema_t(0.3)", () => emaTransform(0.3), 1],
+  ["diff", () => difference(), 1],
+  ["std(0.05)", () => standardize(0.05), 1],
+  ["frac(0.3)", () => fractionalDifference(0.3, 30), 3],
+  ["garch", () => garch(), 1],
+  ["pow(0.5)", () => powerTransform(0.5), 1],
+  ["ar(2)", () => ar(2), 2],
+  ["ar(5)", () => ar(5, 0.99, 1.0, 1), 3],
+  ["gar(16)", () => groupedAr(16), 2],
+  ["theta(0.1)", () => theta(0.1), 1],
+  ["theta(0.3)", () => theta(0.3), 1],
+  ["drift", () => drift(), 1],
+  ["drift(0.01)", () => drift(0.01, 0.002), 1],
+  ["holt(0.1,0.05)", () => holtLinear(0.1, 0.05), 1],
+  ["holt(0.3,0.1)", () => holtLinear(0.3, 0.1), 1],
+  ["seas(7)", () => seasonalDifference(7), 1],
+  ["seas(12)", () => seasonalDifference(12), 1],
+  ["seas(24)", () => seasonalDifference(24), 1],
+];
+
+function avgW(entry, k) {
+  let s = 0.0;
+  for (const w of entry.log_w) s += w;
+  return s / k;
+}
+
+function makeEntry(skaterFn, depth, recipe, k, cost = 0.0) {
+  return {
+    f: skaterFn,
+    s: null,
+    depth,
+    recipe,
+    cost,
+    age: 0,
+    warmed: false,
+    log_w: new Array(k).fill(0.0),
+    queues: Array.from({ length: k }, () => []),
+    dists: null,
+  };
+}
+
+function warmup(entry, buffer, k) {
+  for (const y of buffer) {
+    const [dists, s] = entry.f(y, entry.s);
+    entry.s = s;
+    entry.dists = dists;
+    entry.age += 1;
+  }
+  if (entry.dists !== null) {
+    for (let h = 0; h < k; h++) {
+      entry.queues[h].length = 0;
+      entry.queues[h].push(entry.dists[h]);
+    }
+  }
+  entry.warmed = true;
+}
+
+function initPool(k, costBudget) {
+  const pool = [];
+  const leafEntry = makeEntry(leaf(k), 0, [], k, 1.0);
+  leafEntry.warmed = true;
+  pool.push(leafEntry);
+  for (const [tName, tFactory, tCost] of TRANSFORMS) {
+    const candidateCost = 1.0 + tCost;
+    if (candidateCost > costBudget) continue;
+    const f = conjugate(leaf(k), tFactory(), k);
+    f.skaterName = `${tName}|leaf`;
+    const entry = makeEntry(f, 1, [tName], k, candidateCost);
+    entry.warmed = true;
+    pool.push(entry);
+  }
+  return pool;
+}
+
+function buildFromRecipe(recipe, k, transforms) {
+  const lookup = new Map(transforms.map(([name, factory]) => [name, factory]));
+  let f = leaf(k);
+  for (const tName of recipe) f = conjugate(f, lookup.get(tName)(), k);
+  return f;
+}
+
+function expand(pool, k, topN, maxDepth, transforms, costBudget) {
+  const scored = pool.map((e, i) => ({ avg: avgW(e, k), i, e }));
+  scored.sort((a, b) => (b.avg - a.avg) || (b.i - a.i));
+
+  const existing = new Set(pool.map((e) => e.recipe.join("|")));
+  const children = [];
+  for (const { e: parent } of scored.slice(0, topN)) {
+    if (parent.depth >= maxDepth) continue;
+    for (const [tName, , tCost] of transforms) {
+      const childCost = parent.cost + tCost;
+      if (childCost > costBudget) continue;
+      if (parent.recipe.length && parent.recipe[parent.recipe.length - 1] === tName) continue;
+      const newRecipe = parent.recipe.concat([tName]);
+      const key = newRecipe.join("|");
+      if (existing.has(key)) continue;
+      existing.add(key);
+      const childFn = buildFromRecipe(newRecipe, k, transforms);
+      childFn.skaterName = newRecipe.join("|") + "|leaf";
+      children.push(makeEntry(childFn, newRecipe.length, newRecipe, k, childCost));
+    }
+  }
+  return children;
+}
+
+function prune(pool, threshold, maxPool, k) {
+  if (pool.length <= 1) return;
+  let best = -Infinity;
+  for (const e of pool) best = Math.max(best, avgW(e, k));
+
+  let i = 0;
+  while (i < pool.length) {
+    if (avgW(pool[i], k) < best + threshold && pool.length > 1) pool.splice(i, 1);
+    else i += 1;
+  }
+  while (pool.length > maxPool) {
+    let worstIdx = 0;
+    let worst = Infinity;
+    for (let j = 0; j < pool.length; j++) {
+      const a = avgW(pool[j], k);
+      if (a < worst) {
+        worst = a;
+        worstIdx = j;
+      }
+    }
+    pool.splice(worstIdx, 1);
+  }
+}
+
+export function search({
+  k = 1,
+  learningRate = 0.5,
+  complexityPenalty = 0.02,
+  maxPool = 30,
+  expandInterval = 100,
+  expandTopN = 3,
+  maxDepth = 3,
+  replayBuffer = 500,
+  pruneThreshold = -50.0,
+  maxComponents = 20,
+  costBudget = Infinity,
+} = {}) {
+  const pdFunc = periodDetector();
+
+  function _search(y, state) {
+    if (state === null || state === undefined) {
+      state = {
+        pool: initPool(k, costBudget),
+        n_obs: 0,
+        buffer: [],
+        pd_state: null,
+        detected_periods: new Set(),
+        transforms: TRANSFORMS.slice(),
+      };
+    }
+
+    state.n_obs += 1;
+    state.buffer.push(y);
+    if (state.buffer.length > replayBuffer) state.buffer.shift();
+
+    const pool = state.pool;
+
+    for (const entry of pool) {
+      const [dists, s] = entry.f(y, entry.s);
+      entry.s = s;
+      entry.dists = dists;
+      entry.age += 1;
+    }
+
+    for (const entry of pool) {
+      for (let h = 0; h < k; h++) {
+        const q = entry.queues[h];
+        if (q.length) {
+          const pastDist = q.shift();
+          if (entry.warmed) {
+            const lp = Math.max(pastDist.logpdf(y), -20.0);
+            entry.log_w[h] += learningRate * lp - complexityPenalty * entry.depth;
+          }
+        }
+      }
+    }
+
+    for (const entry of pool) {
+      for (let h = 0; h < k; h++) entry.queues[h].push(entry.dists[h]);
+    }
+
+    const [scores, pdState] = pdFunc(y, state.pd_state);
+    state.pd_state = pdState;
+
+    if (state.n_obs % expandInterval === 0 && state.n_obs > 10) {
+      const detected = topPeriods(scores, 0.3, 3);
+      for (const period of detected) {
+        if (!state.detected_periods.has(period)) {
+          state.detected_periods.add(period);
+          const tName = `seas(${period})`;
+          state.transforms.push([tName, () => seasonalDifference(period), 2]);
+        }
+      }
+      const newChildren = expand(pool, k, expandTopN, maxDepth, state.transforms, costBudget);
+      for (const child of newChildren) warmup(child, state.buffer, k);
+      for (const child of newChildren) pool.push(child);
+      prune(pool, pruneThreshold, maxPool, k);
+    }
+
+    const combined = [];
+    for (let h = 0; h < k; h++) {
+      const logWs = pool.map((e) => e.log_w[h]);
+      const maxLw = Math.max(...logWs);
+      let weights;
+      if (Number.isFinite(maxLw)) weights = logWs.map((lw) => Math.exp(lw - maxLw));
+      else weights = new Array(pool.length).fill(1.0);
+      const horizonDists = pool.map((e) => e.dists[h]);
+      let dist = Dist.combine(horizonDists, weights);
+      if (dist.length > maxComponents) dist = dist.prune(maxComponents);
+      combined.push(dist);
+    }
+    return [combined, state];
+  }
+  _search.skaterName = `search(k=${k})`;
+  return _search;
+}

package/spec.mjs

@@ -0,0 +1,98 @@
+// Symbolic spec for skater pipelines — JS port of skaters/spec.py.
+
+import { leaf } from "./leaf.mjs";
+import { ema } from "./ema.mjs";
+import { precisionWeightedEnsemble } from "./ensemble.mjs";
+import { conjugate } from "./conjugate.mjs";
+import { difference, fractionalDifference, standardize, emaTransform } from "./transform.mjs";
+
+export function build(spec) {
+  const op = spec.op;
+  let f;
+  if (op === "leaf") {
+    f = leaf(spec.k);
+  } else if (op === "ema") {
+    f = ema(spec.alpha, spec.k);
+  } else if (op === "ensemble") {
+    const subs = spec.skaters.map(build);
+    f = precisionWeightedEnsemble(subs, spec.k, spec.floor === undefined ? 1e-6 : spec.floor);
+  } else if (op === "conjugate") {
+    const inner = build(spec.skater);
+    const t = buildTransform(spec.transform);
+    f = conjugate(inner, t, inferK(spec.skater));
+  } else {
+    throw new Error(`Unknown op: ${op}`);
+  }
+  f.skaterName = name(spec);
+  return f;
+}
+
+function buildTransform(spec) {
+  const op = spec.op;
+  if (op === "diff") return difference();
+  if (op === "frac") return fractionalDifference(spec.d, spec.window === undefined ? 50 : spec.window);
+  if (op === "std") return standardize(spec.alpha === undefined ? 0.05 : spec.alpha);
+  if (op === "ema_t") return emaTransform(spec.alpha);
+  throw new Error(`Unknown transform op: ${op}`);
+}
+
+function inferK(spec) {
+  if ("k" in spec) return spec.k;
+  if ("skater" in spec) return inferK(spec.skater);
+  if ("skaters" in spec) return inferK(spec.skaters[0]);
+  throw new Error("Cannot infer k from spec");
+}
+
+// --- canonical name ---
+
+function fmt(x) {
+  // Mimic Python's "%.6g" with integer collapse.
+  if (x === Math.trunc(x)) return String(Math.trunc(x));
+  let s = x.toPrecision(6);
+  if (s.indexOf(".") >= 0 && s.indexOf("e") < 0 && s.indexOf("E") < 0) {
+    s = s.replace(/0+$/, "").replace(/\.$/, "");
+  }
+  return s;
+}
+
+export function name(spec) {
+  const op = spec.op;
+  if (op === "leaf") return "leaf";
+  if (op === "ema") return `ema(${fmt(spec.alpha)})`;
+  if (op === "ensemble") return `ensemble(${spec.skaters.map(name).join(",")})`;
+  if (op === "conjugate") return `${transformName(spec.transform)}|${name(spec.skater)}`;
+  throw new Error(`Unknown op: ${op}`);
+}
+
+function transformName(spec) {
+  const op = spec.op;
+  if (op === "diff") return "diff";
+  if (op === "frac") {
+    const w = spec.window === undefined ? 50 : spec.window;
+    return w === 50 ? `frac(${fmt(spec.d)})` : `frac(${fmt(spec.d)},w=${w})`;
+  }
+  if (op === "std") return `std(${fmt(spec.alpha === undefined ? 0.05 : spec.alpha)})`;
+  if (op === "ema_t") return `ema_t(${fmt(spec.alpha)})`;
+  throw new Error(`Unknown transform op: ${op}`);
+}
+
+// --- serialization ---
+
+export function toJson(spec) {
+  return JSON.stringify(spec);
+}
+
+export function fromJson(s) {
+  return JSON.parse(s);
+}
+
+// --- spec constructors ---
+
+export const leafSpec = (k = 1) => ({ op: "leaf", k });
+export const emaSpec = (alpha = 0.05, k = 1) => ({ op: "ema", alpha, k });
+export const ensembleSpec = (skaterSpecs, k = 1) => ({ op: "ensemble", k, skaters: skaterSpecs });
+export const conjugateSpec = (skaterSpec, transformSpec) => ({ op: "conjugate", skater: skaterSpec, transform: transformSpec });
+export const diffSpec = () => ({ op: "diff" });
+export const fracSpec = (d = 0.4, window = 50) => ({ op: "frac", d, window });
+export const stdSpec = (alpha = 0.05) => ({ op: "std", alpha });
+export const emaTSpec = (alpha = 0.05) => ({ op: "ema_t", alpha });

package/sticky.mjs

@@ -0,0 +1,64 @@
+// Sticky / lattice projection — JS port of skaters/sticky.py.
+// Recency-weighted frequency table of exact values; atoms fire at the values
+// revisited above a noise floor (top-k by frequency), mean-preserving. The
+// single-spike behaviour is the max_atoms=1 case. Uses a Map so numeric-key
+// insertion order (hence the sort tie-break) matches Python's dict.
+
+import { fsum, Dist } from "./dist.mjs";
+
+export function sticky(base, k = 1, propensityAlpha = 0.05, spikeFrac = 0.005,
+                       threshMult = 1.8, maxAtoms = 6, pruneEps = 1e-6) {
+  function _skater(y, state) {
+    if (state === null || state === undefined) {
+      state = { base: null, counts: new Map() };
+    }
+    const [dists, baseState] = base(y, state.base);
+    state.base = baseState;
+
+    // recency-weighted frequency table of exact values.
+    const c = state.counts;
+    const drop = [];
+    for (const key of c.keys()) {
+      const v = c.get(key) * (1.0 - propensityAlpha);
+      if (v < pruneEps) drop.push(key);
+      else c.set(key, v);
+    }
+    for (const key of drop) c.delete(key);
+    c.set(y, (c.get(y) || 0.0) + propensityAlpha);
+
+    // lattice atoms = revisited values above the floor, top-k by weight.
+    const thr = threshMult * propensityAlpha;
+    let atoms = [];
+    for (const [v, w] of c) if (w > thr) atoms.push([v, w]);
+    // stable sort by descending weight; ties keep insertion order (matches Python)
+    atoms = atoms.map((a, i) => [a, i])
+      .sort((A, B) => (B[0][1] - A[0][1]) || (A[1] - B[1]))
+      .map((p) => p[0])
+      .slice(0, maxAtoms);
+
+    const out = [];
+    for (const d of dists) {
+      if (atoms.length === 0) {
+        out.push(d);
+        continue;
+      }
+      const sw = fsum(atoms.map((a) => a[1]));
+      const P = Math.min(sw, 0.999);
+      const pc = 1.0 - P;
+      const atomMean = fsum(atoms.map((a) => a[1] * a[0])) / sw;
+      const spikeStd = Math.max(spikeFrac * d.std, 1e-9);
+      if (pc <= 1e-9) {
+        out.push(new Dist(atoms.map(([v, w]) => [w / sw, v, spikeStd])));
+        continue;
+      }
+      const mu = d.mean;
+      const delta = (P * (mu - atomMean)) / pc;
+      const comps = atoms.map(([v, w]) => [P * (w / sw), v, spikeStd]);
+      for (const [w, m, s] of d.components) comps.push([pc * w, m + delta, s]);
+      out.push(new Dist(comps));
+    }
+    return [out, state];
+  }
+  _skater.skaterName = `sticky(${base.skaterName || "?"})`;
+  return _skater;
+}

package/terminal.mjs

@@ -0,0 +1,82 @@
+// Terminal-leaf ensemble — JS port of skaters/terminal.py.
+// Mix the sub-models for the MEAN; model the combined residual with one
+// terminal leaf (default the scale-mixture leaf), so its shape reaches the
+// output undiluted.
+
+import { fsum, Dist } from "./dist.mjs";
+import { crpsLeaf } from "./leaf.mjs";
+
+export function terminalLeafEnsemble(skaters, {
+  leafFn = crpsLeaf,
+  k = 1,
+  learningRate = 0.5,
+  complexityPenalty = 0.0,
+  depths = null,
+  priorLogWeights = null,
+  maxComponents = 20,
+  forget = 1.0,
+} = {}) {
+  const n = skaters.length;
+  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),
+        qdist: Array.from({ length: n }, () => []),
+        log_w: prior.slice(),
+        tleaf: Array.from({ length: k }, () => leafFn(1)),
+        leafState: new Array(k).fill(null),
+        leafPred: new Array(k).fill(null),
+        meanQ: Array.from({ length: k }, () => []),
+      };
+    }
+
+    const allDists = [];
+    for (let i = 0; i < n; i++) {
+      const [di, s] = skaters[i](y, state.sub[i]);
+      state.sub[i] = s;
+      allDists.push(di);
+    }
+
+    for (let i = 0; i < n; i++) {
+      const q = state.qdist[i];
+      if (q.length) {
+        const lp = Math.max(q.shift().logpdf(y), -20.0);
+        state.log_w[i] = forget * state.log_w[i] + learningRate * lp - complexityPenalty * d[i];
+      }
+      q.push(allDists[i][0]);
+    }
+
+    const maxLw = Math.max(...state.log_w);
+    const w = state.log_w.map((lw) => Math.exp(lw - maxLw));
+    const tot = fsum(w);
+
+    const combined = [];
+    for (let h = 0; h < k; h++) {
+      const muH = fsum(w.map((wi, i) => wi * allDists[i][h].mean)) / tot;
+
+      const mq = state.meanQ[h];
+      if (mq.length >= h + 1) {
+        const r = y - mq.shift();
+        const [ld, ls] = state.tleaf[h](r, state.leafState[h]);
+        state.leafState[h] = ls;
+        state.leafPred[h] = ld[0];
+      }
+
+      let pred;
+      if (state.leafPred[h] !== null) {
+        pred = state.leafPred[h].shift(muH);
+      } else {
+        pred = Dist.combine(allDists.map((di) => di[h]), w);
+        if (pred.components.length > maxComponents) pred = pred.prune(maxComponents);
+      }
+      combined.push(pred);
+      mq.push(muH);
+    }
+    return [combined, state];
+  }
+  _skater.skaterName = `terminal_leaf_ensemble(n=${n}, k=${k})`;
+  return _skater;
+}