skaters 0.1.0__tar.gz

skaters-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: skaters
+Version: 0.1.0
+Summary: Fast univariate time series models that run in Pyodide
+Author: Peter Cotton
+Author-email: Peter Cotton <peter.cotton@microprediction.com>
+License-Expression: MIT
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Python: >=3.10
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# skaters
+
+Fast univariate online time series models. Zero dependencies. Runs in [Pyodide](https://pyodide.org/).
+
+## Install
+
+```bash
+pip install skaters
+```
+
+## Quick start
+
+```python
+from skaters import ensemble, envelope
+
+# Create a precision-weighted ensemble of EMA models
+f = ensemble(k=3)  # predict 3 steps ahead
+
+state = None
+for y in observations:
+    x, state = f(y, state)
+    # x = [float, float, float]  (forecasts for horizons 1, 2, 3)
+
+# Want uncertainty bands? Wrap any skater with an envelope:
+f = envelope(ensemble(k=3), k=3)
+
+state = None
+for y in observations:
+    out, state = f(y, state)
+    # out["mean"] = point forecasts
+    # out["std"]  = empirical std of forecast error per horizon
+```
+
+## The skater convention
+
+A skater is any callable with this signature:
+
+```python
+x, state = f(y, state)
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `y` | `float` | New observation |
+| `state` | `dict \| None` | Prior state (`None` on first call) |
+| **Returns** | | |
+| `x` | `list[float]` | Point forecasts for horizons 1..k |
+| `state` | `dict` | Updated state (pass back next call) |
+
+Skaters only predict. Uncertainty is handled separately by the [envelope](#envelope).
+
+## Built-in skaters
+
+### EMA
+
+Exponential moving average. O(1) per observation.
+
+```python
+from skaters import ema
+
+f = ema(alpha=0.1, k=1)
+```
+
+### Convenience constructors
+
+Pre-configured EMA speeds:
+
+```python
+from skaters import rapidly, quickly, slowly, sluggishly
+
+f = rapidly(k=1)     # alpha=0.3
+f = quickly(k=1)     # alpha=0.1
+f = slowly(k=1)      # alpha=0.05
+f = sluggishly(k=1)  # alpha=0.01
+```
+
+### Precision-weighted ensemble
+
+Combines multiple skaters, weighting each by 1/MSE of its forecast errors. Automatically favors models that are both accurate and unbiased.
+
+```python
+from skaters import ensemble, precision_weighted_ensemble, ema
+
+# Default: ensemble of EMAs at different speeds
+f = ensemble(k=3)
+
+# Custom: bring your own skaters
+f = precision_weighted_ensemble(
+    skaters=[ema(alpha=0.05, k=3), ema(alpha=0.2, k=3)],
+    k=3,
+)
+```
+
+## Envelope
+
+The envelope wraps any skater and tracks empirical forecast errors at each horizon. It is model-independent — it doesn't care how the predictions are made.
+
+```python
+from skaters import envelope, ema
+
+# Welford's (uniform weight over all history)
+f = envelope(ema(alpha=0.1, k=3), k=3)
+
+# Exponentially weighted (forgets old errors, adapts to regime changes)
+f = envelope(ema(alpha=0.1, k=3), k=3, decay=0.95)
+
+state = None
+for y in observations:
+    out, state = f(y, state)
+    print(out["mean"], out["std"])
+```
+
+## Writing your own skater
+
+Any function matching the convention works:
+
+```python
+def my_skater(y: float, state: dict | None) -> tuple[list[float], dict]:
+    if state is None:
+        state = {"last": y}
+    state["last"] = y
+    return [state["last"]], state  # predict last value for k=1
+
+# Use it standalone or in an ensemble:
+from skaters import envelope, precision_weighted_ensemble
+
+f = envelope(my_skater, k=1)
+f = precision_weighted_ensemble([my_skater, ema(alpha=0.1, k=1)], k=1)
+```
+
+## Design
+
+- **Online only** — O(1) per observation, no batch recomputation
+- **Prediction and uncertainty are separate** — skaters predict, envelopes estimate error
+- **Pure Python** — zero dependencies, runs anywhere Python runs
+- **Pyodide compatible** — works in the browser via WebAssembly
+
+## Lineage
+
+This package distills ideas from [timemachines](https://github.com/microprediction/timemachines), which provided a common skater interface for dozens of time series packages. This is a from-scratch rewrite focused on speed, simplicity, and browser compatibility.

skaters-0.1.0/README.md

@@ -0,0 +1,140 @@
+# skaters
+
+Fast univariate online time series models. Zero dependencies. Runs in [Pyodide](https://pyodide.org/).
+
+## Install
+
+```bash
+pip install skaters
+```
+
+## Quick start
+
+```python
+from skaters import ensemble, envelope
+
+# Create a precision-weighted ensemble of EMA models
+f = ensemble(k=3)  # predict 3 steps ahead
+
+state = None
+for y in observations:
+    x, state = f(y, state)
+    # x = [float, float, float]  (forecasts for horizons 1, 2, 3)
+
+# Want uncertainty bands? Wrap any skater with an envelope:
+f = envelope(ensemble(k=3), k=3)
+
+state = None
+for y in observations:
+    out, state = f(y, state)
+    # out["mean"] = point forecasts
+    # out["std"]  = empirical std of forecast error per horizon
+```
+
+## The skater convention
+
+A skater is any callable with this signature:
+
+```python
+x, state = f(y, state)
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `y` | `float` | New observation |
+| `state` | `dict \| None` | Prior state (`None` on first call) |
+| **Returns** | | |
+| `x` | `list[float]` | Point forecasts for horizons 1..k |
+| `state` | `dict` | Updated state (pass back next call) |
+
+Skaters only predict. Uncertainty is handled separately by the [envelope](#envelope).
+
+## Built-in skaters
+
+### EMA
+
+Exponential moving average. O(1) per observation.
+
+```python
+from skaters import ema
+
+f = ema(alpha=0.1, k=1)
+```
+
+### Convenience constructors
+
+Pre-configured EMA speeds:
+
+```python
+from skaters import rapidly, quickly, slowly, sluggishly
+
+f = rapidly(k=1)     # alpha=0.3
+f = quickly(k=1)     # alpha=0.1
+f = slowly(k=1)      # alpha=0.05
+f = sluggishly(k=1)  # alpha=0.01
+```
+
+### Precision-weighted ensemble
+
+Combines multiple skaters, weighting each by 1/MSE of its forecast errors. Automatically favors models that are both accurate and unbiased.
+
+```python
+from skaters import ensemble, precision_weighted_ensemble, ema
+
+# Default: ensemble of EMAs at different speeds
+f = ensemble(k=3)
+
+# Custom: bring your own skaters
+f = precision_weighted_ensemble(
+    skaters=[ema(alpha=0.05, k=3), ema(alpha=0.2, k=3)],
+    k=3,
+)
+```
+
+## Envelope
+
+The envelope wraps any skater and tracks empirical forecast errors at each horizon. It is model-independent — it doesn't care how the predictions are made.
+
+```python
+from skaters import envelope, ema
+
+# Welford's (uniform weight over all history)
+f = envelope(ema(alpha=0.1, k=3), k=3)
+
+# Exponentially weighted (forgets old errors, adapts to regime changes)
+f = envelope(ema(alpha=0.1, k=3), k=3, decay=0.95)
+
+state = None
+for y in observations:
+    out, state = f(y, state)
+    print(out["mean"], out["std"])
+```
+
+## Writing your own skater
+
+Any function matching the convention works:
+
+```python
+def my_skater(y: float, state: dict | None) -> tuple[list[float], dict]:
+    if state is None:
+        state = {"last": y}
+    state["last"] = y
+    return [state["last"]], state  # predict last value for k=1
+
+# Use it standalone or in an ensemble:
+from skaters import envelope, precision_weighted_ensemble
+
+f = envelope(my_skater, k=1)
+f = precision_weighted_ensemble([my_skater, ema(alpha=0.1, k=1)], k=1)
+```
+
+## Design
+
+- **Online only** — O(1) per observation, no batch recomputation
+- **Prediction and uncertainty are separate** — skaters predict, envelopes estimate error
+- **Pure Python** — zero dependencies, runs anywhere Python runs
+- **Pyodide compatible** — works in the browser via WebAssembly
+
+## Lineage
+
+This package distills ideas from [timemachines](https://github.com/microprediction/timemachines), which provided a common skater interface for dozens of time series packages. This is a from-scratch rewrite focused on speed, simplicity, and browser compatibility.

skaters-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "skaters"
+version = "0.1.0"
+description = "Fast univariate time series models that run in Pyodide"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Peter Cotton", email = "peter.cotton@microprediction.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

skaters-0.1.0/src/skaters/__init__.py

@@ -0,0 +1,23 @@
+"""Fast univariate online time series models that run in Pyodide."""
+
+from skaters.conventions import Skater
+from skaters.ema import ema
+from skaters.envelope import envelope
+from skaters.ensemble import precision_weighted_ensemble
+from skaters.api import (
+    quickly, slowly, sluggishly, rapidly,
+    ensemble, ensemble_with_envelope,
+)
+
+__all__ = [
+    "Skater",
+    "ema",
+    "envelope",
+    "precision_weighted_ensemble",
+    "quickly",
+    "slowly",
+    "sluggishly",
+    "rapidly",
+    "ensemble",
+    "ensemble_with_envelope",
+]

skaters-0.1.0/src/skaters/api.py

@@ -0,0 +1,43 @@
+"""Convenience constructors for common skater configurations."""
+
+from __future__ import annotations
+from skaters.ema import ema
+from skaters.ensemble import precision_weighted_ensemble
+from skaters.envelope import envelope
+
+
+def rapidly(k: int = 1):
+    """EMA with alpha=0.3 — reacts fast to changes."""
+    return ema(alpha=0.3, k=k)
+
+
+def quickly(k: int = 1):
+    """EMA with alpha=0.1 — moderate reactivity."""
+    return ema(alpha=0.1, k=k)
+
+
+def slowly(k: int = 1):
+    """EMA with alpha=0.05 — smooth, slow-moving."""
+    return ema(alpha=0.05, k=k)
+
+
+def sluggishly(k: int = 1):
+    """EMA with alpha=0.01 — very slow adaptation."""
+    return ema(alpha=0.01, k=k)
+
+
+def ensemble(k: int = 1):
+    """Precision-weighted ensemble of EMA models at different speeds."""
+    return precision_weighted_ensemble(
+        skaters=[rapidly(k), quickly(k), slowly(k), sluggishly(k)],
+        k=k,
+    )
+
+
+def ensemble_with_envelope(k: int = 1, decay: float | None = None):
+    """Precision-weighted ensemble wrapped with an empirical error envelope.
+
+    This is the recommended default — good predictions with calibrated
+    uncertainty bands.
+    """
+    return envelope(ensemble(k=k), k=k, decay=decay)

skaters-0.1.0/src/skaters/conventions.py

@@ -0,0 +1,23 @@
+"""Skater convention: an online univariate model is a callable:
+
+    x, state = f(y, state)
+
+where:
+    y:     float             - new observation
+    state: dict | None       - prior state (None on first call)
+    x:     list[float]       - point forecasts for horizons 1..k
+    state: dict              - updated state (pass back next call)
+
+Skaters only predict. Uncertainty estimation is handled separately
+by the Envelope (see envelope.py), which wraps any skater and tracks
+empirical forecast errors per horizon.
+"""
+
+from __future__ import annotations
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Skater(Protocol):
+    def __call__(self, y: float, state: dict | None) -> tuple[list[float], dict]:
+        ...

skaters-0.1.0/src/skaters/ema.py

@@ -0,0 +1,28 @@
+"""Exponential moving average skater.
+
+Pure online, O(1) per observation. Returns only point forecasts.
+"""
+
+from __future__ import annotations
+
+
+def ema(alpha: float = 0.05, k: int = 1):
+    """Create an EMA skater.
+
+    Args:
+        alpha: smoothing factor in (0,1). Small = slow, large = fast.
+        k: forecast horizon (number of steps ahead).
+
+    Returns:
+        A skater callable: (y, state) -> (list[float], state)
+    """
+    assert 0 < alpha < 1
+
+    def _skater(y: float, state: dict | None) -> tuple[list[float], dict]:
+        if state is None:
+            return [y] * k, {"level": y}
+        level = state["level"] + alpha * (y - state["level"])
+        return [level] * k, {"level": level}
+
+    _skater.__name__ = f"ema(alpha={alpha}, k={k})"
+    return _skater

skaters-0.1.0/src/skaters/ensemble.py

@@ -0,0 +1,74 @@
+"""Precision-weighted ensemble of skaters.
+
+Combines multiple online skaters by weighting inversely proportional
+to their empirical forecast variance. Each sub-model's errors are
+tracked internally via parade-style queues.
+
+The ensemble itself is a skater — it returns list[float] predictions.
+Wrap it with an envelope if you also want uncertainty bands.
+"""
+
+from __future__ import annotations
+import math
+from collections import deque
+from skaters.runstats import running_var_init, running_var_update, running_mse_get
+
+
+def precision_weighted_ensemble(skaters: list, k: int = 1, floor: float = 1e-6):
+    """Create a precision-weighted ensemble skater.
+
+    Args:
+        skaters: list of skater callables
+        k: forecast horizon
+        floor: minimum precision to prevent zero-weight
+
+    Returns:
+        A skater callable: (y, state) -> (list[float], state)
+    """
+    n = len(skaters)
+    assert n > 0
+
+    def _skater(y: float, state: dict | None) -> tuple[list[float], dict]:
+        if state is None:
+            state = {
+                "sub": [None] * n,
+                "queues": [[deque() for _ in range(k)] for _ in range(n)],
+                "stats": [[running_var_init() for _ in range(k)] for _ in range(n)],
+            }
+
+        # Run all sub-models and collect predictions
+        preds = []
+        for i, f in enumerate(skaters):
+            x_i, state["sub"][i] = f(y, state["sub"][i])
+            preds.append(x_i)
+
+        # Resolve pending predictions and update error stats
+        for i in range(n):
+            for h in range(k):
+                q = state["queues"][i][h]
+                if q:
+                    error = y - q.popleft()
+                    state["stats"][i][h] = running_var_update(state["stats"][i][h], error)
+                state["queues"][i][h].append(preds[i][h])
+
+        # Precision-weighted combination per horizon (weight by 1/MSE)
+        combined = []
+        for h in range(k):
+            weights = []
+            for i in range(n):
+                mse = running_mse_get(state["stats"][i][h])
+                if math.isfinite(mse) and mse > 0:
+                    w = 1.0 / mse
+                else:
+                    w = floor
+                weights.append(max(w, floor))
+
+            w_total = sum(weights)
+            combined.append(
+                sum(w * preds[i][h] for i, w in enumerate(weights)) / w_total
+            )
+
+        return combined, state
+
+    _skater.__name__ = f"precision_weighted_ensemble(n={n}, k={k})"
+    return _skater

skaters-0.1.0/src/skaters/envelope.py

@@ -0,0 +1,88 @@
+"""Model-independent empirical prediction envelope.
+
+Wraps any skater and tracks forecast errors at each horizon using
+online statistics. Provides regularized std estimates that can be
+used as confidence bands.
+
+The envelope is the sole source of uncertainty — skaters just predict.
+"""
+
+from __future__ import annotations
+import math
+from collections import deque
+from skaters.runstats import running_var_init, running_var_update, running_std_get
+
+
+def envelope(skater, k: int = 1, decay: float | None = None):
+    """Wrap a skater with an empirical error envelope.
+
+    Args:
+        skater: any skater callable (y, state) -> (list[float], state)
+        k: forecast horizon (must match the skater's k)
+        decay: if set, use exponentially weighted variance with this
+               decay factor (0 < decay < 1, smaller = faster forgetting).
+               If None, use Welford's (uniform weighting over all history).
+
+    Returns:
+        A callable: (y, state) -> (x_dict, state) where x_dict contains
+        "mean" (point forecasts) and "std" (empirical error std per horizon).
+    """
+
+    def _enveloped(y: float, state: dict | None) -> tuple[dict, dict]:
+        if state is None:
+            state = {
+                "inner": None,
+                "queues": [deque() for _ in range(k)],
+                "error_stats": [running_var_init() for _ in range(k)],
+            }
+            if decay is not None:
+                state["ew_var"] = [{"mean": 0.0, "var": 0.0, "n": 0} for _ in range(k)]
+
+        # Run the inner skater
+        x, state["inner"] = skater(y, state["inner"])
+
+        # Resolve pending predictions against this observation
+        queues = state["queues"]
+        error_stats = state["error_stats"]
+        for h in range(k):
+            if queues[h]:
+                predicted = queues[h].popleft()
+                error = y - predicted
+                if decay is not None:
+                    _ew_update(state["ew_var"][h], error, decay)
+                else:
+                    error_stats[h] = running_var_update(error_stats[h], error)
+
+        # Enqueue new predictions
+        for h in range(k):
+            queues[h].append(x[h])
+
+        # Compute std
+        if decay is not None:
+            std = [_ew_std(state["ew_var"][h]) for h in range(k)]
+        else:
+            std = [running_std_get(s) for s in error_stats]
+
+        return {"mean": x, "std": std}, state
+
+    _enveloped.__name__ = f"envelope({getattr(skater, '__name__', '?')})"
+    return _enveloped
+
+
+def _ew_update(ew: dict, x: float, decay: float) -> None:
+    """Exponentially weighted online variance update (in-place)."""
+    ew["n"] += 1
+    if ew["n"] == 1:
+        ew["mean"] = x
+        ew["var"] = 0.0
+        return
+    diff = x - ew["mean"]
+    ew["mean"] = decay * ew["mean"] + (1 - decay) * x
+    ew["var"] = decay * (ew["var"] + (1 - decay) * diff * diff)
+
+
+def _ew_std(ew: dict) -> float:
+    """Get std from exponentially weighted state."""
+    if ew["n"] < 2:
+        return float("inf")
+    return math.sqrt(ew["var"]) if ew["var"] > 0 else float("inf")

skaters-0.1.0/src/skaters/parade.py

@@ -0,0 +1,53 @@
+"""Parade: track forecast errors at each horizon incrementally.
+
+A "parade" maintains k queues of pending predictions. When a new
+observation arrives, it resolves the oldest prediction at each horizon,
+computes the error, and updates running statistics.
+"""
+
+from __future__ import annotations
+from collections import deque
+from skaters.runstats import running_var_init, running_var_update, running_std_get
+
+
+def parade_init(k: int) -> dict:
+    """Initialize parade state for k horizons."""
+    return {
+        "k": k,
+        "queues": [deque() for _ in range(k)],
+        "error_stats": [running_var_init() for _ in range(k)],
+    }
+
+
+def parade_update(state: dict, x: list[float], y: float) -> dict:
+    """Record new predictions x[0..k-1] and resolve against observation y.
+
+    Args:
+        state: parade state
+        x: predictions for horizons 1..k
+        y: the observation that just arrived
+
+    Returns:
+        updated state (std available via parade_std)
+    """
+    k = state["k"]
+    queues = state["queues"]
+    error_stats = state["error_stats"]
+
+    # Resolve: the observation y was predicted h steps ago by queue[h]
+    for h in range(k):
+        if queues[h]:
+            predicted = queues[h].popleft()
+            error = y - predicted
+            error_stats[h] = running_var_update(error_stats[h], error)
+
+    # Enqueue new predictions
+    for h in range(k):
+        queues[h].append(x[h])
+
+    return state
+
+
+def parade_std(state: dict) -> list[float]:
+    """Return current std estimate at each horizon."""
+    return [running_std_get(s) for s in state["error_stats"]]

skaters-0.1.0/src/skaters/runstats.py

@@ -0,0 +1,48 @@
+"""Lightweight online running statistics (pure Python, no dependencies).
+
+Welford's algorithm for mean/variance, plus exponentially weighted variants.
+"""
+
+from __future__ import annotations
+import math
+
+
+def running_var_init() -> dict:
+    """Initialize state for Welford's online variance."""
+    return {"n": 0, "mean": 0.0, "m2": 0.0}
+
+
+def running_var_update(state: dict, x: float) -> dict:
+    """Update running mean/variance with a new observation (Welford)."""
+    n = state["n"] + 1
+    delta = x - state["mean"]
+    mean = state["mean"] + delta / n
+    delta2 = x - mean
+    m2 = state["m2"] + delta * delta2
+    return {"n": n, "mean": mean, "m2": m2}
+
+
+def running_var_get(state: dict) -> tuple[float, float]:
+    """Return (mean, variance) from running stats state."""
+    if state["n"] < 2:
+        return state["mean"], float("inf")
+    return state["mean"], state["m2"] / (state["n"] - 1)
+
+
+def running_std_get(state: dict) -> float:
+    """Return standard deviation from running stats state."""
+    _, var = running_var_get(state)
+    return math.sqrt(var) if math.isfinite(var) else float("inf")
+
+
+def running_mse_get(state: dict) -> float:
+    """Return mean squared error (second moment) from running stats of errors.
+
+    MSE = bias² + variance, so it penalizes both systematic and random error.
+    """
+    if state["n"] < 1:
+        return float("inf")
+    mean, var = running_var_get(state)
+    if not math.isfinite(var):
+        return float("inf")
+    return mean * mean + var