Statistical 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`

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`

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`

generate_single_series(length, exog=None)

Generate values for a single SARIMA time series. The generation process:

Generate white noise innovations
Apply MA filtering to get MA component
Apply AR filtering recursively
Apply inverse differencing to get integrated process
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`

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`

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`

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`

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`

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`

get_model_info()

Return information about the INAR configuration.

Getting Started

Capabilities

Generators

Nixtlaverse

API Reference

Statistical Generators

`RandomWalkGenerator`

`RandomWalkGenerator.generate_single_series`

`SeasonalGenerator`

`SeasonalGenerator.generate_single_series`

`SARIMAGenerator`

`SARIMAGenerator.generate_single_series`

`SARIMAGenerator.get_model_info`

`ETSGenerator`

`ETSGenerator.generate_single_series`

`ETSGenerator.generate_with_states`

`ETSGenerator.get_model_info`

`INARGenerator`

`INARGenerator.generate_single_series`

`INARGenerator.get_model_info`

​RandomWalkGenerator

​RandomWalkGenerator.generate_single_series

​SeasonalGenerator

​SeasonalGenerator.generate_single_series

​SARIMAGenerator

​SARIMAGenerator.generate_single_series

​SARIMAGenerator.get_model_info

​ETSGenerator

​ETSGenerator.generate_single_series

​ETSGenerator.generate_with_states

​ETSGenerator.get_model_info

​INARGenerator

​INARGenerator.generate_single_series

​INARGenerator.get_model_info

`RandomWalkGenerator`

`RandomWalkGenerator.generate_single_series`

`SeasonalGenerator`

`SeasonalGenerator.generate_single_series`

`SARIMAGenerator`

`SARIMAGenerator.generate_single_series`

`SARIMAGenerator.get_model_info`

`ETSGenerator`

`ETSGenerator.generate_single_series`

`ETSGenerator.generate_with_states`

`ETSGenerator.get_model_info`

`INARGenerator`

`INARGenerator.generate_single_series`

`INARGenerator.get_model_info`