Generation and Composition

Convenience APIs, generator pools, and multivariate composition

generate_series

generate_series(n_series, freq='D', min_length=50, max_length=500, generators=None, engine='pandas', seed=0, with_generator_col=False)

Generate a synthetic panel of time series.

Series are drawn from the interpretable pool of generators covering diverse temporal behaviors (or from generators when provided) and returned in long format, mirroring utilsforecast.data.generate_series.

Series are spread evenly across the generator list from the front, so when n_series is smaller than the pool only the first n_series generators contribute. The default pool is ordered round-robin across its behavioral niches, so a small panel still spans distinct behaviors: the first 15 generators cover all 15 niches.

Parameters:

Name	Type	Description	Default
n_series	int	Number of series to generate.	required
freq	str | int	Frequency of the data, as a pandas offset alias (e.g. ‘D’, ‘h’, ‘5min’, ‘MS’) or an integer for an integer time index. Defaults to ‘D’.	‘D’
min_length	int	Minimum length of each series. Defaults to 50.	50
max_length	int	Maximum length of each series. Defaults to 500.	500
generators	list[BaseGenerator]	Generators to draw from. Defaults to synforecast.interpretable_pool. Ignores min_length / max_length / freq / engine / seed when provided.	None
engine	str	Output dataframe library. Defaults to ‘pandas’.	‘pandas’
seed	int	Random seed. Defaults to 0.	0
with_generator_col	bool	When True, add a generator column with the alias of the generator that produced each series. Defaults to False.	False

Returns:

Type	Description
IntoDataFrame	DataFrame in long format with columns [unique_id, ds, y], plus generator when with_generator_col is True.

interpretable_pool

interpretable_pool(min_length=200, max_length=200, freq='D', seed=42, seasonal_period=None, **base_kwargs)

Create a pool of interpretable single-mechanism generators.

Returns 42 pre-configured generator instances across 15 behavioral niches, with allocation proportional to each generator’s behavioral range, so no domain dominates. Every instance is one named data-generating process; the meta-generators that randomize their own composition per series are left to :func:pretraining_pool. Until version 0.2 this function was called balanced_pool; that name remains available as a deprecated alias.

The list is ordered round-robin across the niches (one variant of every niche, then second variants, and so on), so any prefix spans as many distinct behaviors as possible: the first 15 entries cover all 15 niches. Consumers that use only the first k generators — such as generate_series with n_series < 42 — therefore still get a behaviorally diverse panel.

The seasonal variants (seasonal SARIMA, Holt-Winters ETS, seasonal intermittent demand and the periodic Gaussian process) share one seasonal period, which also sets the mean period of the two cyclic variants. Unless seasonal_period is given it is derived from freq as the number of steps in the next-larger calendar cycle: hourly data gets 24, daily 7, business-daily 5, weekly 52, monthly 12, quarterly 4, and multiples divide accordingly ("15min" gives 4, "2h" gives 12). Integer frequencies and offsets without a calendar convention fall back to 12. Yearly data has no sub-annual cycle, so its period is 1 and the seasonal variants reduce to their non-seasonal counterparts.

Parameters:

Name	Type	Description	Default
min_length	int	Minimum time series length for all generators.	200
max_length	int	Maximum time series length for all generators.	200
freq	str | int	Frequency for all generators, as a pandas offset alias or integer.	‘D’
seed	int | None	Base random seed. Each generator gets seed + i for reproducibility. Set to None for random seeds.	42
seasonal_period	int | None	Seasonal period, in time steps, for the seasonal variants. Defaults to None, which derives it from freq.	None
**base_kwargs	Any	Additional keyword arguments passed to all generators (e.g., engine, id_col, time_col, target_col).	{}

Returns:

Type	Description
list[BaseGenerator]	List of 42 BaseGenerator instances ready for use with SynSet.

Examples:

>>> from synforecast import SynSet, interpretable_pool
>>> dataset = SynSet(
...     interpretable_pool(min_length=100, max_length=100, freq="D")
... )
>>> df = dataset.generate(n_series_per_generator=1)

balanced_pool

balanced_pool(*args, **kwargs)

Deprecated alias of :func:interpretable_pool.

The pool is balanced across behavioral niches, but so is :func:pretraining_pool; the distinguishing property is that every instance is an interpretable single-mechanism process. Use :func:interpretable_pool. This alias warns and will be removed in a future release.

pretraining_pool

pretraining_pool(min_length=256, max_length=1024, freq='D', seed=42, include_interpretable=True, n_meta_variants=3, seasonal_period=None, include_seasonal=False, **base_kwargs)

Create a breadth-maximizing pool for foundation-model pretraining.

This is the pretraining-oriented counterpart to :func:interpretable_pool. It adds the diversity-targeted meta-generators that interpretable_pool deliberately excludes — TSIGenerator (randomized trend/seasonal/ irregular composition), TCMGenerator (random temporal causal graphs), KernelSynthGenerator (samples from randomly composed GP kernels), and MARGenerator (GRATIS-style mixtures of autoregressive components). Each resamples a fresh configuration per series, so a handful of instances spans a very wide distribution. By default it also includes the full interpretable_pool so the corpus carries interpretable single-mechanism behaviors alongside the meta-generators.

Unlike interpretable_pool, the default length range is wide (256-1024 steps), matching the longer contexts typical of pretraining.

Parameters:

Name	Type	Description	Default
min_length	int	Minimum series length for all generators.	256
max_length	int	Maximum series length for all generators.	1024
freq	str | int	Frequency for all generators, as a pandas offset alias or integer.	‘D’
seed	int | None	Base random seed. Each generator gets a distinct offset. Set to None for random seeds.	42
include_interpretable	bool	When True (default), prepend the full :func:interpretable_pool; when False, return only the meta-generators (a purely procedural pretraining corpus), plus the seasonal instances if include_seasonal is also set. The former keyword include_balanced is still accepted with a DeprecationWarning.	True
n_meta_variants	int	Number of independently-seeded instances of each meta-generator (default 3). More instances give the meta-generators a larger share when series are spread evenly across the pool, as in :func:generate_series.	3
seasonal_period	int | None	Seasonal period for the seasonal variants of the included :func:interpretable_pool and :func:seasonal_pool. Defaults to None, which derives it from freq.	None
include_seasonal	bool	When True, append the eight :func:seasonal_pool instances (strong seasonality on a moving level) at the same period. Skipped with a warning when the period is below 2, as for yearly data. Recommended for regularly seasonal quarterly and monthly targets, where it raised feature-space coverage on every panel tested that had a seasonal gap to fill; it does not help intermittent monthly data, where displacing pool breadth cost about three points. Leave it off for weekly, daily, hourly, and intermittent targets. Default False.	False
**base_kwargs	Any	Additional keyword arguments passed to all generators (e.g., engine, id_col, time_col, target_col).	{}

Returns:

Type	Description
list[BaseGenerator]	List of BaseGenerator instances ready for use with SynSet.

Examples:

>>> from synforecast import SynSet, pretraining_pool
>>> pool = pretraining_pool(min_length=512, max_length=512, freq="h")
>>> df = SynSet(pool).generate(n_series_per_generator=1)

>>> # Purely procedural corpus (meta-generators only)
>>> meta = pretraining_pool(include_interpretable=False)

>>> # Add the strongly seasonal instances for monthly targets
>>> seasonal = pretraining_pool(freq="MS", include_seasonal=True)

seasonal_pool

seasonal_pool(min_length=200, max_length=200, *, freq, seed=42, seasonal_period=None, **base_kwargs)

Create an opt-in pool of strongly seasonal series on a moving level.

Feature-space coverage benchmarks found that real quarterly and monthly panels with a pronounced, regular seasonal cycle whose swing grows with the level (tourism demand, hospital patient counts) have few near neighbours in :func:interpretable_pool. This pool adds eight configured instances of existing generators that fill that region: TSIGenerator with one harmonic at the seasonal period under moderate to heavy noise, including persistent AR(1) and heavy-tailed variants and a weakly seasonal variant; noisy multiplicative and additive Holt-Winters ETSGenerator instances with fast level adaptation; and SeasonalGenerator sines with level or slope breaks.

It is meant to be added on top of interpretable_pool or pretraining_pool, never to replace them or any share of them. On tourism, hospital, and M1 monthly panels, adding it raised the fraction of real series with a close synthetic neighbour by 8 to 32 points; on M4 panels, which have no such gap, it was neutral; and on intermittent car-parts sales it slightly lowered coverage when it displaced the pretraining pool’s share. As a standalone corpus it covers far fewer real series than the pools. It was evaluated only at quarterly and monthly periods; other periods are supported but untested, and its effect on forecasting accuracy has not been measured.

Parameters:

Name	Type	Description	Default
min_length	int	Minimum series length for all generators.	200
max_length	int	Maximum series length for all generators.	200
freq	str | int	Frequency for all generators, as a pandas offset alias or integer. Required, because the pool is meant to be combined with another and its period derives from freq: pass the same value to :func:interpretable_pool or :func:pretraining_pool, whose default is "D". Evaluated at "QS" and "MS".	required
seed	int | None	Base random seed; generator i receives seed + i. Set to None for random seeds.	42
seasonal_period	int | None	Seasonal period in time steps. Defaults to None, which derives it from freq as in :func:interpretable_pool; it must be at least 2, so yearly frequencies need an explicit value.	None
**base_kwargs	Any	Additional keyword arguments passed to all generators (e.g., engine, id_col, time_col, target_col). Keys the pool sets per generator, such as alias or level, raise ValueError.	{}

Returns:

Type	Description
list[BaseGenerator]	List of 8 BaseGenerator instances ready for use with SynSet.

Examples:

>>> from synforecast import SynSet, interpretable_pool, seasonal_pool
>>> pool = interpretable_pool(freq="MS") + seasonal_pool(freq="MS")
>>> df = SynSet(pool).generate(n_series_per_generator=1)

Multivariatizer

Bases: BaseModel

Wrap a univariate :class:BaseGenerator to produce correlated channels.

generate(n_series) draws n_series independent series of one shared length from the wrapped generator, standardizes them, applies the configured couplings, then restores each channel’s original level and scale. The output is the same long-format frame the wrapped generator produces (its id_col/time_col/target_col and engine).

Couplings (both may compose; mixing is applied first):

• "mixing" (cotemporaneous): channels become instantaneous linear combinations Z @ L.T of the standardized bases, where L is the Cholesky factor of a random well-conditioned correlation target C = (1 - s) I + s Q. Q is the correlation matrix of a random Gaussian Gram matrix and s (the mixing strength, drawn from mixing_strength_range) directly sets the magnitude of the induced cross-correlations; s < 1 keeps C positive definite, so L is well conditioned.
• "leadlag" (sequential): each non-root channel becomes, with probability 0.5 (at least one always does), a lagged, sign-flipped, noise-perturbed copy of an earlier channel: z_j = sign * roll(z_src, lag) + sigma * eps with lag from lag_range (clamped below the series length, circular wrap so all channels share the same timestamps) and sigma from noise_scale_range. Per-channel scaling comes from the level/scale restore.

Guards: every drawn base series must be finite with |x| < 1e8 and std > 1e-8; violating draws are redrawn up to 5 times, then replaced by unit Gaussian noise.

Seeding: the multivariatizer’s own seed fully determines the output. The wrapped generator is copied and reseeded from the multivariatizer’s rng on every generate call, so the base generator’s own seed and rng state never influence the result and the original object is not mutated.

The last sampled coupling recipe (mixing strength/matrix, lead-lag pairs with their lags) is exposed as last_recipe for introspection.

Parameters:

Name	Type	Description	Default
base	BaseGenerator	Wrapped univariate generator; supplies the length range, frequency, column names, and dataframe engine.	required
couplings	list[str]	Couplings to apply, subset of [‘mixing’, ‘leadlag’] (default: both).	required
mixing_strength_range	tuple[float, float]	Range for the mixing strength s in [0, 1); s scales the induced cotemporaneous cross-correlations (default: (0.2, 0.9)).	required
lag_range	tuple[int, int]	Inclusive range for lead-lag offsets in time steps (default: (1, 24)).	required
noise_scale_range	tuple[float, float]	Range for the lead-lag perturbation noise std, relative to the unit-variance standardized channels (default: (0.02, 0.2)).	required
seed	int | None	Random seed for reproducibility (default: None).	required

Multivariatizer.generate

generate(n_series, start_id=0)

Generate n_series cross-dependent channels from the wrapped base.

All channels share one length drawn from the base generator’s [min_length, max_length]; each channel is one unique_id in the long-format output.

Parameters:

Name	Type	Description	Default
n_series	int	Number of coupled channels to generate.	required
start_id	int	Starting ID for series numbering (default: 0).	0

Returns:

Type	Description
IntoDataFrameT	DataFrame in long format with the wrapped generator’s [id_col, time_col, target_col] columns and dataframe engine.

Multivariatizer.last_recipe

last_recipe: dict | None

The coupling recipe sampled by the most recent generate() call.