torchvinecopulib package¶
Subpackages¶
Module contents¶
- class torchvinecopulib.BiCop(num_step_grid: int = 128)[source]¶
Bases:
Module
- cdf(obs: Tensor) Tensor [source]¶
Evaluate the copula CDF at given points. For independent copula, returns u₁·u₂.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the CDF (rows are (u₁,u₂)), shape (n,2).
- Returns:
CDF values at each observation, shape (n,1).
- Return type:
torch.Tensor
- property device: device¶
Get the device of the bicop model (all internal buffers).
- Returns:
The device on which the registered buffers reside.
- Return type:
torch.device
- property dtype: dtype¶
Get the data type of the bicop model (all internal buffers). Should be torch.float64.
- Returns:
The data type of the registered buffers.
- Return type:
torch.dtype
- fit(obs: Tensor, is_tll: bool = True, mtd_tll: str = 'constant', num_iter_max: int = 17, is_tau_est: bool = False) None [source]¶
Estimate and cache PDF/CDF/h-function grids from bivariate copula observations.
This method computes KDE-based bicopula densities on a uniform [0,1]² grid and populates internal buffers (
_pdf_grid
,_cdf_grid
,_hfunc_l_grid
,_hfunc_r_grid
,negloglik
).Nagler, T., Schellhase, C., & Czado, C. (2017). Nonparametric estimation of simplified vine copula models: comparison of methods. Dependence Modeling, 5(1), 99-120.
O’Brien, T. A., Kashinath, K., Cavanaugh, N. R., Collins, W. D. & O’Brien, J. P. A fast and objective multidimensional kernel density estimation method: fastKDE. Comput. Stat. Data Anal. 101, 148–160 (2016). http://dx.doi.org/10.1016/j.csda.2016.02.014
O’Brien, T. A., Collins, W. D., Rauscher, S. A. & Ringler, T. D. Reducing the computational cost of the ECF using a nuFFT: A fast and objective probability density estimation method. Comput. Stat. Data Anal. 79, 222–234 (2014). http://dx.doi.org/10.1016/j.csda.2014.06.002
- Parameters:
obs (torch.Tensor) – shape (n, 2) bicop obs in [0, 1]².
is_tll (bool, optional) – Using tll or fastKDE. Defaults to True (tll).
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
is_tll=False
. Defaults to 17.is_tau_est (bool, optional) – If True, compute and store Kendall’s τ. Defaults to
False
.
- hfunc_l(obs: Tensor) Tensor [source]¶
Evaluate the left h-function at given points. Computes H(u₂ | u₁):= ∂/∂u₁ C(u₁,u₂) for the fitted copula. For independent copula, returns u₂.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the left h-function (rows are (u₁,u₂)), shape (n,2).
- Returns:
Left h-function values at each observation, shape (n,1).
- Return type:
torch.Tensor
- hfunc_r(obs: Tensor) Tensor [source]¶
Evaluate the right h-function at given points. Computes H(u₁ | u₂):= ∂/∂u₂ C(u₁,u₂) for the fitted copula. For independent copula, returns u₁.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the right h-function (rows are (u₁,u₂)), shape (n,2).
- Returns:
Right h-function values at each observation, shape (n,1).
- Return type:
torch.Tensor
- hinv_l(obs: Tensor) Tensor [source]¶
Invert the left h‐function via root‐finding: find u₂ given (u₁, p). Solves H(u₂ | u₁) = p by ITP between 0 and 1.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the left h-function (rows are (u₁,u₂)), shape (n,2).
- Returns:
Solutions u₂ ∈ [0,1], shape (n,1).
- Return type:
torch.Tensor
- hinv_r(obs: Tensor) Tensor [source]¶
Invert the right h‐function via root‐finding: find u₁ given (u₂, p). Solves H(u₁ | u₂) = p by ITP between 0 and 1.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the right h-function (rows are (u₁,u₂)), shape (n,2).
- Returns:
Solutions u₁ ∈ [0,1], shape (n,1).
- Return type:
torch.Tensor
- imshow(is_log_pdf: bool = False, ax: Axes | None = None, cmap: str = 'inferno', xlabel: str = '$u_{left}$', ylabel: str = '$u_{right}$', title: str = 'Estimated bivariate copula density', colorbartitle: str = 'Density', **imshow_kwargs: dict) tuple[Figure, Axes] [source]¶
Display the (log-)PDF grid as a heatmap.
- Parameters:
is_log_pdf (bool, optional) – If True, plot log-PDF. Defaults to False.
ax (plt.Axes, optional) – Matplotlib Axes object to plot on. If None, a new figure and axes are created. Defaults to None.
cmap (str, optional) – Colormap for the plot. Defaults to “inferno”.
xlabel (str, optional) – X-axis label. Defaults to r”$u_{left}$”.
ylabel (str, optional) – Y-axis label. Defaults to r”$u_{right}$”.
title (str, optional) – Plot title. Defaults to “Estimated bivariate copula density”.
colorbartitle (str, optional) – Colorbar title. Defaults to “Density”.
**imshow_kwargs – Additional keyword arguments for imshow.
- Returns:
The figure and axes objects.
- Return type:
tuple[plt.Figure, plt.Axes]
- log_pdf(obs: Tensor) Tensor [source]¶
Evaluate the copula log-PDF at given points, with safe handling of inf/nan. For independent copula, returns 0.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the log-PDF (rows are (u₁,u₂)), shape (n,2).
- Returns:
log-PDF values at each observation, shape (n,1).
- Return type:
torch.Tensor
- pdf(obs: Tensor) Tensor [source]¶
Evaluate the copula PDF at given points. For independent copula, returns 1.
- Parameters:
obs (torch.Tensor) – Points in [0,1]² where to evaluate the PDF (rows are (u₁,u₂)), shape (n,2).
- Returns:
PDF values at each observation, shape (n,1).
- Return type:
torch.Tensor
- plot(plot_type: str = 'surface', margin_type: str = 'unif', xylim: tuple[float, float] | None = None, grid_size: int | None = None) tuple[Figure, Axes] [source]¶
Plot the bivariate copula density.
- Parameters:
plot_type (str, optional) – Type of plot, either “contour” or “surface”. Defaults to “surface”.
margin_type (str, optional) – Type of margin, either “unif” or “norm”. Defaults to “unif”.
xylim (tuple[float, float], optional) – Limits for x and y axes. Defaults to None.
grid_size (int, optional) – Size of the grid for the plot. Defaults to None.
- Returns:
The figure and axes objects.
- Return type:
tuple[plt.Figure, plt.Axes]
- reset() None [source]¶
Reinitialize state and zero all statistics and precomputed grids.
Sets the bicop back to independent bicop and clears accumulated metrics (
tau
,num_obs
,negloglik
) as well as all grid buffers (_pdf_grid
,_cdf_grid
,_hfunc_l_grid
,_hfunc_r_grid
).
- sample(num_sample: int = 100, seed: int = 42, is_sobol: bool = False) Tensor [source]¶
Sample from the copula by inverse Rosenblatt transform. Uses Sobol sequence if
is_sobol=True
, otherwise uniform RNG. For independent copula, returns uniform samples in [0,1]².- Parameters:
num_sample (int, optional) – number of samples to generate. Defaults to 100.
seed (int, optional) – random seed for reproducibility. Defaults to 42.
is_sobol (bool, optional) – If True, use Sobol sampling. Defaults to False.
- Returns:
Generated samples, shape (num_sample, 2).
- Return type:
torch.Tensor
- class torchvinecopulib.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 belowobs
.- 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, is_tll: bool = False, 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.
is_tll (bool, optional) – Using
tll
orfastKDE
. Defaults to False (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 is_tll=False. 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]
- 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