torchvinecopulib.bicop package

Module contents

torchvinecopulib.bicop

Provides BiCop (torch.nn.Module) for estimating, evaluating, and sampling from bivariate copulas via tll or fastKDE approaches.

Decorators

  • torch.compile() for bilinear interpolation

  • torch.no_grad() for fit(), hinv_l(), hinv_r(), sample(), and imshow()

Key Features

  • Fits a copula density on a uniform [0,1]² grid and caches PDF/CDF/h‐functions

  • Device‐agnostic: all buffers live on the same device/dtype you fit on

  • Fast bilinear interpolation compiled with torch.compile

  • Convenient .cdf(), .pdf(), .hfunc_*(), .hinv_*(), and .sample() APIs

  • Plotting helpers: .imshow() and .plot(contour|surface)

Usage

>>> from torchvinecopulib.bicop import BiCop
>>> cop = BiCop(num_step_grid=256)
>>> cop.fit(obs)  # obs: Tensor of shape (n,2) in [0,1]²
>>> u = torch.rand(10, 2)
>>> cdf_vals = cop.cdf(u)
>>> samples = cop.sample(1000, is_sobol=True)

References

  • 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

class torchvinecopulib.bicop.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