> ## 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.

# Statistical Generators

> RandomWalk, Seasonal, SARIMA, ETS, and INAR generators

### `RandomWalkGenerator`

Bases: `BaseGenerator`

Generate random walk time series.

y\_t = y\_\{t-1} + drift + ε\_t, where ε\_t has standard deviation
`volatility` and is drawn from `innovation_distribution`. The first
output value already includes one step: y\_1 = start\_value + drift + ε\_1.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `min_length` | `int` | Minimum length of each series. | *required* |
| `max_length` | `int` | Maximum length of each series. | *required* |
| `freq` | `str \| int` | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `drift` | `float` | Mean of the random steps (default: 0.0). | *required* |
| `volatility` | `float` | Standard deviation of random steps (default: 1.0). | *required* |
| `start_value` | `float` | Initial value for all series (default: 0.0). | *required* |
| `seed` | `int \| None` | Random seed for reproducibility (default: None). | *required* |
| `id_col` | `str` | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | `str` | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | `str` | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | `str` | First timestamp of every series (default: '2000-01-01'). | *required* |

#### `RandomWalkGenerator.generate_single_series`

```python theme={null}
generate_single_series(length)
```

Generate values for a single random walk time series.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `length` | `int` | The length of the series to generate | *required* |

**Returns:**

| Type | Description |
| - | - |
| `ndarray` | Array of time series values |

### `SeasonalGenerator`

Bases: `BaseGenerator`

Generate time series with seasonal patterns.

y\_t = base\_level + amplitude · sin(2π t / period) + trend · t + ε\_t,
where ε\_t has standard deviation `noise_level`.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `min_length` | `int` | Minimum length of each series. | *required* |
| `max_length` | `int` | Maximum length of each series. | *required* |
| `freq` | `str \| int` | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `seasonality_period` | `int` | Period of seasonality in time steps (default: 24). | *required* |
| `seasonality_amplitude` | `float` | Amplitude of seasonal component (default: 10.0). | *required* |
| `trend` | `float` | Linear trend coefficient per time step (default: 0.0). | *required* |
| `noise_level` | `float` | Standard deviation of noise (default: 1.0). | *required* |
| `base_level` | `float` | Base level of the series (default: 50.0). | *required* |
| `seed` | `int \| None` | Random seed for reproducibility (default: None). | *required* |
| `id_col` | `str` | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | `str` | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | `str` | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | `str` | First timestamp of every series (default: '2000-01-01'). | *required* |

#### `SeasonalGenerator.generate_single_series`

```python theme={null}
generate_single_series(length)
```

Generate values for a single seasonal time series.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `length` | `int` | The length of the series to generate | *required* |

**Returns:**

| Type | Description |
| - | - |
| `ndarray` | Array of time series values |

### `SARIMAGenerator`

Bases: `BaseGenerator`

Generate time series based on Seasonal ARIMA (SARIMAX) processes.

Creates time series using a Seasonal AutoRegressive Integrated Moving Average
model with optional eXogenous regressors. The model is defined by (p,d,q)x(P,D,Q,s).

The SARIMA model uses multiplicative seasonal structure:

* AR polynomial: φ(B)Φ(B^s) where B is the backshift operator
* MA polynomial: θ(B)Θ(B^s)
* Differencing: (1-B)^d (1-B^s)^D

For SARIMA(1,1,1)(1,1,1)\_12, this creates dependencies at lags:

* AR: 1, 12, 13 (from φ₁, Φ₁, φ₁Φ₁)
* MA: 1, 12, 13 (from θ₁, Θ₁, θ₁Θ₁)

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `min_length` | `int` | Minimum length of each series. | *required* |
| `max_length` | `int` | Maximum length of each series. | *required* |
| `freq` | `str \| int` | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `p` | `int` | AR order (default: 1). | *required* |
| `d` | `int` | Differencing order, 0-2 (default: 0). | *required* |
| `q` | `int` | MA order (default: 1). | *required* |
| `P` | `int` | Seasonal AR order (default: 1). | *required* |
| `D` | `int` | Seasonal differencing order, 0-2 (default: 0). | *required* |
| `Q` | `int` | Seasonal MA order (default: 1). | *required* |
| `seasonal_period` | `int` | Seasonal period s (default: 12). | *required* |
| `ar_params` | `list[float] \| None` | AR coefficients φ₁,...,φ\_p (default: random stable). | *required* |
| `ma_params` | `list[float] \| None` | MA coefficients θ₁,...,θ\_q (default: random in (-0.5, 0.5)). | *required* |
| `seasonal_ar_params` | `list[float] \| None` | Seasonal AR coefficients Φ₁,...,Φ\_P (default: random stable). | *required* |
| `seasonal_ma_params` | `list[float] \| None` | Seasonal MA coefficients Θ₁,...,Θ\_Q (default: random in (-0.5, 0.5)). | *required* |
| `mean` | `float` | Process mean for stationary models (d=0, D=0) (default: 0.0). | *required* |
| `drift` | `float` | Constant added to the differenced series for integrated models (d>0 or D>0); yields slope `drift` per step when d=1 (default: 0.0). | *required* |
| `noise_std` | `float` | Standard deviation of innovation noise (default: 1.0). | *required* |
| `burn_in` | `int \| None` | Burn-in period; None computes it from model order and AR persistence (default: None). | *required* |
| `validate_stationarity` | `bool` | Validate AR parameters for stationarity (default: True). | *required* |
| `exog_coefficients` | `list[float] \| None` | Coefficients for exogenous regressors (default: None). | *required* |
| `seed` | `int \| None` | Random seed for reproducibility (default: None). | *required* |
| `id_col` | `str` | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | `str` | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | `str` | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | `str` | First timestamp of every series (default: '2000-01-01'). | *required* |

#### `SARIMAGenerator.generate_single_series`

```python theme={null}
generate_single_series(length, exog=None)
```

Generate values for a single SARIMA time series.

The generation process:

1. Generate white noise innovations
2. Apply MA filtering to get MA component
3. Apply AR filtering recursively
4. Apply inverse differencing to get integrated process
5. Add mean/drift and exogenous effects

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `length` | `int` | The length of the series to generate | *required* |
| `exog` | `ndarray \| None` | Exogenous regressors of shape (length, n\_exog) | `None` |

**Returns:**

| Type | Description |
| - | - |
| `ndarray` | Array of time series values |

#### `SARIMAGenerator.get_model_info`

```python theme={null}
get_model_info()
```

Get information about the SARIMA model configuration.

**Returns:**

| Type | Description |
| - | - |
| `dict[str, Any]` | Model information including orders, parameters, and polynomial structure |

### `ETSGenerator`

Bases: `BaseGenerator`

Generate time series based on ETS (Error, Trend, Seasonal) models.

Creates time series from the innovations state space form of exponential
smoothing (Hyndman, Koehler, Ord & Snyder, 2008). Each component is
additive (A), multiplicative (M), or absent (N):

* y\_t = μ\_t + ε\_t (additive error) or y\_t = μ\_t (1 + ε\_t) (multiplicative)
* μ\_t combines level l, trend b (optionally damped by φ), and seasonal s,
  e.g. ETS(A,A,A): μ\_t = l\_\{t-1} + φ b\_\{t-1} + s\_\{t-m}
* States update per the standard taxonomy, e.g. ETS(A,A,A):
  l\_t = l\_\{t-1} + φ b\_\{t-1} + α ε\_t; b\_t = φ b\_\{t-1} + β ε\_t;
  s\_t = s\_\{t-m} + γ ε\_t

Common models: ETS(A,N,N) simple exponential smoothing, ETS(A,A,N) Holt,
ETS(A,A,A) additive Holt-Winters, ETS(M,A,M) multiplicative Holt-Winters,
ETS(A,Ad,A) damped Holt-Winters.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `min_length` | `int` | Minimum length of each series. | *required* |
| `max_length` | `int` | Maximum length of each series. | *required* |
| `freq` | `str \| int` | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `error_type` | `str` | Error component, 'add' or 'mul' (default: 'add'). | *required* |
| `trend_type` | `str \| None` | Trend component, 'add', 'mul', or None (default: 'add'). | *required* |
| `seasonal_type` | `str \| None` | Seasonal component, 'add', 'mul', or None (default: 'add'). | *required* |
| `seasonal_period` | `int` | Seasonal period m (default: 12). | *required* |
| `level` | `float` | Initial level l\_0 (default: 100.0). | *required* |
| `trend` | `float` | Initial trend b\_0 (default: 0.0; reset to 1.0 for multiplicative trend when \<= 0). | *required* |
| `seasonal` | `list[float] \| None` | Initial seasonal states, one per season (default: random, zero-sum for additive / unit-mean for multiplicative). | *required* |
| `alpha` | `float` | Level smoothing parameter in \[0, 1] (default: 0.3). | *required* |
| `beta` | `float` | Trend smoothing parameter in \[0, 1] (default: 0.1). | *required* |
| `gamma` | `float` | Seasonal smoothing parameter in \[0, 1] (default: 0.1). | *required* |
| `phi` | `float` | Damping parameter in \[0, 1], used when damped=True (default: 0.98). | *required* |
| `damped` | `bool` | Whether to damp the trend (default: False). | *required* |
| `noise_std` | `float` | Standard deviation of the innovations ε (default: 1.0). | *required* |
| `box_cox_lambda` | `float \| None` | If set, apply the inverse Box-Cox transform with this λ to the generated series (default: None). | *required* |
| `seed` | `int \| None` | Random seed for reproducibility (default: None). | *required* |
| `id_col` | `str` | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | `str` | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | `str` | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | `str` | First timestamp of every series (default: '2000-01-01'). | *required* |

#### `ETSGenerator.generate_single_series`

```python theme={null}
generate_single_series(length)
```

Generate values for a single ETS time series.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `length` | `int` | The length of the series to generate | *required* |

**Returns:**

| Type | Description |
| - | - |
| `ndarray` | Array of time series values |

#### `ETSGenerator.generate_with_states`

```python theme={null}
generate_with_states(n_series=1, start_id=0)
```

Generate series and return both observations and hidden states.

This is useful for analyzing the underlying ETS state evolution.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `n_series` | `int` | Number of series to generate (default: 1) | `1` |
| `start_id` | `int` | Starting ID for series naming (default: 0) | `0` |

**Returns:**

| Type | Description |
| - | - |
| `tuple[IntoDataFrameT, IntoDataFrameT]` | tuple\[DataFrame, DataFrame]: - DataFrame with observations (id\_col, time\_col, target\_col) - DataFrame with states (id\_col, time\_col, level, trend, seasonal\_\*) |

#### `ETSGenerator.get_model_info`

```python theme={null}
get_model_info()
```

Get information about the ETS model configuration.

**Returns:**

| Type | Description |
| - | - |
| `dict[str, Any]` | Model information including type, parameters, and state |

### `INARGenerator`

Bases: `BaseGenerator`

Generate integer-valued time series with autoregressive structure.

INAR(p) models use binomial thinning to maintain integer values while
preserving autoregressive dynamics:

```
X_t = alpha_1 o X_{t-1} + ... + alpha_p o X_{t-p} + epsilon_t
```

where 'o' is binomial thinning, alpha o X = sum\_\{i=1}^\{X} Bernoulli(alpha),
and epsilon\_t are i.i.d. count innovations (Poisson or negative binomial).

Stationarity requires sum(alpha) \< 1, giving unconditional mean
E\[X] = E\[epsilon] / (1 - sum(alpha)). The autocorrelation function
follows the same Yule-Walker recursions as a Gaussian AR(p); for
INAR(1), acf(k) = alpha^k. With Poisson innovations the INAR(1)
stationary marginal is Poisson(innovation\_mean / (1 - alpha)).

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `min_length` | `int` | Minimum length of each series | *required* |
| `max_length` | `int` | Maximum length of each series | *required* |
| `freq` | `str \| int` | Frequency of the data (e.g. 'D', 'h', '5min') or int | *required* |
| `p` | `int` | Autoregressive order (default: 1) | *required* |
| `alpha` | `list[float] \| None` | Thinning probabilities, each in \[0, 1] with sum \< 1 (default: random with sum \< 0.8) | *required* |
| `innovation_type` | `str` | 'poisson' or 'negative\_binomial' (default: 'poisson') | *required* |
| `innovation_mean` | `float` | Mean of innovations (default: 5.0) | *required* |
| `innovation_dispersion` | `float` | Dispersion r for the negative binomial; innovation variance is mean + mean^2 / r (default: 2.0) | *required* |
| `seed` | `int \| None` | Random seed for reproducibility (default: None) | *required* |

#### `INARGenerator.generate_single_series`

```python theme={null}
generate_single_series(length)
```

Generate a single INAR time series.

**Parameters:**

| Name | Type | Description | Default |
| - | - | - | - |
| `length` | `int` | The length of the series to generate | *required* |

**Returns:**

| Type | Description |
| - | - |
| `ndarray` | Array of non-negative integer time series values |

#### `INARGenerator.get_model_info`

```python theme={null}
get_model_info()
```

Return information about the INAR configuration.


## Related topics

- [Pretraining Generators](https://nixtlaverse.nixtla.io/synforecast/generators_pretraining.html.md)
- [Seasonal](https://nixtlaverse.nixtla.io/synforecast/docs/generators/statistical/seasonal.html.md)
- [INAR (integer counts)](https://nixtlaverse.nixtla.io/synforecast/docs/generators/statistical/inar.html.md)
- [Random walk](https://nixtlaverse.nixtla.io/synforecast/docs/generators/statistical/random_walk.html.md)
- [ETS (exponential smoothing)](https://nixtlaverse.nixtla.io/synforecast/docs/generators/statistical/ets.html.md)
