Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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)

NameDescription
GaussianCopulaBivariate Gaussian copula with correlation rho; pdf, logpdf, cdf, tau, spearmans_rho.
StudentTCopulaBivariate Student-t copula with rho and degrees of freedom df; pdf and tau.
ClaytonCopulaArchimedean copula, theta > 0; lower-tail dependence.
GumbelCopulaArchimedean copula, theta >= 1; upper-tail dependence.
FrankCopulaArchimedean copula, theta != 0; symmetric, no tail dependence.

Methods (per copula type)

NameDescription
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

NameDescription
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.