# copula¶

High performance copula generators

pyscenarios.copula.gaussian_copula(cov: Union[List[List[float]], numpy.ndarray], samples: int, seed: int = 0, chunks: Union[None, int, Tuple[int, int], Tuple[Tuple[int, ...], Tuple[int, ...]]] = None, rng: str = 'Mersenne Twister') → Union[numpy.ndarray, dask.array.core.Array]

Gaussian Copula scenario generator.

Simplified algorithm:

>>> l = numpy.linalg.cholesky(cov)
>>> y = numpy.random.standard_normal(size=(samples, cov.shape))
>>> p = (l @ y.T).T

Parameters
• cov (numpy.ndarray) – covariance matrix, a.k.a. correlation matrix. It must be a Hermitian, positive-definite matrix in any square array-like format. The width of cov determines the number of dimensions of the output.

• samples (int) –

Number of random samples to generate

Note

When using Sobol, to obtain a uniform distribution one must use $$2^{n} - 1$$ samples (for any n > 0).

• chunks

Chunk size for the return array, which has shape (samples, dimensions). It can be anything accepted by dask (a positive integer, a tuple of two ints, or a tuple of two tuples of ints) for the output shape.

Set to None to return a numpy array.

Warning

When using the Mersenne Twister random generator, the chunk size changes the random sequence. To guarantee repeatability, it must be fixed together with the seed. chunks=None also produces different results from using dask.

• seed (int) –

Random seed.

With rng='Sobol', this is the initial dimension; when generating multiple copulas with different seeds, one should never use seeds that are less than cov.shape apart from each other.

The maximum seed when using sobol is:

pyscenarios.sobol.max_dimensions() - cov.shape - 1


• rng (str) – Either Mersenne Twister or Sobol

Returns

array of shape (samples, dimensions), with all series being normal (0, 1) distributions.

Return type

If chunks is not None, dask.array.Array; else numpy.ndarray

pyscenarios.copula.t_copula(cov: Union[List[List[float]], numpy.ndarray], df: Union[int, List[int], numpy.ndarray], samples: int, seed: int = 0, chunks: Union[None, int, Tuple[int, int], Tuple[Tuple[int, ...], Tuple[int, ...]]] = None, rng: str = 'Mersenne Twister') → Union[numpy.ndarray, dask.array.core.Array]

Student T Copula / IT Copula scenario generator.

Simplified algorithm:

>>> l = numpy.linalg.cholesky(cov)
>>> y = numpy.random.standard_normal(size=(samples, cov.shape))
>>> p = (l @ y.T).T  # Gaussian Copula
>>> r = numpy.random.uniform(size=(samples, 1))
>>> s = scipy.stats.chi2.ppf(r, df=df)
>>> z = numpy.sqrt(df / s) * p
>>> u = scipy.stats.t.cdf(z, df=df)
>>> t = scipy.stats.norm.ppf(u)

Parameters
• cov (numpy.ndarray) – covariance matrix, a.k.a. correlation matrix. It must be a Hermitian, positive-definite matrix in any square array-like format. The width of cov determines the number of dimensions of the output.

• df – Number of degrees of freedom. Can be either a scalar int for Student T Copula, or a one-dimensional array-like with one point per dimension for IT Copula.

• samples (int) –

Number of random samples to generate

Note

When using Sobol, to obtain a uniform distribution one must use $$2^{n} - 1$$ samples (for any n > 0).

• chunks

Chunk size for the return array, which has shape (samples, dimensions). It can be anything accepted by dask (a positive integer, a tuple of two ints, or a tuple of two tuples of ints) for the output shape.

Set to None to return a numpy array.

Warning

When using the Mersenne Twister random generator, the chunk size changes the random sequence. To guarantee repeatability, it must be fixed together with the seed. chunks=None also produces different results from using dask.

• seed (int) –

Random seed.

With rng='Sobol', this is the initial dimension; when generating multiple copulas with different seeds, one should never use seeds that are less than cov.shape + 1 apart from each other.

The maximum seed when using sobol is:

pyscenarios.sobol.max_dimensions() - cov.shape - 2


• rng (str) – Either Mersenne Twister or Sobol

Returns

array of shape (samples, dimensions), with all series being normal (0, 1) distributions.

Return type

If chunks is not None, dask.array.Array; else numpy.ndarray