warp_regression

KO | EN

gitlite — search

#javascript #ai #llm #machine-learning #rust #java #cli #vue #pytorch #security #mcp #ios #openai #open-source

warp_regression

(★ 13)

Warp Regression module for Pytorch

warp_regression 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# warp_regression

Likelihood-based time warping for regression and forecasting — for **cyclical** series with irregular phase, and for response shapes whose *duration* wanders (e.g. adstocked media effects).

Longer motivation write-up: [`blog_post.md`](blog_post.md).

---

## What is this?

Most of machine learning clings to **y-axis** error. Real life talks in time errors all the time — a train ten minutes late, a parcel a day after the window. Errors-in-variables already puts noise on inputs; this package asks whether **time** error can sit in a regression model explicitly, instead of being dumped into the residual on $y$.

That matters for warped or cyclical series (irregular phase — not the same as seasonality). Dynamic time warping is common, but it is mostly pattern matching: it does not easily give you regression, inference, or forecasts of future timing. The approach here is a **generative** warp. An input series $x$ is deformed by slow expansions and contractions; we score that deformation with its own likelihood (**terror** = *t*iming *error*), and fit it jointly with ordinary observation error.

At each index $i$,

$$
\hat{y}_i = f\big(\mathrm{warp}(x, p)_i\big).
$$

$x$ is a covariate (often a sine or other known shape), $p$ is a low-dimensional path of fractional indices into $x$, and $f$ is whatever readout you want — linear, MLP, trend + cycle, …. Soft-warp is ordinary differentiable linear interpolation at those indices (same family as spatial transformers / `grid_sample`; not invented here). What *is* specific is scoring the path with a generative terror likelihood and fitting it jointly with the observation model.

![Soft-warp aligning a sine covariate to a warped target series](https://raw.githubusercontent.com/aaron1rcl/warp_regression/main/docs/warp_series_example.png)

*Notebook 0 style: without the path, $x$ and $y$ look unrelated; with the right $p$, they line up.*

### Terror and the dual loss

Timing is modelled as a Gaussian random walk on path offsets — not the only option, but a simple generative way to drift early and late, with scale $\sigma_t$. A free walk at every index is infeasible (jagged, one parameter per observation), so the fitted path is piecewise linear through $K \ll n$ knots. Terror is the **expected log-likelihood of a Brownian bridge** on each knot segment: $O(K)$, autograd-friendly, and still tied to the RW story used for forecast path sampling.

Maths write-up: [Expectation of a Gaussian Likelihood Function](https://aaron-pickering.com/2023/12/10/expectation-of-gaussian-likelihood-function/). Code: [`expected_likelihood_torch`](src/warp_regression/core/training.py), [`expected_likelihood`](src/warp_regression/core/bayesian_jax.py) (JAX).

![Random-walk offsets with piecewise-linear path and Brownian bridges between knots](https://raw.githubusercontent.com/aaron1rcl/warp_regression/main/docs/terror_rw_pwl.png)

*Terror story: RW on timing offsets, low-dimensional PWL path, bridges between knots.*

Training mixes the two likelihoods with weight $\lambda$:

$$
\mathcal{J} = \lambda \cdot (-\log p(y \mid \hat{y},\sigma_y)) - (1-\lambda)\cdot \log p(p \mid \sigma_t).
$$

At $\lambda = 0.5$ neither term is preferred *a priori*. Toward 1 you mostly fit $y$; toward 0, terror takes over.

![Dual loss: observation error and terror on path offsets](https://raw.githubusercontent.com/aaron1rcl/warp_regression/main/docs/dual_loss.png)

*Error on the left ($\sigma_y$), terror on the right ($\sigma_t$). Same $\lambda$ mixes them.*

Because timing has its own scale, forecasts can continue the warp as a random walk and build terror bands (timing only), error bands (observation noise), and combined bands (both). That is also how you get a distribution over *next cycle length*, not only next height.

Seasonality resets every January. A business cycle, a predator–prey boom, or Bitcoin’s rough four-year rhythm can run long or short: the shape recurs; the clock slips. Packaged tooling rarely gives warping, regression/inference, cycle-length uncertainty, and path-sampled forecasts in one place. GPs, state-space models, DTW, and neural warps each cover pieces; the full checklist usually means a custom research stack. Short survey: [`legacy/info/comparable_methods.md`](legacy/info/comparable_methods.md).

**Use it** for irregular cycles or warped response shapes on regular, small-to-medium series where you care about *when* as much as *what*. **Skip it** for pure seasonal series, irregular timestamps, or when there is no shape worth warping.

---

## Install

```bash
pip install -e ".[dev]"
# optional: fully Bayesian notebook (PyMC + JAX / NumPyro)
pip install -e ".[bayes]"
```

## Quick start

Start with [`0_Warp_Block_Basics.ipynb`](examples/notebooks/0_Warp_Block_Basics.ipynb): a portable `WarpPath` + `WarpRegression` block in ordinary PyTorch, recovering a known expanding warp of a sine (error-only loss; dual / terror comes in notebook 1).

```python
import torch
import torch.nn as nn
from warp_regression import WarpPath, WarpRegression

n, n_knots = 100, 8
path = WarpPath(n, n_knots, path_anchor="start")
warp = WarpRegression(path, covariate_kind="array", name="x")

A = nn.Parameter(torch.tensor(1.0))
C = nn.Parameter(torch.tensor(0.0))

x = torch.sin(2 * torch.pi * torch.arange(n) / n)
p = path.path()                 # identity at init (B = 0)
y_hat = A * warp.warp(x, p) + C
```

For YAML models, dual loss, forecast bands, Bayesian sampling, and pinned / masked MMM-style warps, see notebooks 1–5 and `WarpModel.from_yaml(...)`.

---

## Examples

Same dual idea in different settings — shape on $x$, timing on $p$:

![Four example settings](https://raw.githubusercontent.com/aaron1rcl/warp_regression/main/docs/use_cases_4panel.png)

| Notebook | What it covers |
|----------|----------------|
| [`0_Warp_Block_Basics.ipynb`](examples/notebooks/0_Warp_Block_Basics.ipynb) | Portable `WarpPath` / `WarpRegression`; recover a known expanding warp (error-only) |
| [`1_Introduction_to_Warp_Regression.ipynb`](examples/notebooks/1_Introduction_to_Warp_Regression.ipynb) | End-to-end `WarpModel` on a synthetic sine: prefit, dual fit, path recovery, forecast bands |
| [`2_Adding_complexity_Lynx_Forecast.ipynb`](examples/notebooks/2_Adding_complexity_Lynx_Forecast.ipynb) | Hudson Bay lynx: ~10y + ~38y inputs, shared warp, nonlinear maps, holdout forecast |
| [`3_Bitcoin_Warp.ipynb`](examples/notebooks/3_Bitcoin_Warp.ipynb) | Daily BTC: log-trend + envelope sine, cycle timing, out-of-sample bands |
| [`4_Fully_Bayesian.ipynb`](examples/notebooks/4_Fully_Bayesian.ipynb) | Fully Bayesian dual model (PyMC + JAX / NumPyro): posteriors on $A$, $C$, path, and scales |
| [`5_Marketing_Mix_Model_Warped_Effects.ipynb`](examples/notebooks/5_Marketing_Mix_Model_Warped_Effects.ipynb) | MMM-style: sparse spend → adstock → pinned warp; Bayesian $A_m$ / path / $\sigma_t$; effect-length bridges |

![Five-year Bitcoin forecast](https://raw.githubusercontent.com/aaron1rcl/warp_regression/main/docs/bitcoin_5yr_forecast.png)

*Bitcoin five-year ahead (notebook 3): timing uncertainty is part of the product, not an afterthought.*

HTML under [`examples/html/`](examples/html/). Configs in [`examples/models/`](examples/models/). Motivation: [`blog_post.md`](blog_post.md).

---

## Package

| Piece | Role |
|-------|------|
| `WarpPath` / `WarpRegression` | Portable warp block |
| `WarpModel` | Paths, blocks, observation $f$, dual fit, forecast |
| `recipes` | Declarative configs (e.g. `lynx_dual_map_config`) |
| `observation` | Term kinds for $f$ |
| `forecast` | Path continuation and bands |
| `prefit` | Covariates (e.g. sine) before `fit` |
| `core` | Soft-warp, path geometry (incl. multi-pin bridges), dual / terror loss |
| `covariates` | Sine helpers; sparse / MMM utilities (`geometric_adstock`, `pulse_start_indices`, terror masks) |

```
examples/notebooks/   tutorials
examples/html/        static HTML renders
examples/models/      YAML configs
src/warp_regression/  package
src/data/             lynx.csv, bitcoin_daily.csv
src/tests/            pytest
legacy/               archived notes (not imported)
```

```python
from warp_regression import WarpModel, WarpPath, WarpRegression
from warp_regression import as_forecast_state, forecast_from_state, build_forecast_bands
from warp_regression import prefit, analyze_cycle_lengths
```

---

## Develop

```bash
pytest src/tests/ -v
pytest src/tests/ -v -m slow   # full Bitcoin reproduction

jupyter nbconvert --execute --to notebook --inplace examples/notebooks/*.ipynb
jupyter nbconvert --to html examples/notebooks/*.ipynb --output-dir examples/html/
```

warp_regression

warp_regression 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

warp_regression

warp_regression 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README