> ## 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](#synforecast.base.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](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `drift` | [float](#float) | Mean of the random steps (default: 0.0). | *required* |
| `volatility` | [float](#float) | Standard deviation of random steps (default: 1.0). | *required* |
| `start_value` | [float](#float) | Initial value for all series (default: 0.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
| `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | [str](#str) | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | [str](#str) | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | [str](#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](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values |
### `SeasonalGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `seasonality_period` | [int](#int) | Period of seasonality in time steps (default: 24). | *required* |
| `seasonality_amplitude` | [float](#float) | Amplitude of seasonal component (default: 10.0). | *required* |
| `trend` | [float](#float) | Linear trend coefficient per time step (default: 0.0). | *required* |
| `noise_level` | [float](#float) | Standard deviation of noise (default: 1.0). | *required* |
| `base_level` | [float](#float) | Base level of the series (default: 50.0). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
| `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | [str](#str) | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | [str](#str) | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | [str](#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](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values |
### `SARIMAGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `p` | [int](#int) | AR order (default: 1). | *required* |
| `d` | [int](#int) | Differencing order, 0-2 (default: 0). | *required* |
| `q` | [int](#int) | MA order (default: 1). | *required* |
| `P` | [int](#int) | Seasonal AR order (default: 1). | *required* |
| `D` | [int](#int) | Seasonal differencing order, 0-2 (default: 0). | *required* |
| `Q` | [int](#int) | Seasonal MA order (default: 1). | *required* |
| `seasonal_period` | [int](#int) | Seasonal period s (default: 12). | *required* |
| `ar_params` | [list](#list)\[[float](#float)] \| None | AR coefficients φ₁,...,φ\_p (default: random stable). | *required* |
| `ma_params` | [list](#list)\[[float](#float)] \| None | MA coefficients θ₁,...,θ\_q (default: random in (-0.5, 0.5)). | *required* |
| `seasonal_ar_params` | [list](#list)\[[float](#float)] \| None | Seasonal AR coefficients Φ₁,...,Φ\_P (default: random stable). | *required* |
| `seasonal_ma_params` | [list](#list)\[[float](#float)] \| None | Seasonal MA coefficients Θ₁,...,Θ\_Q (default: random in (-0.5, 0.5)). | *required* |
| `mean` | [float](#float) | Process mean for stationary models (d=0, D=0) (default: 0.0). | *required* |
| `drift` | [float](#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](#float) | Standard deviation of innovation noise (default: 1.0). | *required* |
| `burn_in` | [int](#int) \| None | Burn-in period; None computes it from model order and AR persistence (default: None). | *required* |
| `validate_stationarity` | [bool](#bool) | Validate AR parameters for stationarity (default: True). | *required* |
| `exog_coefficients` | [list](#list)\[[float](#float)] \| None | Coefficients for exogenous regressors (default: None). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
| `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | [str](#str) | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | [str](#str) | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | [str](#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](#int) | The length of the series to generate | *required* |
| `exog` | [ndarray](#numpy.ndarray) \| None | Exogenous regressors of shape (length, n\_exog) | None |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.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](#dict)\[[str](#str), [Any](#typing.Any)] | Model information including orders, parameters, and polynomial structure |
### `ETSGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series. | *required* |
| `max_length` | [int](#int) | Maximum length of each series. | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency, a pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time step. | *required* |
| `error_type` | [str](#str) | Error component, 'add' or 'mul' (default: 'add'). | *required* |
| `trend_type` | [str](#str) \| None | Trend component, 'add', 'mul', or None (default: 'add'). | *required* |
| `seasonal_type` | [str](#str) \| None | Seasonal component, 'add', 'mul', or None (default: 'add'). | *required* |
| `seasonal_period` | [int](#int) | Seasonal period m (default: 12). | *required* |
| `level` | [float](#float) | Initial level l\_0 (default: 100.0). | *required* |
| `trend` | [float](#float) | Initial trend b\_0 (default: 0.0; reset to 1.0 for multiplicative trend when \<= 0). | *required* |
| `seasonal` | [list](#list)\[[float](#float)] \| None | Initial seasonal states, one per season (default: random, zero-sum for additive / unit-mean for multiplicative). | *required* |
| `alpha` | [float](#float) | Level smoothing parameter in \[0, 1] (default: 0.3). | *required* |
| `beta` | [float](#float) | Trend smoothing parameter in \[0, 1] (default: 0.1). | *required* |
| `gamma` | [float](#float) | Seasonal smoothing parameter in \[0, 1] (default: 0.1). | *required* |
| `phi` | [float](#float) | Damping parameter in \[0, 1], used when damped=True (default: 0.98). | *required* |
| `damped` | [bool](#bool) | Whether to damp the trend (default: False). | *required* |
| `noise_std` | [float](#float) | Standard deviation of the innovations ε (default: 1.0). | *required* |
| `box_cox_lambda` | [float](#float) \| None | If set, apply the inverse Box-Cox transform with this λ to the generated series (default: None). | *required* |
| `seed` | [int](#int) \| None | Random seed for reproducibility (default: None). | *required* |
| `id_col` | [str](#str) | Name of the ID column (default: 'unique\_id'). | *required* |
| `time_col` | [str](#str) | Name of the timestamp column (default: 'ds'). | *required* |
| `target_col` | [str](#str) | Name of the value column (default: 'y'). | *required* |
| `start_datetime` | [str](#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](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | --------------------------- |
| [ndarray](#numpy.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](#int) | Number of series to generate (default: 1) | 1 |
| `start_id` | [int](#int) | Starting ID for series naming (default: 0) | 0 |
**Returns:**
| Type | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [tuple](#tuple)\[[IntoDataFrameT](#narwhals.stable.v2.typing.IntoDataFrameT), [IntoDataFrameT](#narwhals.stable.v2.typing.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](#dict)\[[str](#str), [Any](#typing.Any)] | Model information including type, parameters, and state |
### `INARGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#int) | Minimum length of each series | *required* |
| `max_length` | [int](#int) | Maximum length of each series | *required* |
| `freq` | [str](#str) \| [int](#int) | Frequency of the data (e.g. 'D', 'h', '5min') or int | *required* |
| `p` | [int](#int) | Autoregressive order (default: 1) | *required* |
| `alpha` | [list](#list)\[[float](#float)] \| None | Thinning probabilities, each in \[0, 1] with sum \< 1 (default: random with sum \< 0.8) | *required* |
| `innovation_type` | [str](#str) | 'poisson' or 'negative\_binomial' (default: 'poisson') | *required* |
| `innovation_mean` | [float](#float) | Mean of innovations (default: 5.0) | *required* |
| `innovation_dispersion` | [float](#float) | Dispersion r for the negative binomial; innovation variance is mean + mean^2 / r (default: 2.0) | *required* |
| `seed` | [int](#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](#int) | The length of the series to generate | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ------------------------------------------------ |
| [ndarray](#numpy.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.