| # 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. |
|
|
