Skip to main content

​
TSIGenerator

Bases: BaseGenerator Generate series by composing randomized Trend, Seasonality and Irregularity components. The component-based construction is based on Bahrpeyma et al. (2021), “A Methodology for Validating Diversity in Synthetic Time Series Generation,” https://doi.org/10.1016/j.mex.2021.101459. SynForecast’s component families, sampling distributions, and stability guards are its own extensions rather than a reproduction of that paper’s generator. Every series draws a fresh random configuration: a trend type from trend_types, 0-3 seasonal harmonics with periods from seasonal_periods (integer and non-integer, so multiple harmonics are incommensurate), and an irregular (noise) process from irregular_types. The components are combined additively, or multiplicatively with probability multiplicative_prob when the trend base can be kept positive:
where c caps the relative seasonal swing so the factor stays positive. Trend shapes are normalized so their total movement over the series is drawn from trend_slope_range regardless of length; harmonic amplitudes are log-uniform; the noise scale is a log-uniform fraction of the structural signal’s standard deviation, so the pool spans signal-dominated through noise-dominated series. A per-series level and log-uniform scale spread series across magnitudes. Degenerate or exploding draws (non-finite, |y| >= 1e8, or constant) are redrawn a bounded number of times. Parameters:

​
TSIGenerator.generate_single_series

Generate values for a single TSI-composed time series. Parameters: Returns:

​
TCMGenerator

Bases: BaseGenerator Generate series from a random temporal structural causal model (SCM). Each series gets a freshly sampled SCM over n_vars latent variables: a sparse dependency graph over the (variable x lag) space is drawn, each edge is assigned a random edge function, and the system is rolled out autoregressively. Node i evolves as
with per-edge functions f_e(x) in
The temporal-SCM framing follows the overview in Runge et al. (2023), “Causal inference for time series,” https://doi.org/10.1038/s43017-023-00431-y. The particular graph sampler, edge-function mixture, stability rescaling, and guards here are original SynForecast design choices; this is not a reproduction of a named TCM generator from that paper or from Chronos-2. where x' is a second randomly-paired parent (product interaction) and tau a random threshold. Saturating kinds carry a log-uniform softness scale s and contribute c*s*tanh(x/s) (slope c near 0, bounded output). The returned univariate series is node 0 (nodes are exchangeable by construction); the remaining nodes act as latent parents, i.e. realistic exogenous-looking drivers. This produces genuine causal temporal structure — autocorrelation at sampled lags, lead-lag effects, nonlinear/regime-like dynamics — that component mixing cannot. Diversity is shaped per series: edge kinds follow a random Dirichlet mixture over edge_kinds (some series linear-dominated, others nonlinearity-dominated), coefficient magnitudes decay geometrically with lag (short-lag dominance), and, when ‘linear’ is in the pool, every node gets a positive linear self lag-1 edge so the observed node carries its own persistence. Stability: the linear-gain part (linear/tanh/relu edges) is assembled into VAR companion form and its coefficients are rescaled toward a per-series spectral-radius target below stability_margin — drawn near the margin with probability 0.22 (persistent, spectrally peaked series) and well below it otherwise (noise-like series); bounded-output edges cannot destabilize the core and keep their coefficients. During rollout every state is additionally soft-clamped via clamp * tanh(x / clamp) so nonlinear feedback cannot diverge. If a trajectory still fails the finiteness/scale guard, the SCM is redrawn (up to 5 times), then a guaranteed-stable linear AR(1) is used. The counters _redraw_total / _fallback_total and the last accepted SCM _last_scm are exposed for introspection on direct generate_single_series calls. Multivariate mode: with multivariate=True, generate(n_series) samples a single SCM (with at least n_series variables — the lower bound of n_vars_range is clamped up as needed) and one shared length, rolls the system out once, and returns the first n_series nodes as separate series in the long-format output (one unique_id per node, following VARGenerator). Because the nodes share one causal graph, they are genuinely cross-dependent at the sampled lags. The default multivariate=False keeps the univariate behavior: n_series independent SCMs, one observed node each. Parameters:

​
TCMGenerator.generate_single_series

Generate values for a single TCM series. Samples a fresh random SCM, rolls it out (with burn-in), and returns the target node. Redraws the SCM on guard failure, falling back to a stable linear AR(1) after _MAX_REDRAWS redraws. Parameters: Returns:

​
TCMGenerator.generate

Generate n_series time series from temporal causal models. With multivariate=False (default) this is the base behavior: n_series independent SCMs, one observed node each. With multivariate=True the n_series series are the first n_series nodes of one shared SCM, sharing a single length (following VARGenerator); generation is inherently joint, so n_jobs has no effect in that mode. Parameters: Returns:

​
KernelSynthGenerator

Bases: BaseGenerator Generate series by sampling from randomly composed Gaussian-process kernels. This adapts the KernelSynth recipe introduced for pretraining the Chronos forecasting models (Ansari et al. 2024, “Chronos: Learning the Language of Time Series”, https://arxiv.org/abs/2403.07815) and its Apache-2.0-licensed reference implementation (https://github.com/amazon-science/chronos-forecasting/blob/main/scripts/kernel-synth.py). For each series the generator draws 1..max_kernels base kernels (with replacement) from a fixed bank, folds them together with randomly chosen binary operators (+ or *), and samples one path from the resulting GP prior on the normalized grid x = linspace(0, 1, length). Kernel addition mixes behaviors (e.g. trend + seasonality); kernel multiplication modulates them (e.g. locally periodic, amplitude-varying seasonality). SynForecast makes the bank configurable, expresses seasonal periods in time steps on a normalized grid, and adds bounded retries, divergence guards, and optional standardization. Base kernels (r = |x_i - x_j|, all on the normalized grid):
  • rbf: exp(-r^2 / (2 l^2)) — smooth, length-scale l
  • rational_quadratic: (1 + r^2 / (2 a))^(-a) — scale mixture of RBFs, shape a
  • periodic (ExpSineSquared): exp(-2 sin^2(pi r / p_norm)) with p_norm = period / length so period is expressed in time steps
  • linear (DotProduct): s^2 + x_i x_j — trend / drift
  • white: w on the diagonal — independent noise
  • constant: a constant offset
Because a composed kernel can be near-degenerate or produce an exploding scale, non-finite, near-constant, or |y| >= 1e8 draws are redrawn a bounded number of times before falling back to Gaussian noise. Parameters:

​
KernelSynthGenerator.generate_single_series

Generate one KernelSynth series. Parameters: Returns: