Vine Denoising Copula (VDC)
Amortized vine copulas for high-dimensional density and information estimation
Paper · Documentation · Quick start · Pretrained models · Reproduce the paper
Vine copulas model high-dimensional dependence through a tree of bivariate pair-copulas, but classical fitting estimates every edge separately, which becomes the bottleneck as dimension grows. VDC trains one bivariate denoising network on simulated copulas and reuses it for every edge: it maps the empirical histogram of an edge to a density grid in a single forward pass, and an IPFP (Sinkhorn) projection restores uniform copula marginals. The fitted pair-copulas and their cached h-functions plug into standard vine recursion, so the model keeps an explicit, interpretable dependence structure while replacing repeated per-edge fitting with reusable neural inference.
What you can do with it
- Estimate a bivariate copula density from samples in milliseconds.
- Fit D-, C- and regular vines in high dimensions, with batched GPU inference.
- Evaluate likelihoods, draw samples (inverse Rosenblatt), and compute conditional transforms.
- Estimate mutual information and total correlation, decomposed by edge and by tree of the fitted vine.
- Train your own estimator on the included synthetic copula generators.
Results at a glance
From the NeurIPS 2026 paper (all numbers use the released vdc-denoiser-m64-v1):
| Bivariate density (9 in-library cases) | lower ISE than histogram, KDE and pyvine-TLL at ~6 ms per edge on a GPU; parametric family selection is more accurate on its own families at ~100x the cost |
| Families never seen in training | matches per-case TLL refits in held-out likelihood and roughly halves MI error |
| High-dimensional vines (d = 100–500) | 3.3–4.0x faster than 16-thread pyvine-TLL on one node (749 s vs 2,489 s at d = 500) |
| S&P100 daily returns (d = 100) | best held-out likelihood of the compared methods on random and chronological splits |
| Information estimation | fewer data-processing-inequality violations and lower additivity error than KSG; TC at d = 50 in 0.71 s |
Limits are reported alongside: the 64x64 grid bounds accuracy for near-deterministic pairs, and chained conditional prediction (VaR, imputation) is not yet competitive. See the paper and the reproduction guide for every protocol.
Installation
python -m pip install vine-denoising-copula
Python 3.11 or later with PyTorch 2 is required. A GPU is optional. The base install supports pretrained pair densities, vine fitting, likelihoods and sampling without pyvinecopulib or plotting/training packages. Optional features:
python -m pip install 'vine-denoising-copula[train]' # synthetic data and training
python -m pip install 'vine-denoising-copula[baselines]' # qualified pyvinecopulib 0.7.x
python -m pip install 'vine-denoising-copula[viz,data]' # plotting and dataset downloads
Install vine-denoising-copula, not the unrelated PyPI project vdc. Both
provide an import vdc namespace, so use separate virtual environments.
Checkpoints remain on Hugging Face and are downloaded and hash-verified on first
use. For a source installation:
git clone https://github.com/KempnerInstitute/vine-denoising-copula.git
cd vine-denoising-copula
python -m pip install -e '.[dev,train,data,viz]'
See getting started for CPU/GPU PyTorch installation. The paper reproduction environment retains its recorded dependency versions.
Quick start
import numpy as np
from vdc import load_pretrained_model, estimate_pair_density_from_samples, VineCopulaModel
bundle = load_pretrained_model("vdc-denoiser-m64-v1", device="cpu") # downloads and hash-checks
# 1) a bivariate copula density from pseudo-observations in [0, 1]^2
u = np.random.default_rng(0).uniform(size=(2000, 2))
density = estimate_pair_density_from_samples(bundle, u) # (64, 64) grid
# 2) a vine on d-dimensional pseudo-observations
x = np.random.default_rng(1).uniform(size=(2000, 8))
vine = VineCopulaModel(vine_type="dvine", m=64, device="cpu", batch_edges=True)
vine.fit(x, bundle.model, diffusion=bundle.diffusion)
loglik = vine.logpdf(x) # per-row log copula density
samples = vine.simulate(n=1000) # inverse-Rosenblatt sampling
Pseudo-observations are ranks scaled to (0, 1). Fit marginal transforms on training rows and apply them to held-out rows. More: examples/ and the user guide.
Pretrained models
| Model | Grid | Use | Status |
|---|---|---|---|
vdc-denoiser-m64-v1 |
64x64 | the estimator of all main paper results | released |
vdc-denoiser-m64-v2 |
64x64 | retrained linear-grid estimator VDC-64 (paper, Appendix G) | released |
vdc-denoiser-m128-v2 |
128x128 | retrained linear-grid estimator VDC-128 (paper, Appendix G) | released |
Every checkpoint is verified by SHA-256 on load. The v2 estimators were trained after the paper's
main experiments on corrected synthetic data; they use a continuous bilinear density with exact
h-functions and are selected with VineCopulaModel.from_pretrained(bundle). Their training
initialization is published as vdc-linear-grid-pilot.
See docs/MODEL_RELEASES.md and docs/IMPROVED_ESTIMATORS.md.
Train an estimator
# the released estimator (vdc-denoiser-m64-v1)
python scripts/train_unified.py --config configs/train/denoiser_cond_enhanced.yaml --model-type denoiser
# the retrained linear-grid estimators: pilot, data cache, then each fine-tune
python scripts/train_linear_grid_estimator.py configs/train/linear_grid_pilot.yaml
python scripts/train_linear_grid_estimator.py configs/train/linear_grid_cache.yaml
python scripts/train_linear_grid_estimator.py configs/train/linear_grid_vdc128_v2.yaml
Configurations and the synthetic training generators are documented in docs/CONFIGURATION.md and docs/TRAINING_DATA.md; the linear-grid recipes, their resources and verification are in docs/IMPROVED_ESTIMATORS.md.
Reproduce the paper
paper/ contains everything needed to reproduce the NeurIPS 2026
results: experiment runners with fixed protocols, the scripts and saved outputs that
regenerate every figure and table, and reference results. Figures and tables
rebuild from saved outputs on a laptop in minutes:
bash paper/figures/make_figures.sh output/figures
bash paper/tables/make_tables.sh output/tables
Repository layout
vdc/ library: models, projection (IPFP), vine fitting, sampling, information, training, data
configs/ training configurations
scripts/ command-line entry points (training, model and dataset downloads, packaging)
examples/ runnable examples
tests/ test suite (run with python -m pytest tests)
docs/ documentation (also served at kempnerinstitute.github.io/vine-denoising-copula)
paper/ NeurIPS 2026 reproduction: runners, figure and table generators, saved results
Citation
@inproceedings{safaai2026vdc,
title = {Amortized Vine Copulas for High-Dimensional Density and Information Estimation},
author = {Safaai, Houman},
booktitle = {Advances in Neural Information Processing Systems},
year = {2026},
note = {arXiv:2604.20568}
}
License
MIT; see LICENSE. This work was supported in part by a gift from the Chan Zuckerberg Initiative Foundation to establish the Kempner Institute for the Study of Natural and Artificial Intelligence at Harvard University.
Metadata
Release files for vine-denoising-copula 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vine_denoising_copula-0.4.0.tar.gz | 327.7 kB | Without provenance | Details for vine_denoising_copula-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vine_denoising_copula-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for vine_denoising_copula-0.4.0-py3-none-any.whl |
Total release size: 539.5 kB
Release files / vine_denoising_copula-0.4.0.tar.gz
| Download URL | vine_denoising_copula-0.4.0.tar.gz |
|---|---|
| Size | 327.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f7800e21bd9be1915a201f655b7845a82ac60a9885340164f56e643266f5804d
|
|
BLAKE2b-256 checksum How to use checksums |
5632598685d482b97bb146d5a63988b4976847d5094ad80c718696a1b6b6a935
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / vine_denoising_copula-0.4.0-py3-none-any.whl
| Download URL | vine_denoising_copula-0.4.0-py3-none-any.whl |
|---|---|
| Size | 211.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61bb5b86c0b763844d1cd072a99f6a220843da0840b8e93c85af178afd8bda23
|
|
BLAKE2b-256 checksum How to use checksums |
6a4db16c4bb21cd4f1f1eec692ff8a0099cda4b1d90220f693ff501b9aabba73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for vine-denoising-copula 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.