Copula Families: Gaussian, Vine, HAC, and More

The Gaussian copula captures symmetric linear dependence parameterized by a correlation matrix. It is a natural starting point and widely used in finance and risk modeling. Upper- and lower-tail dependence are both zero, making it a poor fit for data with extreme co-movements.

import numpy as np
from rscopulas import GaussianCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.68, 0.73], [0.82, 0.79]], dtype=np.float64)
result = GaussianCopula.fit(data)
print(result.model.correlation)

Use GaussianCopula.from_params(correlation) to construct a model from a known correlation matrix without fitting.

The Student t copula is elliptical like the Gaussian but has heavier tails controlled by the degrees_of_freedom parameter. Both upper and lower tail dependence are positive, making it suitable when joint extremes occur more often than a Gaussian copula would predict.

import numpy as np
from rscopulas import StudentTCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.68, 0.73], [0.82, 0.79]], dtype=np.float64)
result = StudentTCopula.fit(data)
print(result.model.degrees_of_freedom)

The Clayton copula is an Archimedean family parameterized by a single theta > 0. It exhibits strong lower-tail dependence — variables are more likely to be simultaneously low than simultaneously high. Choose Clayton when you expect dependence to concentrate in the lower joint tail (e.g., simultaneous losses).

import numpy as np
from rscopulas import ClaytonCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.68, 0.73], [0.82, 0.79]], dtype=np.float64)
result = ClaytonCopula.fit(data)
print(result.model.theta)

The Frank copula is an Archimedean family with a single theta ≠ 0. It is symmetric — no tail dependence in either direction — and allows both positive and negative dependence. It is often a good baseline for moderate, symmetric association.

import numpy as np
from rscopulas import FrankCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.68, 0.73], [0.82, 0.79]], dtype=np.float64)
result = FrankCopula.fit(data)
print(result.model.theta)

The Gumbel copula is an Archimedean family parameterized by theta ≥ 1, where theta = 1 corresponds to independence. It has upper-tail dependence, meaning joint extreme high values are more likely than a Gaussian copula predicts. Choose Gumbel when dependence concentrates in the upper joint tail.

import numpy as np
from rscopulas import GumbelCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.68, 0.73], [0.82, 0.79]], dtype=np.float64)
result = GumbelCopula.fit(data)
print(result.model.theta)

A C-vine has a star graph at each tree level: one variable acts as the central "hub" and is paired with all others. This structure is natural when one variable drives dependence with all remaining variables.

import numpy as np
from rscopulas import VineCopula

data = np.array([
    [0.12, 0.18, 0.21], [0.21, 0.25, 0.29],
    [0.48, 0.51, 0.46], [0.82, 0.79, 0.76],
], dtype=np.float64)

result = VineCopula.fit_c(
    data,
    family_set=["gaussian", "clayton", "frank", "gumbel"],
    criterion="aic",
)

A D-vine has a path graph at each tree level: variables are arranged in a sequence and each is paired with its immediate neighbors. D-vines are well suited to data with a natural ordering, such as time series or spatial sequences.

result = VineCopula.fit_d(
    data,
    family_set=["gaussian", "clayton", "frank", "gumbel"],
    criterion="aic",
)

An R-vine allows any valid tree structure at each level, making it the most general option. Rscopulas selects the structure that minimizes the chosen criterion (AIC by default). Use R-vine when you have no prior reason to prefer C- or D-vine and want the model to choose its own structure.

result = VineCopula.fit_r(
    data,
    family_set=["independence", "gaussian", "clayton", "frank", "gumbel", "khoudraji"],
    include_rotations=True,
    truncation_level=1,
)
print(result.model.structure_info.kind)