> ## Documentation Index > Fetch the complete documentation index at: https://nixtlaverse.nixtla.io/llms.txt > Use this file to discover all available pages before exploring further. # Dataset > Dataset composition and augmentation ### `SynSet` ```python theme={null} 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](#list)\[[BaseGenerator](#synforecast.base.BaseGenerator)] | List of instantiated generator objects to use for creating time series. | *required* | **Examples:** ```pycon theme={null} >>> 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](#list)\[[BaseGenerator](#synforecast.base.BaseGenerator)] | List of instantiated generator objects. | *required* | **Raises:** | Type | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [ValueError](#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` ```python theme={null} 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](#int) | Number of time series to generate from each generator. | *required* | | `n_jobs` | [int](#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](#narwhals.stable.v2.typing.IntoFrameT) | DataFrame containing all generated time series from all generators, in long format with columns \[id\_col, time\_col, target\_col]. |
Notes Series IDs are unique across all generators. With 2 generators and 3 series per generator, IDs run from 0 to 5.
### `SynAugment` ```python theme={null} 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: 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 Synthetic series IDs follow the pattern `"{original_id}_aug_{i}"` **Parameters:** | Name | Type | Description | Default | | ------------ | -------------------------------- | ------------------------------------------------------------------------------- | ------------------------- | | `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id') | 'unique\_id' | | `time_col` | [str](#str) | Name of the timestamp column (default: 'ds') | 'ds' | | `target_col` | [str](#str) | Name of the value column (default: 'y') | 'y' | | `seed` | [int](#int) \| None | Random seed for reproducibility | None | | `engine` | [str](#str) \| None | Output dataframe library. None (default) matches the input DataFrame's library. | None |
Example > > > from synforecast import SynAugment > > > import polars as pl > > > > > > # Create sample data > > > > > > df = pl.DataFrame( > > > ... \{ > > > ... "unique\_id": \["series\_0"] \* 100, > > > ... "ds": pl.date\_range( > > > ... pl.date(2020, 1, 1), pl.date(2020, 4, 9), eager=True > > > ... ), > > > ... "y": \[i + np.random.randn() for i in range(100)], > > > ... } > > > ... ) > > > > > > # Augment the dataset > > > > > > augmenter = SynAugment(seed=42) > > > augmented\_df = augmenter.augment(df, n\_augment=3) > > > augmented\_df\["unique\_id"].n\_unique() > > > 4
Initialize the SynAugment instance. **Parameters:** | Name | Type | Description | Default | | ------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `id_col` | [str](#str) | Name of the ID column | 'unique\_id' | | `time_col` | [str](#str) | Name of the timestamp column | 'ds' | | `target_col` | [str](#str) | Name of the value column | 'y' | | `seed` | [int](#int) \| None | Random seed for reproducibility | None | | `engine` | [str](#str) \| None | Output dataframe library (e.g. 'pandas', 'polars'). None (default) matches the input DataFrame's library. | None | | `on_error` | [Literal](#typing.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` ```python theme={null} 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](#narwhals.stable.v2.typing.IntoFrameT) | DataFrame with time series data (must have id\_col, time\_col, target\_col) | *required* | **Returns:** | Type | Description | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [dict](#dict)\[[str](#str), [dict](#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](#ValueError) | If DataFrame is missing required columns | #### `SynAugment.augment` ```python theme={null} 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](#narwhals.stable.v2.typing.IntoFrameT) | Input DataFrame with time series (must have id\_col, time\_col, target\_col) | *required* | | `n_augment` | [int](#int) | Number of synthetic series to generate per original series | 1 | | `generator_override` | [dict](#dict)\[[str](#str), [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](#bool) | If True, synthetic series use the same timestamps as the original series | True | **Returns:** | Type | Description | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [IntoFrameT](#narwhals.stable.v2.typing.IntoFrameT) | Combined DataFrame with original and synthetic series. Synthetic series IDs follow the pattern `"{original_id}_aug_{i}"` | **Raises:** | Type | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | [ValueError](#ValueError) | If DataFrame is missing required columns, n\_augment \< 1, or generator\_override names an unsupported generator | | [RuntimeError](#RuntimeError) | If a fitted generator fails for a series and the instance was created with on\_error='raise' (the default) |
Example > > > augmenter = SynAugment(seed=42) > > > > > > # Basic augmentation > > > > > > augmented\_df = augmenter.augment(df, n\_augment=3) # doctest: +SKIP > > > > > > # With generator override > > > > > > augmented\_df = augmenter.augment( # doctest: +SKIP > > > ... df, n\_augment=2, generator\_override=\{"series\_0": "SARIMAGenerator"} > > > ... )
#### `SynAugment.augment_single_series` ```python theme={null} 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](#str) | ID of the original series | *required* | | `values` | [ndarray](#numpy.ndarray) | Array of time series values | *required* | | `timestamps` | [ndarray](#numpy.ndarray) | Array of timestamps | *required* | | `n_augment` | [int](#int) | Number of synthetic series to generate | 1 | | `generator_name` | [str](#str) \| None | Optional generator name; if None, auto-detect | None | **Returns:** | Type | Description | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [list](#list)\[[tuple](#tuple)\[[str](#str), [ndarray](#numpy.ndarray), [ndarray](#numpy.ndarray)]] | List of tuples: (new\_id, synthetic\_values, timestamps) |