torchvinecopulib.util package

Module contents

torchvinecopulib.util

Utility routines for copula‐based dependence measures, 1D KDE CDF/PPF, and root-finding via the Interpolate Truncate and Project (ITP) method.

Decorators

  • torch.compile() for solve_ITP()

  • torch.no_grad() for solve_ITP(), kendall_tau(), mutual_info(), ferreira_tail_dep_coeff(), chatterjee_xi()

References

  • O’Brien, T. A., Kashinath, K., Cavanaugh, N. R., Collins, W. D., & O’Brien, J. P. (2016). A fast and objective multidimensional kernel density estimation method: fastKDE. Computational Statistics & Data Analysis, 101, 148-160.

  • O’Brien, T. A., Collins, W. D., Rauscher, S. A., & Ringler, T. D. (2014). Reducing the computational cost of the ECF using a nuFFT: A fast and objective probability density estimation method. Computational Statistics & Data Analysis, 79, 222-234.

  • Purkayastha, S., & Song, P. X. K. (2024). fastMI: A fast and consistent copula-based nonparametric estimator of mutual information. Journal of Multivariate Analysis, 201, 105270.

  • Ferreira, M. S. (2013). Nonparametric estimation of the tail-dependence coefficient.

  • Chatterjee, S. (2021). A new coefficient of correlation. Journal of the American Statistical Association, 116(536), 2009-2022.

  • Lin, Z., & Han, F. (2023). On boosting the power of Chatterjee’s rank correlation. Biometrika, 110(2), 283-299.

  • Oliveira, I. F., & Takahashi, R. H. (2020). An enhancement of the bisection method average performance preserving minmax optimality. ACM Transactions on Mathematical Software (TOMS), 47(1), 1-24.

class torchvinecopulib.util.ENUM_FUNC_BIDEP(value)[source]

Bases: Enum

Enum wrapper for bivariate dependence functions.

chatterjee_xi = <function chatterjee_xi>
ferreira_tail_dep_coeff = <function ferreira_tail_dep_coeff>
kendall_tau = <function kendall_tau>
mutual_info = <function mutual_info>
torchvinecopulib.util.chatterjee_xi(x: Tensor, y: Tensor, M: int = 1) → Tensor[source]

Estimate Chatterjee’s rank correlation coefficient (ξ)

  • Chatterjee, S. (2021). A new coefficient of correlation. Journal of the American Statistical Association, 116(536), 2009-2022.

  • Lin, Z., & Han, F. (2023). On boosting the power of Chatterjee’s rank correlation. Biometrika, 110(2), 283-299.

Parameters:

  • x (torch.Tensor) – shape (n, 1)

  • y (torch.Tensor) – shape (n, 1)

  • M (int, optional) – num of nearest-neighbor. Defaults to 1.

Returns:

Estimated Chatterjee’s rank correlation coefficient

Return type:

torch.Tensor

torchvinecopulib.util.ferreira_tail_dep_coeff(x: Tensor, y: Tensor) → Tensor[source]

Estimate tail dependence coefficient (λ), modifed from Ferreira’s method, symmetric for (x,y), (y,1-x), (1-x,1-y), (1-y,x), (y,x), (1-x,y), (1-y,1-x), (x,1-y).

  • Ferreira, M. S. (2013). Nonparametric estimation of the tail-dependence coefficient.

Parameters:

  • x (torch.Tensor) – shape (n, 1)

  • y (torch.Tensor) – shape (n, 1)

Returns:

Estimated tail dependence coefficient

Return type:

torch.Tensor

class torchvinecopulib.util.kdeCDFPPF1D(x: Tensor, num_step_grid: int = None, x_min: float = None, x_max: float = None, pad: float = 0.1)[source]

Bases: Module

cdf(x: Tensor) → Tensor[source]

Compute the CDF of the fitted KDE at x.

Parameters:

x (torch.Tensor) – Points at which to evaluate the CDF.

Returns:

CDF values at x, clamped to [0, 1].

Return type:

torch.Tensor

property device
property dtype
forward(x: Tensor) → Tensor[source]

Average negative log-likelihood of the fitted KDE at x.

Parameters:

x (torch.Tensor) – Points at which to evaluate the negative log-likelihood.

Returns:

Negative log-likelihood values at x, averaged over the batch.

Return type:

torch.Tensor

log_pdf(x: Tensor) → Tensor[source]

Compute the log PDF of the fitted KDE at x.

Parameters:

x (torch.Tensor) – Points at which to evaluate the log PDF.

Returns:

Log PDF values at x, guaranteed to be finite.

Return type:

torch.Tensor

pdf(x: Tensor) → Tensor[source]

Compute the PDF of the fitted KDE at x.

Parameters:

x (torch.Tensor) – Points at which to evaluate the PDF.

Returns:

PDF values at x, clamped to [0, ∞).

Return type:

torch.Tensor

ppf(q: Tensor) → Tensor[source]

Compute the PPF (quantile function) of the fitted KDE at q.

Parameters:

q (torch.Tensor) – Quantiles at which to evaluate the PPF.

Returns:

PPF values at q, clamped to [x_min, x_max].

Return type:

torch.Tensor

torchvinecopulib.util.kendall_tau(x: Tensor, y: Tensor) → Tensor[source]

Compute Kendall’s tau correlation coefficient and p-value. Moves inputs to CPU and delegates to SciPy’s kendalltau.

Parameters:

  • x (torch.Tensor) – shape (n, 1)

  • y (torch.Tensor) – shape (n, 1)

Returns:

Kendall’s tau correlation coefficient and p-value

Return type:

torch.Tensor

torchvinecopulib.util.mutual_info(x: Tensor, y: Tensor) → Tensor[source]

Estimate mutual information using fastKDE. Moves inputs to CPU and delegates to fastKDE.pdf.

  • O’Brien, T. A., Kashinath, K., Cavanaugh, N. R., Collins, W. D., & O’Brien, J. P. (2016). A fast and objective multidimensional kernel density estimation method: fastKDE. Computational Statistics & Data Analysis, 101, 148-160.

  • O’Brien, T. A., Collins, W. D., Rauscher, S. A., & Ringler, T. D. (2014). Reducing the computational cost of the ECF using a nuFFT: A fast and objective probability density estimation method. Computational Statistics & Data Analysis, 79, 222-234.

  • Purkayastha, S., & Song, P. X. K. (2024). fastMI: A fast and consistent copula-based nonparametric estimator of mutual information. Journal of Multivariate Analysis, 201, 105270.

Parameters:

  • x (torch.Tensor) – shape (n, 1)

  • y (torch.Tensor) – shape (n, 1)

Returns:

Estimated mutual information

Return type:

torch.Tensor

torchvinecopulib.util.solve_ITP(fun: callable, x_a: Tensor, x_b: Tensor, epsilon: float = 1e-10, num_iter_max: int = 31, k_1: float = 0.2) → Tensor[source]

Root-finding for fun via the Interpolate Truncate and Project (ITP) method within [x_a, x_b], with guaranteed average performance strictly better than the bisection method under any continuous distribution.

Parameters:

  • fun (callable) – function to find the root of.

  • x_a (torch.Tensor) – lower bound of the interval to search.

  • x_b (torch.Tensor) – upper bound of the interval to search.

  • epsilon (float, optional) – convergence tolerance. Defaults to _EPS.

  • num_iter_max (int, optional) – maximum number of iterations. Defaults to 31.

  • k_1 (float, optional) – scaling factor for the truncation step. Defaults to 0.2.

Returns:

approximated root of the function fun in the interval [x_a, x_b].

Return type:

torch.Tensor