Dataset

`SynSet`

SynSet(generators)

Generate synthetic time series datasets from multiple generators. Combine multiple generators into one long-format panel; each generator contributes its own type of time series pattern. Parameters:

Name	Type	Description	Default
`generators`	`list[BaseGenerator]`	List of instantiated generator objects to use for creating time series.	required

Examples:

>>> from synforecast import SynSet
>>> from synforecast.generators import RandomWalkGenerator, SeasonalGenerator
>>>
>>> # Create generators
>>> rw_gen = RandomWalkGenerator(
...     min_length=100,
...     max_length=150,
...     freq="h",
...     seed=42,
... )
>>> seasonal_gen = SeasonalGenerator(
...     min_length=100,
...     max_length=150,
...     freq="h",
...     seed=43,
... )
>>>
>>> # Create dataset
>>> dataset = SynSet([rw_gen, seasonal_gen])
>>> df = dataset.generate(n_series_per_generator=5)

Initialize the SynSet with a list of generators. Parameters:

Name	Type	Description	Default
`generators`	`list[BaseGenerator]`	List of instantiated generator objects.	required

Raises:

Type	Description
`ValueError`	If generators list is empty or contains non-BaseGenerator objects. If generators have inconsistent column names (id_col, time_col, target_col).

`SynSet.generate`

generate(n_series_per_generator, n_jobs=-1)

Generate synthetic time series data from all generators. Parameters:

Name	Type	Description	Default
`n_series_per_generator`	`int`	Number of time series to generate from each generator.	required
`n_jobs`	`int`	Number of parallel workers. -1 (default) uses `RAYON_NUM_THREADS` if set, otherwise all logical cores. Results are seed-deterministic and do not depend on n_jobs.	`-1`

Returns:

Type	Description
`IntoFrameT`	DataFrame containing all generated time series from all generators, in long format with columns [id_col, time_col, target_col].

`SynAugment`

SynAugment(id_col='unique_id', time_col='ds', target_col='y', seed=None, engine=None, on_error='raise')

Augment time series datasets with synthetic series. Analyzes input time series, auto-selects appropriate generators based on statistical properties, fits parameters, and generates statistically similar synthetic series. The augmentation process:

For each unique series in the input DataFrame, analyze its statistical properties
Auto-select the most appropriate generator (or use user override)
Fit generator parameters to match the series’ statistical fingerprint
Generate n_augment synthetic series that preserve these properties
Return combined DataFrame with original and synthetic series

Synthetic series IDs follow the pattern "{original_id}_aug_{i}" Parameters:

Name	Type	Description	Default
`id_col`	`str`	Name of the ID column (default: ‘unique_id’)	`‘unique_id’`
`time_col`	`str`	Name of the timestamp column (default: ‘ds’)	`‘ds’`
`target_col`	`str`	Name of the value column (default: ‘y’)	`‘y’`
`seed`	`int \| None`	Random seed for reproducibility	`None`
`engine`	`str \| None`	Output dataframe library. None (default) matches the input DataFrame’s library.	`None`

Initialize the SynAugment instance. Parameters:

Name	Type	Description	Default
`id_col`	`str`	Name of the ID column	`’unique_id’`
`time_col`	`str`	Name of the timestamp column	`’ds’`
`target_col`	`str`	Name of the value column	`’y’`
`seed`	`int \| None`	Random seed for reproducibility	`None`
`engine`	`str \| None`	Output dataframe library (e.g. ‘pandas’, ‘polars’). None (default) matches the input DataFrame’s library.	`None`
`on_error`	`Literal[‘raise’, ‘ar1’]`	What to do when a fitted generator fails for a series. ‘raise’ (default) propagates the error; ‘ar1’ substitutes an AR(1) series matching the source’s mean, std, and lag-1 autocorrelation, and reports all substitutions in a single warning at the end of `augment`.	`‘raise’`

`SynAugment.analyze`

analyze(df)

Analyze all series in DataFrame and return properties. For each unique series, detects statistical properties and recommends the most appropriate generator. Parameters:

Name	Type	Description	Default
`df`	`IntoFrameT`	DataFrame with time series data (must have id_col, time_col, target_col)	required

Returns:

Type	Description
`dict[str, dict]`	Mapping of each `unique_id` to its analysis results. Every entry holds `recommended_generator` (the chosen generator name), `properties` (all detected statistical properties), and `fitted_params` (the estimated generator parameters).

Raises:

Type	Description
`ValueError`	If DataFrame is missing required columns

`SynAugment.augment`

augment(df, n_augment=1, generator_override=None, preserve_timestamps=True)

Augment dataset with synthetic series. For each series in the input DataFrame, generates n_augment synthetic series that are statistically similar to the original. Parameters:

Name	Type	Description	Default
`df`	`IntoFrameT`	Input DataFrame with time series (must have id_col, time_col, target_col)	required
`n_augment`	`int`	Number of synthetic series to generate per original series	`1`
`generator_override`	`dict[str, str] \| None`	Optional dict mapping unique_id to generator name. Overrides automatic generator selection for specified series. Example: {“series_0”: “SARIMAGenerator”}	`None`
`preserve_timestamps`	`bool`	If True, synthetic series use the same timestamps as the original series	`True`

Returns:

Type	Description
`IntoFrameT`	Combined DataFrame with original and synthetic series. Synthetic series IDs follow the pattern `"{original_id}_aug_{i}"`

Raises:

Type	Description
`ValueError`	If DataFrame is missing required columns, n_augment < 1, or generator_override names an unsupported generator
`RuntimeError`	If a fitted generator fails for a series and the instance was created with on_error=‘raise’ (the default)

`SynAugment.augment_single_series`

augment_single_series(series_id, values, timestamps, n_augment=1, generator_name=None)

Augment a single series (lower-level API). Parameters:

Name	Type	Description	Default
`series_id`	`str`	ID of the original series	required
`values`	`ndarray`	Array of time series values	required
`timestamps`	`ndarray`	Array of timestamps	required
`n_augment`	`int`	Number of synthetic series to generate	`1`
`generator_name`	`str \| None`	Optional generator name; if None, auto-detect	`None`

Returns:

Type	Description
`list[tuple[str, ndarray, ndarray]]`	List of tuples: (new_id, synthetic_values, timestamps)

Getting Started

Capabilities

Generators

Nixtlaverse

API Reference

`SynSet`

`SynSet.generate`

`SynAugment`

`SynAugment.analyze`

`SynAugment.augment`

`SynAugment.augment_single_series`

​SynSet

​SynSet.generate

​SynAugment

​SynAugment.analyze

​SynAugment.augment

​SynAugment.augment_single_series

`SynSet`

`SynSet.generate`

`SynAugment`

`SynAugment.analyze`

`SynAugment.augment`

`SynAugment.augment_single_series`