covmats.SparseCholeskyFactor.colorize#

SparseCholeskyFactor.colorize(x: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]#

Perform a colorizing transformation on data.

“Colorizing” (“color” as in “colored noise”, in which different frequencies may have different magnitudes) transforms a set of uncorrelated random variables into a new set of random variables with the desired covariance. When a coloring transform is applied to a sample of points distributed according to a multivariate normal distribution with identity covariance and zero mean, the covariance of the transformed sample is approximately the covariance matrix used in the coloring transform [Wikipedia, 2025, Novak and Vorechovsky, 2019].

Parameters:

x (array_like) – An array of points. The last dimension must correspond with the dimensionality of the space, i.e., the number of columns in the covariance matrix.

Returns:

x_ – The transformed array of points.

Return type:

array_like

Note

We want to solve z.T = x @ K.T, where A = K @ K^{T} We use the cholesky factorization LDL’ = PA’AP’ with P’ = P^{-1} the permutation that makes the decomposition unique. So LD^{1/2} = PA’ and A = D^{1/2}L’P Finally z = (P’ L D^{1/2} x’)’

References

  1. Wikipedia. Whitening transformation. Wikipedia, August 2025.

  2. Lukas Novak and Miroslav Vorechovsky. Generalization of Coloring Linear Transformation. Transactions of the VŠB – Technical University of Ostrava, Civil Engineering Series, 2019. doi:10.31490/tces-2018-0013.

Examples

>>> import numpy as np
>>> import covmats
>>> rng = np.random.default_rng(1638083107694713882823079058616272161)
>>> n = 3
>>> A = rng.random(size=(n, n))
>>> cov_array = A @ A.T  # make matrix symmetric positive definite
>>> cholesky = np.linalg.cholesky(cov_array)
>>> cov_object = covmats.CovViaCholesky(cholesky)
>>> x = rng.multivariate_normal(np.zeros(n), np.eye(n), size=(10000))
>>> x_ = cov_object.colorize(x)
>>> cov_data = np.cov(x_, rowvar=False)
>>> np.allclose(cov_data, cov_array, rtol=3e-2)
True