Copulas
The solow-copula crate provides bivariate copulas for dependence
modeling: the elliptical GaussianCopula and StudentTCopula, and the
Archimedean ClaytonCopula, GumbelCopula, and FrankCopula. Each copula is
a small value type parameterized by its dependence parameter, exposing a copula
density (pdf), and — where a closed form is available — a cdf and the
implied rank correlations. Two free functions, kendalls_tau and
spearmans_rho, compute the corresponding sample statistics from paired data.
Scope note: unlike the reference, which models copulas in arbitrary dimension and offers random sampling and likelihood fitting, this crate is deliberately bivariate and closed-form. It supplies densities, the Gaussian CDF, the analytic tau/rho mappings, and sample rank correlations — not a sampler or an MLE fitter. Parameters are recovered by inverting the Kendall's-tau relation (method of moments) instead.
Background
A bivariate copula is the joint CDF of a pair of \(\mathrm{Uniform}(0,1)\) margins. By Sklar's theorem, any continuous bivariate distribution \(H\) factors as
\[ H(s, t) ;=; C\big(F(s),, G(t)\big), \]
where \(F, G\) are the marginal CDFs and \(C:[0,1]^2 \to [0,1]\) is a unique copula. The copula isolates the dependence structure from the margins. Writing \(u = F(s)\) and \(v = G(t)\), the copula density is \(c(u,v) = \partial^2 C / \partial u,\partial v\).
Elliptical copulas are built from an elliptical joint law via the quantile transform. The Gaussian copula uses \(x = \Phi^{-1}(u)\), \(y = \Phi^{-1}(v)\) and a correlation \(\rho\):
\[ c_{\mathrm{Ga}}(u,v) = \frac{\phi_2(x, y;, \rho)}{\phi(x),\phi(y)} = \frac{1}{\sqrt{1-\rho^2}} \exp!\left(-\frac{\rho^2(x^2+y^2) - 2\rho x y}{2,(1-\rho^2)}\right), \]
with CDF \(C_{\mathrm{Ga}}(u,v) = \Phi_2\big(\Phi^{-1}(u), \Phi^{-1}(v);\rho\big)\), where \(\Phi_2\) is the standard bivariate-normal CDF. The Student-t copula replaces \(\Phi^{-1}\) by the \(t_\nu\) quantile and \(\phi_2\) by the bivariate-\(t\) density with shape matrix \(R = [[1, \rho], [\rho, 1]]\) and \(\nu\) degrees of freedom.
Archimedean copulas are generated by a single dependence parameter \(\theta\):
\[ \begin{aligned} C_{\mathrm{Clayton}}(u,v) &= \big(u^{-\theta} + v^{-\theta} - 1\big)^{-1/\theta}, && \theta > 0, \[2pt] C_{\mathrm{Gumbel}}(u,v) &= \exp!\Big(-\big((-\ln u)^{\theta} + (-\ln v)^{\theta}\big)^{1/\theta}\Big), && \theta \ge 1, \[2pt] C_{\mathrm{Frank}}(u,v) &= -\frac{1}{\theta}, \ln!\left(1 - \frac{(1-e^{-\theta u})(1-e^{-\theta v})}{1-e^{-\theta}}\right), && \theta \ne 0. \end{aligned} \]
Each family has an analytic Kendall's tau as a function of its parameter:
\[ \tau_{\mathrm{Clayton}} = \frac{\theta}{\theta+2}, \qquad \tau_{\mathrm{Gumbel}} = \frac{\theta-1}{\theta}, \qquad \tau_{\mathrm{Frank}} = 1 + \frac{4}{\theta}\big(D_1(\theta) - 1\big), \]
where \(D_1(a) = \tfrac{1}{a}\int_0^a t/(e^t-1),dt\) is the first-order Debye function (evaluated here by adaptive Gauss-Kronrod quadrature; a Taylor expansion is used for small \(|\theta|\)). For the elliptical families the relation is the same arcsine law,
\[ \tau = \frac{2}{\pi}\arcsin(\rho), \qquad \rho_S = \frac{6}{\pi}\arcsin!\big(\tfrac{\rho}{2}\big), \]
the latter being Spearman's rho for the Gaussian copula. These mappings invert in closed form, which is how parameters are estimated from a sample tau (for example \(\theta = 2\tau/(1-\tau)\) for Clayton).
Example
Fit a Clayton copula to a small paired sample by matching Kendall's tau, then evaluate the density and CDF. The data is concordant (large with large), so we expect a positive tau and \(\theta > 0\).
#![allow(unused)] fn main() { use solow_copula::{kendalls_tau, ClaytonCopula, GaussianCopula}; // A small paired sample (e.g. two positively associated measurements). let x = [0.12, 0.31, 0.45, 0.58, 0.62, 0.77, 0.83, 0.91]; let y = [0.20, 0.25, 0.51, 0.49, 0.70, 0.68, 0.88, 0.95]; // 1. Sample dependence: Kendall's tau. let tau = kendalls_tau(&x, &y); println!("sample tau = {tau:.4}"); // 2. Method-of-moments fit: invert tau -> theta for Clayton. let theta = ClaytonCopula::theta_from_tau(tau); let clayton = ClaytonCopula::new(theta); println!("fitted theta = {:.4}", clayton.theta); // 3. Evaluate the copula density and CDF on the unit square. let (u, v) = (0.4, 0.6); println!("clayton.pdf({u}, {v}) = {:.4}", clayton.pdf(u, v)); println!("clayton.cdf({u}, {v}) = {:.4}", clayton.cdf(u, v)); // Round-trip check: the implied tau matches the sample tau. assert!((clayton.tau() - tau).abs() < 1e-12); // A Gaussian copula calibrated to the same tau, for comparison. let gauss = GaussianCopula::new(GaussianCopula::rho_from_tau(tau)); println!("gaussian rho = {:.4}", gauss.rho); println!("gaussian rho_S = {:.4}", gauss.spearmans_rho()); println!("gaussian.cdf({u}, {v}) = {:.4}", gauss.cdf(u, v)); }
Illustrative output (values depend on the data above): the sample tau is
positive, so theta_from_tau returns a positive Clayton parameter, the density
exceeds 1 in the lower-left region where Clayton concentrates dependence, and
the CDF lies between \(\max(u+v-1,0)\) and \(\min(u,v)\) (the Fréchet
bounds). The Gaussian comparison prints the correlation rho recovered from
the same tau via \(\rho = \sin(\pi\tau/2)\). The final assertion always holds
because the tau mapping inverts exactly.
The elliptical copulas accept a correlation directly, and GaussianCopula also
builds from a 2×2 correlation matrix:
#![allow(unused)] fn main() { use solow_copula::GaussianCopula; let g = GaussianCopula::from_corr([[1.0, 0.6], [0.6, 1.0]]); println!("log-density at (0.3, 0.7) = {:.4}", g.logpdf(0.3, 0.7)); }
Module reference
Models (copula types)
| Name | Description |
|---|---|
GaussianCopula | Bivariate Gaussian copula with correlation rho; pdf, logpdf, cdf, tau, spearmans_rho. |
StudentTCopula | Bivariate Student-t copula with rho and degrees of freedom df; pdf and tau. |
ClaytonCopula | Archimedean copula, theta > 0; lower-tail dependence. |
GumbelCopula | Archimedean copula, theta >= 1; upper-tail dependence. |
FrankCopula | Archimedean copula, theta != 0; symmetric, no tail dependence. |
Methods (per copula type)
| Name | Description |
|---|---|
new(..) | Construct a copula from its parameter(s). |
pdf(u, v) | Copula density on the unit square (all five types). |
cdf(u, v) | Copula CDF (Gaussian and the three Archimedean types). |
logpdf(u, v) | Log copula density (GaussianCopula). |
tau() | Implied Kendall's tau from the parameter (all five types). |
spearmans_rho() | Implied Spearman's rho (GaussianCopula). |
from_corr(corr) | Build a GaussianCopula from a 2×2 correlation matrix. |
theta_from_tau(tau) | Invert tau → theta (ClaytonCopula, GumbelCopula). |
rho_from_tau(tau) | Invert tau → rho (GaussianCopula). |
Functions
| Name | Description |
|---|---|
kendalls_tau(x, y) | Sample Kendall's tau-b for paired slices (matches scipy.stats.kendalltau). |
spearmans_rho(x, y) | Sample Spearman's rho via tie-averaged ranks (matches scipy.stats.spearmanr). |
bvn_cdf(h, k, r) | Standard bivariate-normal CDF (Drezner-Wesolowsky/Genz), used by the Gaussian copula. |
Full API: see the generated rustdoc for solow-copula.
References
- R. B. Nelsen, An Introduction to Copulas, 2nd ed., Springer, 2006.
- H. Joe, Dependence Modeling with Copulas, Chapman & Hall/CRC, 2014.
- A. Genz, "Numerical Computation of Rectangular Bivariate and Trivariate Normal and t Probabilities," Statistics and Computing 14(3), 251–260, 2004.
- M. G. Kendall, "A New Measure of Rank Correlation," Biometrika 30(1–2), 81–93, 1938.