User guide

VDC separates continuous marginal distributions from their dependence. It estimates pair-copula densities with a pretrained network, then combines them in a simplified vine. The same fitted vine supports density evaluation, sampling and an edge-level information decomposition.

Transform raw data without leaking test observations

Split observations before fitting the marginal transform:

import numpy as np
from vdc.data.tabular import EmpiricalMarginals, train_test_split

X = np.load("measurements.npy")  # finite array, shape (rows, variables)
X_train, X_test = train_test_split(X, test_frac=0.2, seed=42)
marginals = EmpiricalMarginals.fit(X_train)
train_u = marginals.transform(X_train)
test_u = marginals.transform(X_test)

Use a chronological split for time series. Handle missing values explicitly before fitting. Ties and discrete variables need additional modeling choices; the released estimator assumes continuous marginals.

EmpiricalMarginals uses right-sided training ranks and (rank + 0.5)/(n + 1), clipped away from the endpoints. Its inverse is a nearest-rank empirical quantile, not a smooth parametric marginal model.

Load the reusable pair estimator

from vdc import load_pretrained_model, estimate_pair_density_from_samples

bundle = load_pretrained_model("vdc-denoiser-m64-v1", device="cpu")
pair_density = estimate_pair_density_from_samples(bundle, train_u[:, :2])

The grid is 64 × 64 for this checkpoint. Loading downloads the weights on the first use, verifies their hash and caches them. The model has about 133 million parameters; allow several GB of RAM, or GPU memory when using device="cuda".

Fit and evaluate a vine

from vdc import VineCopulaModel

vine = VineCopulaModel(
    vine_type="dvine", m=64, device=str(bundle.device),
    batch_edges=True, edge_batch_size=16,
)
vine.fit(train_u, bundle.model, diffusion=bundle.diffusion, verbose=False)
mean_log_density = float(vine.logpdf(test_u).mean())
print(vine.summary())

The log density is in copula space. A raw-data likelihood also needs the marginal log densities; empirical ranks alone do not provide those densities.

D-vines and C-vines support fitting and the implemented sampling paths. R-vines support density fitting but not general inverse-Rosenblatt sampling. For large D-vines, consult optimized fitting; batching is opt-in, and changing batch size or numerical precision can affect floating-point results.

Generate observations

samples_u = vine.simulate(1000, seed=42)
samples_x = marginals.inverse_transform(samples_u)

For repeated sampling, vine.prepare_sampler(backend="auto") can build a compiled D-vine sampler, with an automatic NumPy fallback. Supported structures, interpolation settings, thread controls and memory limits are described in compiled sampling.

Inspect information contributions

import torch
from vdc.utils.metrics import mutual_information_from_density_grid

mi = float(mutual_information_from_density_grid(torch.as_tensor(pair_density)))
parts = vine.logpdf_decomposed(test_u)
print("Pair MI (nats):", mi)
print("Held-out mean log copula density (nats):", parts["mean_total"])
print("Tree contributions:", parts["per_tree_mean"])

For a correctly specified population copula, the expected log density is total correlation. A fitted held-out estimate includes sampling and model error; individual fitted contributions may be negative. It is not causal attribution.

Save a fitted model

vine.save("vine.pkl")
restored = VineCopulaModel.load("vine.pkl")

Save the marginal transform and preprocessing choices separately. Pickles and Torch checkpoints can execute code when loaded: use trusted artifacts. Compiled sampler handles are not serialized; prepare a new handle after loading.

Choosing settings

  • Keep the grid size consistent with the checkpoint. A denser grid is not a substitute for a model trained and evaluated for that representation.
  • Increase projection_iters when marginal residuals matter, and measure them.
  • Start with small edge batches on a CPU or limited-memory GPU.
  • Choose truncation from training/validation data, not the test set.
  • Evaluate conditional predictions for the intended task; good joint likelihood alone does not establish imputation or tail-risk calibration.

For benchmark protocols, use the paper reproduction guide. Its fixed settings and release pins should not be inferred from library defaults.