Single-Family Copula Models Python Reference
API reference for GaussianCopula, StudentTCopula, ClaytonCopula, FrankCopula, GumbelCopula, and HierarchicalArchimedeanCopula in rscopulas.
Rscopulas provides six single-family copula classes. Each class shares the same core interface—fit, log_pdf, and sample—and exposes family-specific parameters as read-only properties. Elliptical copulas (GaussianCopula, StudentTCopula) infer dimension from their correlation matrix. Archimedean copulas (ClaytonCopula, FrankCopula, GumbelCopula) take an explicit dim argument. HierarchicalArchimedeanCopula accepts a nested tree structure.
Shared interface
Every single-family copula class exposes the following methods and properties.
fit(data, *, clip_eps=1e-12, max_iter=500) → FitResult
Fit the copula to pseudo-observations by maximum likelihood. Returns a FitResult containing the fitted model and diagnostics.
A 2-D array of pseudo-observations with shape (n_samples, n_dims) and dtype=float64. Every value must be strictly in (0, 1).
Values closer than clip_eps to 0 or 1 are clipped before evaluation to avoid numerical overflow.
Maximum number of optimizer iterations. If the optimizer has not converged by this limit, the result is still returned but diagnostics.converged will be False.
log_pdf(data, *, clip_eps=1e-12) → ndarray
Evaluate the log-density of the copula at each row of data.
A 2-D array with the same column count as the fitted model.
Boundary clipping tolerance applied before evaluation.
A 1-D array of log-density values, one per row of data.
sample(n, *, seed=None) → ndarray
Draw n pseudo-observations from the copula.
Number of samples to draw.
Random seed for reproducibility. Pass None for a non-deterministic draw.
A 2-D array of shape (n, dim) with values in (0, 1).
dim property
Number of dimensions (variables) in the fitted copula.
family property
Family name string, e.g. "gaussian", "student_t", "clayton".
GaussianCopula
A multivariate Gaussian (normal) copula parameterized by a correlation matrix. It captures symmetric, linear dependence and has no tail dependence.
GaussianCopula.from_params(correlation)
Construct a GaussianCopula directly from a correlation matrix without fitting.
A positive-definite correlation matrix of shape (d, d) with ones on the diagonal and values in (-1, 1) on the off-diagonals.
A ready-to-use GaussianCopula instance.
Properties
A copy of the fitted correlation matrix with shape (d, d).
Example
import numpy as np
from rscopulas import GaussianCopula
rng = np.random.default_rng(0)
data = rng.uniform(0.01, 0.99, size=(500, 3))
# Fit from data
result = GaussianCopula.fit(data)
model = result.model
print(model.correlation)
# Or build from known parameters
corr = np.array([[1.0, 0.6], [0.6, 1.0]])
manual = GaussianCopula.from_params(corr)
samples = manual.sample(100, seed=7)
StudentTCopula
A multivariate Student-t copula parameterized by a correlation matrix and degrees-of-freedom. It captures symmetric dependence with heavier tails than the Gaussian copula, making it useful when you expect joint extreme events.
StudentTCopula.from_params(correlation, degrees_of_freedom)
A positive-definite correlation matrix of shape (d, d).
Degrees of freedom (must be > 2 for finite variance). Smaller values produce heavier tails.
A ready-to-use StudentTCopula instance.
Properties
A copy of the fitted correlation matrix with shape (d, d).
The fitted degrees-of-freedom parameter.
Example
import numpy as np
from rscopulas import StudentTCopula
rng = np.random.default_rng(1)
data = rng.uniform(0.01, 0.99, size=(400, 2))
result = StudentTCopula.fit(data)
model = result.model
print("df:", model.degrees_of_freedom)
print("correlation:", model.correlation)
# Build from known parameters
corr = np.array([[1.0, 0.4], [0.4, 1.0]])
manual = StudentTCopula.from_params(corr, degrees_of_freedom=4.0)
log_d = manual.log_pdf(data)
ClaytonCopula
An Archimedean copula with lower-tail dependence. The theta parameter controls the strength of dependence: larger values mean stronger lower-tail clustering.
ClaytonCopula.from_params(dim, theta)
Number of dimensions.
Dependence parameter. Must be > 0.
A ready-to-use ClaytonCopula instance.
Properties
The fitted Archimedean dependence parameter.
Example
import numpy as np
from rscopulas import ClaytonCopula
rng = np.random.default_rng(2)
data = rng.uniform(0.01, 0.99, size=(300, 2))
result = ClaytonCopula.fit(data)
print("theta:", result.model.theta)
# Build from known theta
manual = ClaytonCopula.from_params(dim=2, theta=2.5)
samples = manual.sample(200, seed=42)
FrankCopula
An Archimedean copula with symmetric dependence and no tail dependence. theta can be positive or negative, making the Frank copula suitable for modeling mild positive or negative dependence.
FrankCopula.from_params(dim, theta)
Number of dimensions.
Dependence parameter. Positive values indicate positive dependence; negative values indicate negative dependence.
A ready-to-use FrankCopula instance.
Properties
The fitted dependence parameter.
Example
import numpy as np
from rscopulas import FrankCopula
rng = np.random.default_rng(3)
data = rng.uniform(0.01, 0.99, size=(300, 2))
result = FrankCopula.fit(data)
print("theta:", result.model.theta)
manual = FrankCopula.from_params(dim=2, theta=3.0)
log_d = manual.log_pdf(data)
GumbelCopula
An Archimedean copula with upper-tail dependence. The theta parameter must be ≥ 1; at theta = 1 the Gumbel copula reduces to the independence copula.
GumbelCopula.from_params(dim, theta)
Number of dimensions.
Dependence parameter. Must be ≥ 1.
A ready-to-use GumbelCopula instance.
Properties
The fitted dependence parameter.
Example
import numpy as np
from rscopulas import GumbelCopula
rng = np.random.default_rng(4)
data = rng.uniform(0.01, 0.99, size=(300, 2))
result = GumbelCopula.fit(data)
print("theta:", result.model.theta)
manual = GumbelCopula.from_params(dim=2, theta=1.8)
samples = manual.sample(100, seed=0)
HierarchicalArchimedeanCopula
A nested Archimedean copula that supports a hierarchical tree structure where different subtrees can use different Archimedean families. Density evaluation uses an exact exchangeable path for single-fan Archimedean trees; nested trees use a composite pair-copula evaluation.
Mixed-family nesting (different Archimedean family on a child node than on its parent) uses a numerical frailty sampler that can degenerate near the boundary. Do not rely on sample() for mixed-family trees until the implementation is stabilized.
HierarchicalArchimedeanCopula.from_tree(tree)
Construct a HierarchicalArchimedeanCopula directly from a nested tree specification.
A nested dict describing the HAC structure. Each node specifies "family", "theta", and "children". Children can be integer leaf indices or nested node dicts. See the HAC guide for a full example.
A ready-to-use instance.
HierarchicalArchimedeanCopula.fit(data, *, ...)
Fit the copula to pseudo-observations. In addition to the shared clip_eps and max_iter, the following keyword arguments control structure and parameter estimation.
Pseudo-observations with shape (n_samples, n_dims) and values strictly in (0, 1).
Fix the tree structure and only fit parameters. Pass None to let the algorithm infer the structure.
Restrict the allowed Archimedean families. Pass None to use all supported families.
Algorithm used to infer the hierarchical nesting structure.
Parameter estimation method.
Threshold for collapsing subtrees when the structure method uses agglomeration.
Number of Monte Carlo samples used for likelihood approximation in nested settings.
Allow experimental code paths in the Rust backend.
Properties
True when the model uses the exact density path (single Archimedean fan).
True when the log-likelihood was computed exactly rather than approximated.
The fitted tree structure as a nested dict.
Archimedean family assigned to each node in the hierarchy.
Dependence parameters for each node, in the same order as families.
The order of leaf variables in the fitted tree.
Example
import numpy as np
from rscopulas import HierarchicalArchimedeanCopula
rng = np.random.default_rng(5)
data = rng.uniform(0.01, 0.99, size=(400, 4))
result = HierarchicalArchimedeanCopula.fit(
data,
family_set=["clayton", "gumbel"],
)
model = result.model
print("families:", model.families)
print("parameters:", model.parameters)
print("leaf order:", model.leaf_order)