skaters

Guide

How the pieces fit: the Dist object, transforms, conjugation, and ensembles — everything returns a distribution, everything composes.

Architecture: transforms all the way down

Every model in skaters is a chain of bijective transforms with a distributional leaf at the bottom:

$y \;\xrightarrow{T_1}\; y' \;\xrightarrow{T_2}\; y'' \;\xrightarrow{\cdots}\; \text{leaf} \;\rightarrow\; \hat{D}$

The leaf estimates $\hat{D} = \mathcal{N}(0, \hat\sigma^2)$ from residuals via Welford's algorithm. Predictions in the original space come from inverting the transform chain: $\hat{D}_{\text{original}} = T_1^{-1}\bigl(T_2^{-1}\bigl(\cdots(\hat{D})\bigr)\bigr).$

Every node returns a list[Dist]. There is no separate “point forecast” vs “uncertainty” — both are aspects of the same $\hat{D}$. An EMA doesn't “predict”; it strips off a running level $\ell_t$, leaving simpler residuals $\varepsilon_t = y_t - \ell_t$, and the prediction is whatever the leaf's estimate becomes when run back through the inverse.

Transforms

TransformForwardUse case
ema_transform(α)$y'_t = y_t - \ell_t$Remove level
difference()$y'_t = y_t - y_{t-1}$Random walk
drift(α, λ)$y'_t = \Delta y_t - \hat\mu_t$Random walk + drift
holt_linear(α, β)$y'_t = y_t - (\ell_t + b_t)$Level + trend (Holt 1957)
ar(p)$y'_t = y_t - \sum \hat\phi_j y_{t-j}$Autoregression (online RLS)
fractional_difference(d)$y'_t = (1-B)^d y_t$Long memory
standardize(α)$y'_t = (y_t - \hat\mu_t)/\hat\sigma_t$Remove scale
garch(ω, α, β)$y'_t = y_t / \hat\sigma_t$Volatility clustering
seasonal_difference(s)$y'_t = y_t - y_{t-s}$Periodicity
yeo_johnson(λ)signed Box–Cox coordinateLearn the coordinate (log / root / linear)

Conjugation

Transforms compose via conjugation. Given a transform $T$ and a skater $f$, $f_{\text{conj}}(y) = T^{-1}\bigl(f\bigl(T(y)\bigr)\bigr).$ The whole predictive distribution is mapped back through the inverse, so multi-step uncertainty accumulates correctly and the coordinate choice is handled coherently rather than by a biased point back-transform. 

from skaters import conjugate, ema, difference, standardize

# diff removes trend, then EMA predicts the differenced series
f = conjugate(ema(alpha=0.1, k=3), difference(), k=3)

# Chain: standardize, then difference, then EMA
f = conjugate(
    conjugate(ema(alpha=0.1, k=3), difference(), k=3),
    standardize(),
    k=3,
)
# canonical name: std|diff|ema_t|leaf

Ensembles

Precision-weighted (MSE)

Weights by $w_i \propto 1/\text{MSE}_i$ where $\text{MSE} = \text{bias}^2 + \text{variance}$.

from skaters import precision_weighted_ensemble, ema

f = precision_weighted_ensemble([
    ema(alpha=0.05, k=1),
    ema(alpha=0.2, k=1),
], k=1)

Bayesian (log-likelihood with XGBoost-inspired regularisation)

Each model accumulates a log-weight updated at every observation: $\log w_i \mathrel{+}= \eta \cdot \log p_i(y_t) - \lambda \cdot d_i,$ where $\eta$ is the learning rate (shrinkage), $\lambda$ is the complexity penalty, and $d_i$ is the model's depth. Predictions are combined via Dist.combine with softmax weights. 

from skaters import bayesian_ensemble, ema

f = bayesian_ensemble(
    [ema(alpha=0.05, k=1), ema(alpha=0.2, k=1)],
    k=1,
    learning_rate=0.5,       # eta: prevents over-concentrating
    complexity_penalty=0.02, # lambda: penalises deeper chains
    depths=[1, 1],
)

Adaptive search

Beam search over the transform grammar. Grows the candidate population online: expand top performers with new transforms, replay recent history to warm-start, prune losers.

from skaters import search

f = search(
    k=1,
    expand_interval=100,   # expand top performers every 100 obs
    max_depth=3,           # max transform chain depth
    replay_buffer=500,     # warm-start new candidates on recent history
    max_pool=30,
)

Design