Multivariate Generators

`CopulaGenerator`

Bases: BaseGenerator Generate correlated time series using Gaussian or t copulas. Copulas model the dependence structure between variables independently of their marginal distributions. Sampling proceeds in two steps:

Draw correlated uniforms from the copula. Gaussian copula: z ~ N(0, R), u_i = Phi(z_i). t copula: z ~ N(0, R), w ~ chi2(df), u_i = T_df(z_i * sqrt(df / w)) (the chi-square mixing is shared across variables, which creates tail dependence).
Map each uniform through the inverse CDF of its marginal: x_i = F_i^{-1}(u_i).

For the Gaussian copula the rank correlations satisfy spearman = (6 / pi) * arcsin(rho / 2) and for both copulas kendall_tau = (2 / pi) * arcsin(rho). generate(n_series) creates n_series correlated variables sharing one length; each variable is one unique_id in the long-format output. Samples are i.i.d. over time (no serial dependence). 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. A pandas offset alias (e.g. ‘D’, ‘h’, ‘5min’, ‘MS’) or an integer time index step.	required
`copula_type`	`str`	’gaussian’ or ‘t’ (default: ‘gaussian’).	required
`correlation_matrix`	`list[list[float]] \| None`	Correlation matrix. Must be symmetric positive definite with unit diagonal. When None, a random correlation matrix is generated. When smaller than n_series, it is padded with an identity block (extra variables are independent); when larger, the leading principal submatrix is used.	required
`df`	`float`	Degrees of freedom for the t copula (default: 5.0).	required
`marginal_distributions`	`list[dict]`	Marginal specs, cycled over variables. Types: ‘normal’ (loc, scale), ‘lognormal’ (mean, sigma), ‘exponential’ (scale), ‘uniform’ (low, high), ‘gamma’ (shape, scale). Default: standard normal.	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 (default: ‘2000-01-01’).	required

`CopulaGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single univariate series. Provided for compatibility with BaseGenerator; use generate(n_series) for multivariate output. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of time series values.

`CopulaGenerator.generate`

generate(n_series, start_id=0, n_jobs=-1)

Generate n_series correlated series with copula dependence. Overrides the base generate() for multivariate output: n_series is the number of correlated variables, all sharing a single length. Generation is inherently joint, so n_jobs has no effect. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of correlated series (variables).	required
`start_id`	`int`	Starting ID for series numbering (default: 0).	`0`
`n_jobs`	`int`	Unused (accepted for API compatibility).	`-1`

Returns:

Type	Description
`IntoDataFrameT`	DataFrame in long format with columns [id_col, time_col, target_col]; each unique_id is one correlated variable.

`VARGenerator`

Bases: BaseGenerator Generate correlated time series using a Vector Autoregression model. A VAR(p) process models each variable as a linear function of past values of all variables:

y[t] = c + A_1 y[t-1] + ... + A_p y[t-p] + e[t],  e[t] ~ (0, Sigma)

The process is stable (stationary) iff the companion matrix

[[A_1 ... A_p], [I 0 ... 0], ..., [0 ... I 0]]

has spectral radius < 1, in which case the stationary mean is (I - A_1 - ... - A_p)^{-1} c. Innovations are drawn from the configured innovation distribution and correlated via the Cholesky factor of Sigma. A burn-in of 100 steps is discarded. generate(n_series) creates n_series correlated variables sharing one length; each variable is one unique_id in the long-format output. 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. A pandas offset alias (e.g. ‘D’, ‘h’, ‘5min’, ‘MS’) or an integer time index step.	required
`lag_order`	`int`	VAR lag order p (default: 1).	required
`coef_matrices`	`list[list[list[float]]] \| None`	One square coefficient matrix per lag, all the same size. Must define a stable VAR. When None, random stable coefficients are generated. When sized differently from n_series, the leading principal submatrices are used (or zero-padded).	required
`intercept`	`list[float] \| None`	Intercept vector c (default: zeros).	required
`innovation_covariance`	`list[list[float]] \| None`	Innovation covariance Sigma; symmetric positive definite (default: identity).	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 (default: ‘2000-01-01’).	required

`VARGenerator.generate_single_series`

generate_single_series(length)

Generate values for a single (univariate) VAR series. Provided for compatibility with BaseGenerator; use generate(n_series) for multivariate output. Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the series to generate.	required

Returns:

Type	Description
`ndarray`	Array of time series values (univariate).

`VARGenerator.generate`

generate(n_series, start_id=0, n_jobs=-1)

Generate n_series correlated time series using the VAR model. Overrides the base generate() for multivariate output: n_series is the number of correlated variables, all sharing a single length. Generation is inherently joint, so n_jobs has no effect. Parameters:

Name	Type	Description	Default
`n_series`	`int`	Number of correlated series (variables).	required
`start_id`	`int`	Starting ID for series numbering (default: 0).	`0`
`n_jobs`	`int`	Unused (accepted for API compatibility).	`-1`

Returns:

Type	Description
`IntoDataFrameT`	DataFrame in long format with columns [id_col, time_col, target_col]; each unique_id is one correlated variable.

`GaussianProcessGenerator`

Bases: BaseGenerator Generate time series by sampling from a Gaussian Process. Samples f ~ GP(mean, k) on the integer grid t = 0..length-1, so the marginal distribution is N(mean, amplitude^2 + noise_variance) and the correlation at lag r is k(r) / k(0). Kernels (r = |t - t’|, l = length_scale, a = amplitude):

rbf: a^2 exp(-r^2 / (2 l^2)) — infinitely differentiable, very smooth paths
matern_0.5: a^2 exp(-r/l) — rough, Ornstein-Uhlenbeck-like
matern_1.5: a^2 (1+s) exp(-s), s = sqrt(3) r / l — once-differentiable
matern_2.5: a^2 (1+s+s^2/3) exp(-s), s = sqrt(5) r / l — twice-differentiable
periodic: a^2 exp(-2 sin^2(pi r / period) / l^2) — exact periodicity

Parameters:

Name	Type	Description	Default
`kernel`	`str`	Kernel type (default: ‘rbf’).	required
`length_scale`	`float`	Kernel length scale (default: 20.0).	required
`amplitude`	`float`	Signal amplitude / output scale (default: 1.0).	required
`period`	`float`	Period for the periodic kernel (default: 50.0).	required
`mean`	`float`	Mean function value (default: 0.0).	required
`noise_variance`	`float`	Observation noise variance, also acts as jitter for the Cholesky factorization (default: 1e-6).	required

`GaussianProcessGenerator.generate_single_series`

generate_single_series(length)

Generate a single GP sample path. Parameters:

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

Returns:

Type	Description
`ndarray`	Array of time series values

`GaussianProcessGenerator.get_model_info`

get_model_info()

Return information about the GP configuration.

Getting Started

Capabilities

Generators

Nixtlaverse

API Reference

Multivariate Generators

`CopulaGenerator`

`CopulaGenerator.generate_single_series`

`CopulaGenerator.generate`

`VARGenerator`

`VARGenerator.generate_single_series`

`VARGenerator.generate`

`GaussianProcessGenerator`

`GaussianProcessGenerator.generate_single_series`

`GaussianProcessGenerator.get_model_info`

​CopulaGenerator

​CopulaGenerator.generate_single_series

​CopulaGenerator.generate

​VARGenerator

​VARGenerator.generate_single_series

​VARGenerator.generate

​GaussianProcessGenerator

​GaussianProcessGenerator.generate_single_series

​GaussianProcessGenerator.get_model_info

`CopulaGenerator`

`CopulaGenerator.generate_single_series`

`CopulaGenerator.generate`

`VARGenerator`

`VARGenerator.generate_single_series`

`VARGenerator.generate`

`GaussianProcessGenerator`

`GaussianProcessGenerator.generate_single_series`

`GaussianProcessGenerator.get_model_info`