randomcov

Generating random covariance and correlation matrices with beautiful geodesic interpolation visualizations! 🎯

Install

pip install randomcov

or for latest

pip install git+https://github.com/microprediction/randomcov.git

Example

from randomcov import random_covariance_matrix
cov = random_covariance_matrix(n=50, corr_method='residuals', var_method='lognormal')

Motivation

To collect standard but also novel correlation and covariance generation methods, in order to better understand when some estimation methods work better than others in different contexts: such as the construction of machine learning model ensembles, combinations of forecasts, or financial portfolios.

The geodesic interpolation capabilities enable smooth transformations between covariance structures while preserving mathematical properties, making it ideal for portfolio optimization and risk management applications.

Generator catalog

Every method: random_correlation_matrix(n, corr_method="<name>", corr_kwargs={...}). All generators accept rng= (int seed or numpy Generator) for reproducibility.

method	measure / structure	reference
`lkj`	LKJ(eta) via Cholesky factor; eta=1 uniform on the elliptope	Lewandowski, Kurowicka & Joe 2009
`onion`	extended onion, exact LKJ(eta)	Ghosh & Henderson 2003; LKJ 2009
`vine`	C-vine partial correlations, Beta margins (LKJ-exact)	Joe 2006
`archakov_hansen`	Gaussian in matrix-log space + unit-diagonal fixed point	Archakov & Hansen 2021
`spectrum`	prescribed random eigenvalues (exp / dirichlet / marchenko_pastur / spiked), Haar frame, Givens diagonal restoration	Bendel & Mickey 1978; Davies & Higham 2000; Johnstone 2001
`wishart`	normalized Wishart sample correlation	classical
`residuals`	sample correlation of residual-driven paths	this package
`factor`	k factors + idiosyncratic, optional sparse links	approximate-factor literature
`hierarchical`	ultrametric / cophenetic from a random dendrogram	Tumminello, Lillo & Mantegna
`block_equicorr`	constant within/between blocks (DECO, block form)	Engle & Kelly 2012
`ar1`	Toeplitz rho^	i-j
`kernel`	RBF / Matern field on a random point cloud	spatial statistics
`sparse_precision`	random Gaussian graphical model (sparse inverse)	graphical-model literature
`walk`	perturbation random walk on the elliptope, nearest-corr projected	this package
`animals`	agent-based interacting sizes (emergent correlation)	this package

There is no canonical "uniform" measure over covariance matrices, and the elliptope-uniform (LKJ eta=1) concentrates on weak correlations as n grows; robust conclusions require batteries across NAMED ensembles, which is what this catalog is for.

Correlation Inflation

An example of the kind of thing I wish to test against generative models.

Correlation Inflation: A Working Paper

The transformation preserves geometric properties while smoothly interpolating towards perfect correlation structure using differential geometry on the manifold of positive definite matrices.

Geodesic Interpolation Towards Perfect Correlation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

randomcov-0.1.0.tar.gz (23.9 kB view details)

Uploaded Aug 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

randomcov-0.1.0-py3-none-any.whl (32.0 kB view details)

Uploaded Aug 27, 2026 Python 3

File details

Details for the file randomcov-0.1.0.tar.gz.

File metadata

Download URL: randomcov-0.1.0.tar.gz
Upload date: Aug 27, 2026
Size: 23.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for randomcov-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`6270452a8d59bc120254f7d6ca747ad1184e439b3bd72230752ca6106f7b6882`
MD5	`93e293d3ee42f84828b48097771dddee`
BLAKE2b-256	`08d72d3dd755dd7548a91196d2d622e3c7d068af301cbdc82b5810ae75753dd4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for randomcov-0.1.0.tar.gz:

Publisher: deploy.yml on microprediction/randomcov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: randomcov-0.1.0.tar.gz
- Subject digest: 6270452a8d59bc120254f7d6ca747ad1184e439b3bd72230752ca6106f7b6882
- Sigstore transparency entry: 2617657516
- Sigstore integration time: Aug 27, 2026
Source repository:
- Permalink: microprediction/randomcov@2f0068654823b78b2ea593f00b7a5a69c6fa2651
- Branch / Tag: refs/tags/v0.1.0
- Owner: https://github.com/microprediction
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: deploy.yml@2f0068654823b78b2ea593f00b7a5a69c6fa2651
- Trigger Event: release