PairCopula — Bivariate Copula Building Block
API reference for PairCopula: constructors, h-functions, inverse h-functions, and properties for bivariate copula evaluation in rscopulas.
PairCopula represents a single bivariate copula and is the fundamental building block used inside vine models. You can construct a pair-copula from a family specification or as a Khoudraji asymmetrization of two base copulas. The class exposes both the log-density and the h-functions (conditional CDFs) needed for vine construction and sequential sampling.
Constructors
PairCopula.from_spec(family, parameters=(), *, rotation="R0") → PairCopula
Construct a PairCopula from a family name and parameter list.
Copula family. Valid values: "independence", "gaussian", "student_t", "clayton", "frank", "gumbel".
Parameter values in the order expected by the family. For example, Gaussian takes one correlation value; Student-t takes a correlation and degrees-of-freedom.
Rotation applied to the bivariate copula. Valid values: "R0" (no rotation), "R90", "R180", "R270". Rotations let you model negative dependence or lower-tail dependence with families that are canonically upper-tail.
A ready-to-use PairCopula instance.
PairCopula.from_khoudraji(first_family, second_family, *, shape_1, shape_2, ...) → PairCopula
Construct a Khoudraji asymmetrized pair-copula from two base families.
Family name for the first base copula.
Family name for the second base copula.
Shape parameter controlling the weight of the first base copula. Must be in (0, 1).
Shape parameter controlling the weight of the second base copula. Must be in (0, 1).
Parameters for the first base copula.
Parameters for the second base copula.
Overall rotation applied to the Khoudraji copula.
Rotation applied to the first base copula.
Rotation applied to the second base copula.
A ready-to-use Khoudraji PairCopula instance.
Examples
from rscopulas import PairCopula
# Gaussian pair-copula with correlation 0.6
gaussian = PairCopula.from_spec("gaussian", [0.6])
# Clayton with 90-degree rotation (models negative dependence)
clayton_neg = PairCopula.from_spec("clayton", [2.0], rotation="R90")
# Independence copula
indep = PairCopula.from_spec("independence")
from rscopulas import PairCopula
# Khoudraji copula combining Gumbel and Clayton
khoudraji = PairCopula.from_khoudraji(
"gumbel",
"clayton",
shape_1=0.6,
shape_2=0.4,
first_parameters=[1.5],
second_parameters=[2.0],
)
Instance methods
log_pdf(u1, u2, *, clip_eps=1e-12) → ndarray
Evaluate the log-density of the pair-copula at paired observations.
A 1-D array of values for the first variable, with values strictly in (0, 1).
A 1-D array of values for the second variable, same length as u1.
Boundary clipping tolerance applied before evaluation.
A 1-D array of log-density values with length equal to u1.
cond_first_given_second(u1, u2, *, clip_eps=1e-12) → ndarray
Compute the h-function h(u1 | u2): the conditional CDF of the first variable given the second.
Values of the first variable.
Conditioning values of the second variable.
Boundary clipping tolerance.
Conditional CDF values in (0, 1).
cond_second_given_first(u1, u2, *, clip_eps=1e-12) → ndarray
Compute the h-function h(u2 | u1): the conditional CDF of the second variable given the first.
Conditioning values of the first variable.
Values of the second variable.
Boundary clipping tolerance.
Conditional CDF values in (0, 1).
inv_first_given_second(p, u2, *, clip_eps=1e-12) → ndarray
Inverse h-function: given a probability p and a conditioning value u2, return the quantile u1 such that h(u1 | u2) = p.
Probability values in (0, 1).
Conditioning values of the second variable.
Boundary clipping tolerance.
Quantile values in (0, 1).
inv_second_given_first(u1, p, *, clip_eps=1e-12) → ndarray
Inverse h-function: given a conditioning value u1 and a probability p, return the quantile u2 such that h(u2 | u1) = p.
Conditioning values of the first variable.
Probability values in (0, 1).
Boundary clipping tolerance.
Quantile values in (0, 1).
H-function example
import numpy as np
from rscopulas import PairCopula
copula = PairCopula.from_spec("gaussian", [0.7])
u1 = np.array([0.2, 0.5, 0.8])
u2 = np.array([0.3, 0.5, 0.7])
# Conditional CDF: P(U1 <= u1 | U2 = u2)
h = copula.cond_first_given_second(u1, u2)
# Inverse: recover u1 from h values
u1_recovered = copula.inv_first_given_second(h, u2)
print(np.allclose(u1, u1_recovered)) # True
Properties
Always 2 for a pair-copula.
The copula family name: "gaussian", "student_t", "clayton", "frank", "gumbel", "independence", or "khoudraji".
The rotation applied to the copula: "R0", "R90", "R180", or "R270".
The fitted or specified parameter values.
A serializable dict representation of the pair-copula specification, including family, rotation, and parameters. For Khoudraji copulas, the dict also contains shape_1, shape_2, base_copula_1, and base_copula_2.