torchvinecopulib.vinecop package

Module contents

torchvinecopulib.vinecop

Provides VineCop (torch.nn.Module) for multivariate vine copula fitting, and sampling

  • Constructs and fits D-, C-, and R-vine copula structures via the Dissmann algorithm or user-specified tree matrices.

  • Optinally handles marginals with 1D KDE via kdeCDFPPF1D.

  • Employs pairwise bivariate copulas (BiCop).

  • Supports a variety of dependence measures (ENUM_FUNC_BIDEP) such as Kendall’s τ and Chatterjee’s ξ for edge weighting.

  • Offers device-agnostic .fit(), .log_pdf(), .cdf(), .sample(), and visualization helpers (.draw_lv(), .draw_dag()).

Key Features

  • Modular design: ModuleDict of bivariate copulas + ModuleList of marginals.

  • Lazy pseudo-obs: Efficient on-the-fly computation of h-functions.

  • Structure learning: MST-based tree construction per vine level (DVine/CVine/RVine).

  • Sampling: Inverse Rosenblatt using reference counting and ITP root-finding.

  • Visualization: NetworkX-based plots of vine in trees and in DAGs.

Usage

>>> from torchvinecopulib.vinecop import VineCop
>>> vc = VineCop(num_dim=4, is_cop_scale=False, num_step_grid=128)
>>> vc.fit(obs=data_tensor, mtd_vine="rvine", mtd_bidep="chatterjee_xi")
>>> samples = vc.sample(num_sample=500)
>>> log_liks = vc.log_pdf(obs=data_tensor)

References

  • Dissmann, J., Brechmann, E. C., Czado, C., & Kurowicka, D. (2013). Selecting and estimating regular vine copulae and application to financial returns. Computational Statistics & Data Analysis, 59, 52-69.

  • Chang, B., & Joe, H. (2019). Prediction based on conditional distributions of vine copulas. Computational Statistics & Data Analysis, 139, 45-63.

  • Zhu, K., Kurowicka, D., & Nane, G. F. (2020). Common sampling orders of regular vines with application to model selection. Computational Statistics & Data Analysis, 142, 106811.

  • Czado, C., & Nagler, T. (2022). Vine copula based modeling. Annual Review of Statistics and Its Application, 9(1), 453-477.

class torchvinecopulib.vinecop.VineCop(num_dim: int, is_cop_scale: bool = False, num_step_grid: int = 128)[source]

Bases: Module

cdf(obs: Tensor, num_sample: int = 10007, seed: int = 42) → Tensor[source]

Estimate the multivariate CDF via Monte Carlo of the vine copula. Approximates C(u) = P(U ≤ u) by drawing num_sample Sobol samples in copula scale and computing the proportion that lie below obs.

Parameters:

  • obs (torch.Tensor) – Points at which to evaluate the CDF. Shape (num_obs, num_dim).

  • num_sample (int, optional) – number of samples to draw for approx. Defaults to 10007.

  • seed (int, optional) – random seed for Sobol engine. Defaults to 0.

Returns:

Estimated CDF values at the given observations. Shape (num_obs, 1).

Return type:

torch.Tensor

property device

Device of internal buffers.

draw_dag(sample_order: tuple[int, ...] = None, title: str = 'Vine comp graph', font_size_vertex: int = 8, f_path: Path = None, fig_size: tuple = None) → tuple[source]

Draw the computational graph (DAG) of the vine copula. Creates a directed graph where edges flow from upstream pseudo‐obs and bicop modules to downstream pseudo‐obs, laid out by vine levels.

Parameters:

  • sample_order (tuple[int, ...], optional) – Variable sampling order. Defaults to self.sample_order.

  • title (str, optional) – Title of the plot. Defaults to “Vine comp graph”.

  • font_size_vertex (int, optional) – Font size for vertex labels. Defaults to 8.

  • f_path (Path, optional) – Path to save the figure. If provided, the figure will be saved. Defaults to None.

  • fig_size (tuple, optional) – Figure size. Defaults to None.

Raises:

ImportError – If matplotlib or networkx is not installed.

Returns:

Figure, axis, graph object, and file path (if saved).

Return type:

tuple

draw_lv(lv: int = 0, is_bcp: bool = True, title: str | None = None, num_digit: int = 2, font_size_vertex: int = 8, font_size_edge: int = 7, f_path: Path = None, fig_size: tuple = None) → tuple[source]

Draw the weighted undirected graph at a single level of the vine copula. Constructs a NetworkX graph of bivariate‐copula edges at level lv, where nodes represent either raw variables (lv=0), parent‐copula modules, or pseudo‐observations, and edge widths encode dependence strength.

Parameters:

  • lv (int, optional) – Level to draw. Defaults to 0.

  • is_bcp (bool, optional) – If True, nodes are parent‐bicop “l,r;s”. Otherwise, nodes are pseudo‐obs “v|s”. Defaults to True.

  • title (str | None, optional) – Title of the plot. Defaults to f"Vine level {lv}".

  • num_digit (int, optional) – Number of decimal digits for edge weights. Defaults to 2.

  • font_size_vertex (int, optional) – Font size for vertex labels. Defaults to 8.

  • font_size_edge (int, optional) – Font size for edge labels. Defaults to 7.

  • f_path (Path, optional) – Path to save the figure. Defaults to None.

  • fig_size (tuple, optional) – Figure size. Defaults to None.

Raises:

ImportError – If matplotlib or networkx is not installed.

Returns:

Figure, axis, graph object, and file path (if saved).

Return type:

tuple

property dtype

Data type of internal buffers.

fit(obs: Tensor, is_dissmann: bool = True, matrix: Tensor = None, first_tree_vertex: tuple = (), mtd_vine: str = 'rvine', mtd_bidep: str = 'chatterjee_xi', thresh_trunc: None | float = 0.01, mtd_kde: str = 'fastKDE', mtd_tll: str = 'constant', num_iter_max: int = 17, is_tau_est: bool = False, num_step_grid_kde1d: int = None, **kde_kwargs) → None[source]

Fit the VineCop object to multivariate data. Learns both the vine structure (via Dissmann’s greedy MST or a provided matrix) and fits all bivariate copulas and 1D marginals (if needed).

Parameters:

  • obs (torch.Tensor) – observations of shape (num_obs, num_dim). If is_cop_scale=False, raw data; otherwise assumed already uniform.

  • is_dissmann (bool, optional) – if True, use Dissmann’s algorithm to learn the vine structure. Otherwise, use the provided matrix. Defaults to True.

  • matrix (torch.Tensor, optional) – matrix representation of the vine structure. Defaults to None.

  • first_tree_vertex (tuple, optional) – vertices of the first tree (set of conditioning variables). Defaults to ().

  • mtd_vine (str, optional) – method for vine structure. One of “cvine”, “dvine”, “rvine”. Defaults to “rvine”.

  • mtd_bidep (str, optional) – method for bivariate dependence. One of “chatterjee_xi”, “ferreira_tail_dep_coeff”, “kendall_tau”, “mutual_info”, “spearman_rho”. Defaults to “chatterjee_xi”.

  • thresh_trunc (None | float, optional) – threshold for truncating bivariate copulas using p-val from Kendall’s tau stats test. Defaults to 0.01.

  • mtd_kde (str, optional) – method for bicop KDE. One of “fastKDE” or “tll”. Defaults to “fastKDE”.

  • mtd_tll (str, optional) – fit method for the transformation local-likelihood (TLL) nonparametric family, one of (“constant”, “linear”, or “quadratic”). Defaults to “constant”.

  • num_iter_max (int, optional) – num of Sinkhorn/IPF iters for grid normalization, used only when mtd_kde is “fastKDE”. Defaults to 17.

  • is_tau_est (bool, optional) – If True, compute and store Kendall’s τ inside BiCop. Defaults to False.

  • num_step_grid_kde1d (int, optional) – Grid resolution for each marginal KDE. Defaults to None.

  • **kde_kwargs – additional keyword arguments for kdeCDFPPF1D.

Raises:

ValueError – if mtd_vine is not one of “cvine”, “dvine”, or “rvine”.

forward(x: Tensor) → Tensor[source]

Neg average log-likelihood function for the given observations.

Parameters:

x (torch.Tensor) – Points at which to evaluate. Shape (num_obs, num_dim).

Returns:

scalar loss value.

Return type:

torch.Tensor

log_pdf(obs: Tensor) → Tensor[source]

Compute the log-density function of the vine copula at the given observations (including marginals).

Parameters:

obs (torch.Tensor) – Points at which to evaluate the log-density function. Shape (num_obs, num_dim).

Returns:

Log-density function values at the given observations. Shape (num_obs, 1).

Return type:

torch.Tensor

property matrix: Tensor
Matrix representation of the vine. Diagonal elements form the sampling order.

Read in row-wise: a row of (0,1,3,4,2) indicates a source vertex (0|1,2,3,4) and bicops (fix the leftmost, move ; from right to left) including (0,2;), (0,4;2), (0,3;2,4), and (0,1;2,3,4).

Returns:

Matrix representation of the vine.

Return type:

torch.Tensor

static ref_count_hfunc(num_dim: int, struct_obs: list, sample_order: tuple) → tuple[dict, list, int][source]

Count references of pseudo-obs, identify source vertices, and count number of hfuncs.

Parameters:

  • num_dim (int) – number of dimensions in the vine.

  • struct_obs (list) – structure of pseudo observations. (parents)

  • sample_order (tuple) – sampling order.

Returns:

reference counts of pseudo-obs, list of source vertices, and number of hfuncs.

Return type:

tuple[dict, list, int]

reset() → None[source]

Reset the VineCop object to its initial state.

rosenblatt(obs: Tensor, sample_order: tuple | None = None) → Tensor[source]

Compute the Rosenblatt transform of observations.

Maps input obs into uniform pseudo‐observations via successive conditional CDFs (Rosenblatt). # TODO, needs grad as residuals

sample(num_sample: int = 1000, seed: int = 42, is_sobol: bool = False, sample_order: tuple[int, ...] | None = None, dct_v_s_obs: dict[tuple[int, ...], Tensor] | None = None) → Tensor[source]

Draw random samples from the fitted vine copula via inverse Rosenblatt.

Generates num_sample joint samples in original or copula scale by (1) sampling independent uniforms for each “source” pseudo-obs, (2) recursively applying h-functions and their inverses following the vine structure, and (3) optionally transforming back through 1D marginal PPFs.

Parameters:

  • num_sample (int, optional) – number of samples to draw. Defaults to 1000.

  • seed (int, optional) – random seed for RNG or Sobol engine. Defaults to 42.

  • is_sobol (bool, optional) – if True, use Sobol engine for quasi-random sampling. Defaults to False.

  • sample_order (tuple[int, ...] | None, optional) – custom sampling order. Defaults to None and uses self.sample_order.

  • dct_v_s_obs (dict[tuple[int, ...], torch.Tensor] | None, optional) – dict mapping tuple(idx|conding set)->pseudo-obs. Defaults to None. User-provided pseudo-obs to initialize the sampling process. Notice if is_cop_scale=False, CDF/PPF will only be applied to the top level marginals. Pseudo-obs at deeper levels are assumed to be in copula scale [0,1].

Returns:

sampled observations in original scale if self.is_cop_scale=False, otherwise in [0,1]^d.

Return type:

torch.Tensor