> ## 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.
# Multivariate Generators
> Copula, VAR, and Gaussian Process generators for correlated time series
### `CopulaGenerator`
Bases: [BaseGenerator](#synforecast.base.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:
1. 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).
2. 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](#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. A pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time index step. | *required* |
| `copula_type` | [str](#str) | 'gaussian' or 't' (default: 'gaussian'). | *required* |
| `correlation_matrix` | [list](#list)\[[list](#list)\[[float](#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](#float) | Degrees of freedom for the t copula (default: 5.0). | *required* |
| `marginal_distributions` | [list](#list)\[[dict](#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](#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 (default: '2000-01-01'). | *required* |
#### `CopulaGenerator.generate_single_series`
```python theme={null}
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](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ---------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values. |
#### `CopulaGenerator.generate`
```python theme={null}
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](#int) | Number of correlated series (variables). | *required* |
| `start_id` | [int](#int) | Starting ID for series numbering (default: 0). | 0 |
| `n_jobs` | [int](#int) | Unused (accepted for API compatibility). | -1 |
**Returns:**
| Type | Description |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [IntoDataFrameT](#narwhals.stable.v2.typing.IntoDataFrameT) | DataFrame in long format with columns \[id\_col, time\_col, target\_col]; each unique\_id is one correlated variable. |
### `VARGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#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. A pandas offset alias (e.g. 'D', 'h', '5min', 'MS') or an integer time index step. | *required* |
| `lag_order` | [int](#int) | VAR lag order p (default: 1). | *required* |
| `coef_matrices` | [list](#list)\[[list](#list)\[[list](#list)\[[float](#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](#list)\[[float](#float)] \| None | Intercept vector c (default: zeros). | *required* |
| `innovation_covariance` | [list](#list)\[[list](#list)\[[float](#float)]] \| None | Innovation covariance Sigma; symmetric positive definite (default: identity). | *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 (default: '2000-01-01'). | *required* |
#### `VARGenerator.generate_single_series`
```python theme={null}
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](#int) | The length of the series to generate. | *required* |
**Returns:**
| Type | Description |
| -------------------------------------- | ----------------------------------------- |
| [ndarray](#numpy.ndarray) | Array of time series values (univariate). |
#### `VARGenerator.generate`
```python theme={null}
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](#int) | Number of correlated series (variables). | *required* |
| `start_id` | [int](#int) | Starting ID for series numbering (default: 0). | 0 |
| `n_jobs` | [int](#int) | Unused (accepted for API compatibility). | -1 |
**Returns:**
| Type | Description |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [IntoDataFrameT](#narwhals.stable.v2.typing.IntoDataFrameT) | DataFrame in long format with columns \[id\_col, time\_col, target\_col]; each unique\_id is one correlated variable. |
### `GaussianProcessGenerator`
Bases: [BaseGenerator](#synforecast.base.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](#str) | Kernel type (default: 'rbf'). | *required* |
| `length_scale` | [float](#float) | Kernel length scale (default: 20.0). | *required* |
| `amplitude` | [float](#float) | Signal amplitude / output scale (default: 1.0). | *required* |
| `period` | [float](#float) | Period for the periodic kernel (default: 50.0). | *required* |
| `mean` | [float](#float) | Mean function value (default: 0.0). | *required* |
| `noise_variance` | [float](#float) | Observation noise variance, also acts as jitter for the Cholesky factorization (default: 1e-6). | *required* |
#### `GaussianProcessGenerator.generate_single_series`
```python theme={null}
generate_single_series(length)
```
Generate a single GP sample path.
**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 |
#### `GaussianProcessGenerator.get_model_info`
```python theme={null}
get_model_info()
```
Return information about the GP configuration.