API reference

Start with the functions exported by vdc. Examples assume the package is installed and inputs are finite arrays of continuous pseudo-observations in [0, 1]. Raw-data transforms are described in the user guide.

Pretrained models

from vdc import load_pretrained_model, estimate_pair_density_from_samples

bundle = load_pretrained_model("vdc-denoiser-m64-v1", device="cpu")
density = estimate_pair_density_from_samples(bundle, pair_data)
Function Arguments and result
load_pretrained_model model_id="vdc-denoiser-m64-v1", keyword arguments device=None, cache_dir=None, force_download=False, prefer_local=True, repo_id=None, revision=None, checkpoint_path=None (a local copy, checked against the manifest's SHA-256); returns a LoadedPretrainedModel.
load_checkpoint_bundle A trusted checkpoint_path, keyword device=None; loads a local unified-trainer checkpoint.
resolve_pretrained_checkpoint The same model/download options, without device; returns a verified checkpoint Path.
estimate_pair_density_from_samples bundle, an (n, 2) array, keywords m=None, diffusion_steps=None, cfg_scale=1.0, projection_iters=None (50 for vdc-denoiser-m64-v1; the recorded setting for linear-grid models); returns an (m, m) density grid (node values for linear-grid models).
estimate_pair_copula_from_samples bundle of a linear-grid model (vdc-denoiser-m64-v2, vdc-denoiser-m128-v2) and an (n, 2) array; returns a LinearGridCopula with pdf, h_u_given_v, h_v_given_u and their exact inverses.
estimate_pair_copulas_from_samples The batched form for a list of (n, 2) arrays.
list_pretrained_models() Returns the packaged model manifests.
load_pretrained_manifest(model_id) Returns one packaged manifest.

A bundle contains model, diffusion, config, device, model_id, checkpoint_path and manifest. diffusion is None for the released single-pass denoiser. device=None selects CUDA when available; choose an explicit device for reproducible resource use. The loader verifies the public checkpoint's SHA-256. See pretrained models for caching.

The grid uses cell centers (i + 0.5) / m. Values are densities, not cell probabilities: on a uniform grid, the mass is density.sum() / m**2. Projection corrects grid marginals to finite numerical tolerance.

VineCopulaModel

VineCopulaModel.from_pretrained(bundle, vine_type="dvine", **overrides) builds a vine with the inference settings recorded for a loaded model: for linear-grid models it selects pair_estimator="linear_grid", the grid size, projection solver, conditional clipping and batch size used in the paper's evaluation; for other models it sets the model's grid size and the bundle's device and keeps the defaults. Keyword arguments override any setting.

from vdc import VineCopulaModel

vine = VineCopulaModel(
    vine_type="dvine", m=64, device="cpu",
    batch_edges=True, edge_batch_size=16,
)
vine.fit(train_u, bundle.model, diffusion=bundle.diffusion, verbose=False)
log_density = vine.logpdf(test_u)

Constructor defaults in the library are:

VineCopulaModel(
    vine_type="rvine", order=None, truncation_level=None, m=64,
    device="cuda", diffusion_steps=50, cfg_scale=1.0, projection_iters=50,
    pred_noise_clip=10.0, hfunc_use_spline=True, batch_edges=False,
    edge_batch_size=256, gpu_histogram=True,
    hfunc_vectorized_inverse=False, fast_fit=False,
)

Select vine_type and device explicitly. order gives the D-vine order or C-vine root order; None selects it from the data. truncation_level=None fits all d - 1 trees. m must match the estimator's grid.

batch_edges=True enables batches within D/C-vine trees for single-pass models; R-vine fitting evaluates edges individually. Trees remain sequential. fast_fit=True enables the qualified execution optimizations described in optimized fitting. Neither option changes the network weights.

Method Behavior
fit(U, diffusion_model, diffusion=None, verbose=True) Fits structure and pair densities to (n, d) inputs.
logpdf(U), pdf(U) Return one copula log density or density per row.
logpdf_decomposed(U) Returns per_sample, mean_total, per_tree_mean and per_edge_mean.
simulate(n, seed=None) Draws (n, d) samples for supported D/C-vines. A supplied seed resets NumPy's global random state.
rosenblatt(U), inverse_rosenblatt(W) Forward and inverse transforms for supported D/C-vines.
prepare_sampler(...) Prepares a reusable sampler with automatic compiled/NumPy selection; see sampling.
summary() Returns the fitted dimension, tree/edge counts, type, order, truncation and grid size.
get_structure_matrix() Returns the fitted vine matrix.
save(path), VineCopulaModel.load(path) Save/load a fitted model with pickle. Load only files you trust.

General R-vine density fitting is supported; general R-vine sampling is not. fit_from_matrix(U, vine_matrix, diffusion_model, diffusion, verbose=True) uses the diagonal order for D/C-vines. The R-vine path selects its own structure; it does not enforce an arbitrary supplied matrix.

Grid transforms and information

Function or object Interface
vdc.models.hfunc.HFuncLookup Construct from an (m, m) density grid; optional use_spline=True, vectorized_inverse=False, vectorized_tables=False.
HFuncLookup.h_u_given_v(u, v) Conditional CDF of u given v.
HFuncLookup.h_v_given_u(v, u) Conditional CDF of v given u; note the argument order.
HFuncLookup.hinv_u_given_v(q, v) Inverse conditional CDF of u given v.
HFuncLookup.hinv_v_given_u(q, u) Inverse conditional CDF of v given u.
HFuncLookup.pdf(u, v) Interpolated pair density.
vdc.models.projection.copula_project Projects a tensor density grid; iters=30, eps=1e-8, method="sinkhorn", optional marginal targets.
vdc.utils.metrics.mutual_information_from_density_grid Accepts a Torch density tensor and computes grid-integrated MI in nats.
vdc.utils.information.ksg_mutual_information x, y, k=5, seed=None with keyword-only k and seed; KSG MI in nats.
vdc.data.tabular.EmpiricalMarginals fit(X_train), then transform(X) or inverse_transform(U).

The continuous density interpolation and cached conditional tables are approximate counterparts. Grid projection does not imply exact normalization or calibration of the complete interpolated vine.

Command line

vdc list-models
vdc resolve-model --model-id vdc-denoiser-m64-v1
vdc estimate-pair pair.npy --output density.npy --device cpu
vdc fit-vine pseudo_obs.npy --output vine.pkl --vine-type dvine --device cpu

Array inputs may be .npy, comma-separated .csv or whitespace-separated .txt files. Use vdc COMMAND --help for the complete options. These commands expect pseudo-observations, not untransformed raw measurements.

Advanced models

vdc.GridUNet and vdc.CopulaAwareDiffusion support iterative diffusion checkpoints. They are not the released single-pass denoiser. Use load_checkpoint_bundle to reconstruct an architecture from its checkpoint, rather than guessing constructor arguments. Training options are in configuration.