# new_generator — compositional SARIMA-backbone cascade generator

A self-contained cascade data generator that uses a **SARIMA(p,d,q)(P,D,Q)_s**
process as its dynamical backbone and layers the ingredients that modern
synthetic-data priors for time-series foundation models rely on. A pure SARIMA
corpus is classic but *narrow* (linear, near-Gaussian, stationary bar the
integration); this generator keeps SARIMA's well-behaved, guaranteed-stationary
recursion as the core and enriches it toward the SOTA recipe.

## What's inside

| file | purpose |
|------|---------|
| `generator.py` | `class Generator(DataGenerator)` — the entrypoint |
| `config.json` | length band, SARIMA order caps, enrichment probabilities |
| `requirements.txt` | hash-locked, allowlisted deps (`numpy`, `scipy`) |

## The recipe

**SARIMA backbone.** Each segment is a draw from `SARIMA(p,d,q)(P,D,Q)_s`:
`(p,q)` non-seasonal AR/MA, `d` integration (stochastic trends), `(P,D,Q)_s`
seasonal terms coupling seasonality with autocorrelation.

**SOTA enrichments layered on top:**

1. **Regime switching** — a series is 1–3 concatenated segments, each its own
   SARIMA parameterisation, stitched with level continuity → structural breaks in
   dynamics a single stationary ARMA can't produce.
2. **Stochastic volatility** — innovations are modulated by an AR(1) log-variance
   process (vectorised) → volatility *clustering*, on top of Gaussian or Student-t
   (fat-tailed) shocks.
3. **Compositional components** — additive nested-calendar seasonality, smooth
   trends, structural level shifts and sparse spikes/outliers, each scaled
   relative to the core (KernelSynth-style composition).
4. **Nonlinear warps** — optional invertible transform (asinh tail-compression,
   exp/softplus positivity, signed power) → non-Gaussian / positive /
   multiplicative marginals, like real demand, price and count series.
5. **TSMixup** — with some probability two independent draws are convex-combined
   (the Chronos augmentation), broadening the corpus beyond any single prior.

## Why this is stronger than plain SARIMA

Plain SARIMA teaches a narrow, linear-Gaussian forecaster. The enrichments add
exactly the dynamics the leading TSFM synthetic priors exploit and that real
held-out series exhibit — regime breaks, volatility clustering, fat tails,
non-Gaussian/positive marginals, compositional multi-scale structure, and mixed
series. It is *not* a claim of a leaderboard win (SOTA is empirical — measure it
with `cascade score`), but the prior now spans the space those recipes cover.

## Stability & determinism

AR/MA coefficients (regular and seasonal) are drawn as reflection coefficients in
`(-1, 1)` and mapped to lag polynomials by **Levinson-Durbin**, guaranteeing all
roots outside the unit circle → the `scipy.signal.lfilter` recursion never
diverges. Integration is de-meaned first; warp exponents are clipped; each series
is rescaled to a sampled target scale and hard-clipped to `max_abs_value`.
Everything is **fully vectorised** (no per-timestep Python loops), so generation
is linear-time and CPU-only. The corpus is a pure function of `(seed, n_series)`
via `np.random.SeedSequence` sub-seeds — no `hash()`, wall-clock, or unseeded RNG.

## Verify

```bash
# from the cascade repo root, with deps installed and cascade importable
cascade verify ../new_generator
```

## Config knobs (`config.json`)

- `min_length` / `max_length` — per-series length band.
- `max_ar` / `max_ma` / `max_seasonal_ar` / `max_seasonal_ma` — SARIMA order caps.
- `d_weights` / `seasonal_d_weights` — integration-order probability mass.
- `seasonal_prob` — probability a series carries seasonal structure.
- `student_t_prob` / `stoch_vol_prob` — fat-tailed / volatility-clustered innovations.
- `regime_prob` / `max_regimes` — regime-switching frequency and segment count.
- `trend_prob` / `calendar_prob` / `level_shift_prob` / `spike_prob` — additive components.
- `warp_prob` — probability of a nonlinear marginal warp.
- `mixup_prob` — probability of TSMixup convex combination.
- `standardize` — z-normalise each series (default `false`).
- `max_abs_value` — hard magnitude clip to keep output trainer-safe finite.