Dataset

Dataset composition and augmentation

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.

Four strategies share the same column contract and seeding:

• :meth:augment fits a parametric generator per series and simulates from it (IDs "{original_id}_aug_{i}").
• :meth:mixup forms convex combinations of scaled series (mean absolute scaling by default; z-normalization is optional) (IDs "mixup_{i}").
• :meth:mbb bootstraps decomposition remainders in moving blocks (IDs "{original_id}_mbb_{i}").
• :meth:dba averages nearest neighbours with DTW barycenters (IDs "{original_id}_dba_{i}").

The fit-and-simulate process behind :meth:augment:

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

Series that are entirely missing (or, for :meth:mbb, shorter than four observations) are skipped with a logged warning by :meth:mixup, :meth:mbb, and :meth:dba.

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)

SynAugment.mixup

mixup(df, n_series=None, max_mix=3, alpha=1.5, scaling='mean', include_original=True)

Augment a dataset with TSMixup convex combinations of real series.

Implements TSMixup, the augmentation used to pretrain the Chronos forecasting models (Ansari et al. 2024, “Chronos: Learning the Language of Time Series”, https://arxiv.org/abs/2403.07815, Apache-2.0). Each synthetic series is built by drawing 1..max_mix source series, taking a random window of their shared (minimum) length, scaling each window, and combining them with convex weights sampled from a Dirichlet(alpha) distribution. Unlike :meth:augment, a mixup series is not tied to a single source: it blends the dynamics of several, which broadens a small panel without fitting any generator.

Because the mixed series live in scaled space (different sources have different magnitudes), the output retains the chosen scaling rather than any single source’s level. Use scaling="none" to mix raw values when all series already share a scale.

Parameters:

Name	Type	Description	Default
df	IntoFrameT	Input DataFrame with time series (must have id_col, time_col, target_col).	required
n_series	int | None	Number of synthetic series to create. Defaults to the number of input series.	None
max_mix	int	Maximum number of source series combined per synthetic series; the count is drawn uniformly from 1..max_mix and capped at the number of available series (default: 3).	3
alpha	float	Concentration of the symmetric Dirichlet weight distribution. Values < 1 concentrate weight on few sources; larger values spread it more evenly (default: 1.5).	1.5
scaling	Literal[‘mean’, ‘std’, ‘none’]	Per-window scaling before mixing: ‘mean’ (divide by mean absolute value, Chronos default), ‘std’ (z-normalize), or ‘none’ (default: ‘mean’).	‘mean’
include_original	bool	Prepend the original series to the output (default: True).	True

Returns:

Type	Description
IntoFrameT	DataFrame with the original series (optional) and synthetic mixup series. Mixup IDs follow the pattern "mixup_{i}".

Raises:

Type	Description
ValueError	If the DataFrame is missing required columns, if arguments are out of range, or if it holds no usable series.

SynAugment.mbb

mbb(df, n_augment=1, seasonal_period=None, block_size=None, include_original=True)

Bootstrap decomposition remainders with moving blocks.

This non-parametric augmenter follows the moving-block-bootstrap idea used for forecasting by Bergmeir, Hyndman, and Benitez (2016, https://doi.org/10.1016/j.ijforecast.2015.07.002) and the augmentation recipe discussed by Bandara et al. (2021, https://arxiv.org/abs/2008.02663). SynForecast uses a classical moving-average decomposition rather than Box-Cox plus STL; its defaults, block-size choice, and stability guards are its own design rather than a reproduction of the reference code.

This method deliberately bypasses the _match_autocorrelation rescaling used by :meth:augment. Recombining a source’s own trend and seasonal components with bootstrapped remainder blocks already anchors the result to that source; re-pinning mean and standard deviation would distort the remainder variability.

Classical decomposition and moving-block sampling execute in native Rust. Seed determinism is stable within this native path.

NaNs are interpolated before decomposition. Series without a finite observation or with fewer than four observations are skipped with a logged warning; at least one series must be usable. Additional input columns are copied unchanged from each source series. The effective block length, including an explicitly supplied block_size, is capped per source series at max(2, len(series) // 3). This keeps multiple remainder blocks in play for short inputs; request a smaller value when the exact block length matters.

An explicit period requires at least two cycles per source. Shorter sources use nonseasonal decomposition and are listed in a logged warning. Infinite values reject the call with the offending series ID; NaNs follow the interpolation/skip policy above.

Parameters:

Name	Type	Description	Default
df	IntoFrameT	Input frame containing the configured ID, time and target columns.	required
n_augment	int	Copies per usable source, from 1 to 1000 (default: 1).	1
seasonal_period	int | None	Period >= 2, or None to detect it per source.	None
block_size	int | None	Block length >= 2, or None for the period/length-based default. Explicit lengths are also capped as described above.	None
include_original	bool	Include unchanged original rows (default: True).	True

Returns:

Type	Description
IntoFrameT	Frame containing generated series and, optionally, original rows,
IntoFrameT	using the configured output engine or the input engine.

Raises:

Type	Description
ValueError	For invalid arguments, missing required columns, infinite target values, or no usable source series.

SynAugment.dba

dba(df, n_augment=1, n_neighbors=3, n_iterations=5, window_fraction=0.1, scale='reference', include_original=True)

Augment a panel with randomized nearest-neighbor DTW barycenters.

DBA comes from Petitjean, Ketterlin, and Gancarski (2011, https://doi.org/10.1016/j.patcog.2010.09.013); nearest-neighbor weighted augmentation follows Forestier et al. (2017, https://doi.org/10.1109/ICDM.2017.106) and Bandara et al. (2021, https://arxiv.org/abs/2008.02663). Neighbor weighting, per-copy weight randomization, banded DTW, and z-normalized alignment are SynForecast’s own design rather than a reproduction of the reference code. Pairwise panel distances are computed once per call in bounded parallel chunks, retaining only the nearest neighbors per source. Neighbor storage is O(number of series * n_neighbors); distance computation still examines every pair. The band limits the otherwise quadratic alignment cost.

This panel-aware method caches every usable source series once and deliberately bypasses _match_autocorrelation. With the default scale="reference", inputs are z-normalized for alignment and the barycenter is mapped to the reference mean and standard deviation. That is explicit reference anchoring, not the :meth:augment pinning path. scale="none" averages raw values for panels already sharing scale. Plain DBA is deterministic, so each requested copy randomizes the reference and neighbor weights to create distinct augmentations. Additional input columns are copied unchanged from the reference series; DBA only barycenters the target column.

Copies share their initial alignment paths and refine in parallel in native Rust. At most eight alignments/copies execute concurrently. Parent storage per alignment, cached paths per copy and returned copies per reference have separate 64 MiB limits; excessive requests raise ValueError. Interrupts are checked between work chunks. Seed determinism is stable within this native path.

NaNs are interpolated; entirely missing sources are skipped with a warning. Infinite values reject the call with the offending series ID. Reference scaling preserves zero scale for constant sources, producing constant copies. Sources with standard deviation below 1e-8 are listed in a warning because their copies may add little or no variation.

Parameters:

Name	Type	Description	Default
df	IntoFrameT	Input frame containing the configured ID, time and target columns.	required
n_augment	int	Copies per usable reference, from 1 to 1000 (default: 1).	1
n_neighbors	int	Positive maximum neighbor count (default: 3), capped at the number of other usable sources.	3
n_iterations	int	Barycenter updates, from 1 to 1000 (default: 5).	5
window_fraction	float	DTW band fraction in (0, 1] (default: 0.1).	0.1
scale	Literal[‘reference’, ‘none’]	“reference” to restore reference scale (default), or “none” to average raw values.	‘reference’
include_original	bool	Include unchanged original rows (default: True).	True

Returns:

Type	Description
IntoFrameT	Frame containing generated series and, optionally, original rows,
IntoFrameT	using the configured output engine or the input engine.

Raises:

Type	Description
ValueError	For invalid arguments, missing required columns, infinite target values, excessive alignment/output storage, or fewer than two usable source series.