copul package

Subpackages

Submodules

copul.basictools module

copul.basictools.monte_carlo_integral(func, n_samples=10000, x=1, y=1, vectorized=False)[source]

copul.chatterjee module

Chatterjee’s Xi coefficient for measuring nonlinear dependence.

This module implements Chatterjee’s Xi coefficient, a rank-based measure of dependence that can detect both linear and non-linear associations between variables.

References

Chatterjee, S. (2021). A new coefficient of correlation. Journal of the American Statistical Association, 116(536), 2009-2022.

copul.chatterjee.test_independence(xvec: ndarray, yvec: ndarray, alpha: float = 0.05) → Tuple[float, float, bool][source]

Test the null hypothesis of independence between x and y.

Parameters:

  • xvec (np.ndarray) – First vector of data.

  • yvec (np.ndarray) – Second vector of data.

  • alpha (float, optional) – Significance level, default is 0.05.

Returns:

The Xi_n value, p-value, and boolean indicating if the null hypothesis of independence should be rejected.

Return type:

Tuple[float, float, bool]

Examples

>>> import numpy as np
>>> # Independent data
>>> x = np.random.rand(100)
>>> y = np.random.rand(100)
>>> xi, p_value, reject = test_independence(x, y)
>>> print(f"Xi_n: {xi:.4f}, p-value: {p_value:.4f}, reject H0: {reject}")
>>>
>>> # Dependent data
>>> x = np.random.rand(100)
>>> y = x + np.random.normal(0, 0.1, 100)
>>> xi, p_value, reject = test_independence(x, y)
>>> print(f"Xi_n: {xi:.4f}, p-value: {p_value:.4f}, reject H0: {reject}")
copul.chatterjee.xi_n_with_ci(xvec: ndarray, yvec: ndarray, alpha: float = 0.05) → Tuple[float, Tuple[float, float]][source]

Calculate Xi_n dependence measure with confidence interval.

Parameters:

  • xvec (np.ndarray) – First vector of data.

  • yvec (np.ndarray) – Second vector of data.

  • alpha (float, optional) – Significance level, default is 0.05 for 95% confidence interval.

Returns:

The Xi_n dependence measure and its confidence interval as (xi_n, (lower, upper)).

Return type:

Tuple[float, Tuple[float, float]]

Examples

>>> import numpy as np
>>> x = np.random.rand(100)
>>> y = 2*x + np.random.normal(0, 0.1, 100)
>>> xi, (lower, upper) = xi_n_with_ci(x, y)
>>> print(f"Xi_n: {xi:.4f}, 95% CI: ({lower:.4f}, {upper:.4f})")
copul.chatterjee.xi_ncalculate(xvec: ndarray, yvec: ndarray) → float[source]

Calculate the Xi_n dependence measure between two vectors of data.

Xi_n is a measure of association that can detect both linear and nonlinear relationships, and is based on the ranks of the data. The measure ranges approximately from 0 to 1, where 0 indicates no association and 1 indicates a perfect deterministic relationship.

Parameters:

  • xvec (np.ndarray) – First vector of data.

  • yvec (np.ndarray) – Second vector of data.

Returns:

The Xi_n dependence measure.

Return type:

float

Notes

  • The measure is not symmetric: xi_n(x, y) may not equal xi_n(y, x).

  • For perfect correlations (positive or negative), the function returns 0.5.

  • For constant data (either x or y), the function returns 0.5.

  • For inputs containing NaN, the function returns 0.5.

  • Empty or single-element vectors return NaN.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 3, 4, 5])
>>> y = np.array([1, 2, 3, 4, 5])  # Perfect positive correlation
>>> xi_ncalculate(x, y)
0.5
>>> y = np.array([5, 4, 3, 2, 1])  # Perfect negative correlation
>>> xi_ncalculate(x, y)
0.5
>>> y = np.array([1, 4, 2, 5, 3])  # Some random association
>>> xi_ncalculate(x, y)  # Will be between 0 and 1
copul.chatterjee.xi_nvarcalculate(xvec: ndarray, yvec: ndarray) → float[source]

Calculate the variance of the Xi_n dependence measure.

This function computes the asymptotic variance of Chatterjee’s Xi coefficient, which can be used for statistical inference.

Parameters:

  • xvec (np.ndarray) – First vector of data.

  • yvec (np.ndarray) – Second vector of data.

Returns:

The estimated variance of the Xi_n dependence measure.

Return type:

float

Notes

  • The variance is always non-negative, with a minimum value of 0.

  • For inputs containing NaN, the function may still return a numerical result.

  • If vectors are of different lengths, the function will process them anyway.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 3, 4, 5])
>>> y = np.array([1, 2, 3, 4, 5])  # Perfect correlation
>>> xi_nvarcalculate(x, y)  # Should be small
>>> y = np.random.rand(5)  # Random values
>>> xi_nvarcalculate(x, y)  # Will likely be higher

copul.copula_sampler module

class copul.copula_sampler.CopulaSampler(copul: Any, precision: int = 3, random_state: int | None = None)[source]

Bases: object

Sampler for generating random variates from copula distributions.

This class provides methods to sample from arbitrary copula distributions using conditional distribution methods and numerical root-finding.

err_counter = 0
rvs(n: int = 1, approximate=False) → ndarray[source]

Sample n random variates from the copula.

Parameters:

  • n – Number of samples to generate (default: 1).

  • approximate – Use approximate sampling method (default: True).

Returns:

Array of shape (n, 2) containing the sampled (u, v) pairs.

Return type:

np.ndarray

sample_val(function: Callable) → Tuple[float, float][source]

Generate a single sample from the copula using inverse CDF method.

Parameters:

function – The conditional distribution function.

Returns:

A (u, v) pair from the copula distribution.

Return type:

Tuple[float, float]

copul.data_uniformer module

class copul.data_uniformer.DataUniformer[source]

Bases: object

Class to transform data to uniform margins using empirical CDF.

Transforms multivariate data to have uniform margins on [0,1] by converting values to ranks and then scaling appropriately.

uniform(data, touch_boundaries=False)[source]

Transform data to uniform margins (ranks scaled to [0,1]).

Parameters:

  • data (numpy.ndarray or list) – Array of shape (n_samples, n_features) to be transformed

  • touch_boundaries (bool, optional) – If False (default), the transformed values lie strictly in (0,1). If True, the transformed values will exactly include 0.0 and 1.0 for the min and max of each column.

Returns:

Transformed data with values in [0,1].

Return type:

numpy.ndarray

copul.exceptions module

exception copul.exceptions.PropertyUnavailableException[source]

Bases: Exception

A property is not available

copul.family_list module

Copula Families Module

Provides a comprehensive enumeration of all copulas in the package, organized by:

  1. Mathematical Category - Archimedean, Elliptical, Extreme Value, Other

  2. Semantic Kind - FAMILY : true parametric families for modeling/fitting - APPROXIMATION : approximation constructs (checkerboards, Bernstein, …) - SPECIAL : notable/special single copulas (Fréchet bounds, Independence, …)

Module-level public lists (alphabetical class names)

  • cp.families -> class names of true parametric families

  • cp.approximations -> class names of approximation constructs

  • cp.copulas -> class names of notable/special single copulas

Examples

>>> import copul as cp
>>> cp.families
['AliMikhailHaq', 'Clayton', 'Frank', 'Gaussian', 'GenestGhoudi', ...]
>>> cp.approximations
['BivCheckPi', 'BivCheckW', 'CheckMin', 'CheckPi', ...]
>>> cp.copulas
['ClampedParabolaCopula', 'DiagonalBandCopula', 'Frechet', 'IndependenceCopula', ...]

Programmatic APIs

>>> cp.Families.list_all()                       # UPPER_CASE enum names of true families
>>> cp.Families.list_all_classnames()            # class names of true families
>>> cp.Families.list_approx_classnames()         # class names of approximations
>>> cp.Families.list_special_classnames()        # class names of specials
>>> cp.Families.list_by_category('archimedean')  # filter by mathematical category
class copul.family_list.CopulaKind(*values)[source]

Bases: Enum

APPROXIMATION = 'approximation'
FAMILY = 'family'
SPECIAL = 'special'
class copul.family_list.Families(*values)[source]

Bases: Enum

Registry of all copulas with lazy import of their classes.

ALI_MIKHAIL_HAQ = 'copul.family.archimedean.AliMikhailHaq'
BB5 = 'copul.family.extreme_value.BB5'
BERNSTEIN = 'copul.checkerboard.bernstein.Bernstein'
BIV_CHECK_MIN = 'copul.checkerboard.biv_check_min.BivCheckMin'
BIV_CHECK_PI = 'copul.checkerboard.biv_check_pi.BivCheckPi'
BIV_CHECK_W = 'copul.checkerboard.biv_check_w.BivCheckW'
CHECK_MIN = 'copul.checkerboard.check_min.CheckMin'
CHECK_PI = 'copul.checkerboard.check_pi.CheckPi'
CLAYTON = 'copul.family.archimedean.Clayton'
CUADRAS_AUGE = 'copul.family.extreme_value.CuadrasAuge'
DIAGONAL_BAND = 'copul.family.other.DiagonalBandCopula'
FARLIE_GUMBEL_MORGENSTERN = 'copul.family.other.FarlieGumbelMorgenstern'
FRANK = 'copul.family.archimedean.Frank'
FRECHET = 'copul.family.other.Frechet'
GALAMBOS = 'copul.family.extreme_value.Galambos'
GAUSSIAN = 'copul.family.elliptical.Gaussian'
GENEST_GHOUDI = 'copul.family.archimedean.GenestGhoudi'
GUMBEL_BARNETT = 'copul.family.archimedean.GumbelBarnett'
GUMBEL_HOUGAARD = 'copul.family.archimedean.GumbelHougaard'
GUMBEL_HOUGAARD_EV = 'copul.family.extreme_value.GumbelHougaardEV'
HUESLER_REISS = 'copul.family.extreme_value.HueslerReiss'
INDEPENDENCE = 'copul.family.other.IndependenceCopula'
JOE = 'copul.family.archimedean.Joe'
JOE_EV = 'copul.family.extreme_value.JoeEV'
LOWER_FRECHET = 'copul.family.other.LowerFrechet'
MARDIA = 'copul.family.other.Mardia'
MARSHALL_OLKIN = 'copul.family.extreme_value.MarshallOlkin'
NELSEN1 = 'copul.family.archimedean.Nelsen1'
NELSEN10 = 'copul.family.archimedean.Nelsen10'
NELSEN11 = 'copul.family.archimedean.Nelsen11'
NELSEN12 = 'copul.family.archimedean.Nelsen12'
NELSEN13 = 'copul.family.archimedean.Nelsen13'
NELSEN14 = 'copul.family.archimedean.Nelsen14'
NELSEN15 = 'copul.family.archimedean.Nelsen15'
NELSEN16 = 'copul.family.archimedean.Nelsen16'
NELSEN17 = 'copul.family.archimedean.Nelsen17'
NELSEN18 = 'copul.family.archimedean.Nelsen18'
NELSEN19 = 'copul.family.archimedean.Nelsen19'
NELSEN2 = 'copul.family.archimedean.Nelsen2'
NELSEN20 = 'copul.family.archimedean.Nelsen20'
NELSEN21 = 'copul.family.archimedean.Nelsen21'
NELSEN22 = 'copul.family.archimedean.Nelsen22'
NELSEN3 = 'copul.family.archimedean.Nelsen3'
NELSEN4 = 'copul.family.archimedean.Nelsen4'
NELSEN5 = 'copul.family.archimedean.Nelsen5'
NELSEN6 = 'copul.family.archimedean.Nelsen6'
NELSEN7 = 'copul.family.archimedean.Nelsen7'
NELSEN8 = 'copul.family.archimedean.Nelsen8'
NELSEN9 = 'copul.family.archimedean.Nelsen9'
PI_OVER_SIGMA_MINUS_PI = 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'
PLACKETT = 'copul.family.other.Plackett'
RAFTERY = 'copul.family.other.Raftery'
SHUFFLE_OF_MIN = 'copul.checkerboard.shuffle_min.ShuffleOfMin'
T = 'copul.family.elliptical.StudentT'
TAWN = 'copul.family.extreme_value.Tawn'
T_EV = 'copul.family.extreme_value.tEV'
UPPER_FRECHET = 'copul.family.other.UpperFrechet'
XI_NU_BOUNDARY = 'copul.family.other.XiNuBoundaryCopula'
XI_PSI_BOUNDARY = 'copul.family.other.XiPsiApproxLowerBoundaryCopula'
XI_RHO_BOUNDARY = 'copul.family.other.XiRhoBoundaryCopula'
property cls
classmethod compare_copulas(u: ndarray, families: List[str] | None = None, fit_method: str = 'ml', criteria: str = 'aic') → List[Dict][source]

Compare multiple copula families on the same dataset.

Parameters:

  • u (ndarray) – Pseudo-observations in [0,1]^d.

  • families (list[str] | None) – Enum NAMES to compare; defaults to a common set.

  • fit_method (str) – Method for .fit(), e.g. ‘ml’ (if available).

  • criteria ({'aic','bic','likelihood'}) – Sorting metric; lower is better for aic/bic, higher is better for likelihood.

Returns:

Sorted list of results with keys: ‘family’, ‘copula’, ‘score’, ‘params’.

Return type:

list[dict]

classmethod create(family_name: str, *args, **kwargs)[source]

Instantiate a copula by enum NAME with parameters.

classmethod get_category(family: Families | str) → FamilyCategory[source]

Mathematical category based on import path.

classmethod get_kind(member: Families) → CopulaKind[source]
classmethod get_params_info(family_name: str) → Dict[source]

Inspect __init__ signature and basic param doc of a copula class.

classmethod list_all() → List[str][source]

UPPER_CASE enum names of true modeling families.

classmethod list_all_classnames(lowercase: bool = False) → List[str][source]

Class names of true families (sorted).

classmethod list_approx_classnames(lowercase: bool = False) → List[str][source]

Class names of approximation constructs (sorted).

classmethod list_approximations() → List[str][source]

UPPER_CASE enum names of approximation constructs.

classmethod list_by_category(category: FamilyCategory | str) → List[str][source]

UPPER_CASE enum names of true families within a given category.

classmethod list_classes(kind: CopulaKind | str | None = None, category: FamilyCategory | str | None = None) → List[type][source]

Same as list_names but returns the class objects.

classmethod list_names(kind: CopulaKind | str | None = None, category: FamilyCategory | str | None = None) → List[str][source]

Enum names filtered by semantic kind and/or mathematical category. kind : {‘family’,’approximation’,’special’} or None category : {‘archimedean’,’elliptical’,’extreme_value’,’other’} or None

classmethod list_special_classnames(lowercase: bool = False) → List[str][source]

Class names of notable/special copulas (sorted).

classmethod list_specials() → List[str][source]

UPPER_CASE enum names of notable/special copulas.

class copul.family_list.FamilyCategory(*values)[source]

Bases: Enum

ARCHIMEDEAN = 'archimedean'
ELLIPTICAL = 'elliptical'
EXTREME_VALUE = 'extreme_value'
OTHER = 'other'

copul.foci module

Conditional Dependence Coefficient (CODEC) Implementation

This module provides functions to calculate the conditional dependence coefficient (CODEC), a measure of conditional dependence between random variables based on an i.i.d. sample.

The implementation is based on the paper “An Empirical Study on New Model-Free Multi-output Variable Selection Methods” by Ansari et al.

copul.foci.codec(Y: ndarray | Series | DataFrame | List, Z: ndarray | Series | DataFrame | List, X: ndarray | Series | DataFrame | List | None = None, na_rm: bool = True) → float | Dict[str, float][source]

Calculate the conditional dependence coefficient (CODEC).

CODEC measures the amount of conditional dependence between a random variable Y and a random vector Z given a random vector X, based on an i.i.d. sample of (Y, Z, X). The coefficient is asymptotically guaranteed to be between 0 and 1.

If X is None, the unconditional CODEC is calculated, corresponding to xi(Y|Z) from the Ansari et al. paper.

Parameters:

  • Y (array-like) – The response variable.

  • Z (array-like) – The conditioning variable.

  • X (array-like, optional) – The conditioning variable. If None, the unconditional CODEC is calculated.

  • na_rm (bool, optional) – Whether to remove NAs. Default is True.

Returns:

The conditional dependence coefficient or a dictionary of coefficients when Y is a DataFrame.

Return type:

float or dict

Raises:

ValueError – If the number of rows of Y, X, and Z are not equal. If the number of rows with no NAs is less than 2.

Examples

>>> import numpy as np
>>> n = 1000
>>> x = np.random.rand(n, 2)
>>> y = (x[:, 0] + x[:, 1]) % 1
>>> # Calculate unconditional CODEC
>>> codec_y_x = codec(y, x)
>>> # Calculate conditional CODEC
>>> z = np.random.randn(n, 1)
>>> codec_y_z_x = codec(y, z, x)
copul.foci.estimate_conditional_q(Y: ndarray, X: ndarray, Z: ndarray) → float[source]

Estimate the conditional Q statistic for CODEC calculation.

Parameters:

  • Y (np.ndarray) – The response variable.

  • X (np.ndarray) – First conditioning variable.

  • Z (np.ndarray) – Second conditioning variable.

Returns:

The estimated conditional Q statistic.

Return type:

float

copul.foci.estimate_conditional_s(Y: ndarray, X: ndarray) → float[source]

Estimate the conditional S statistic for CODEC calculation.

Parameters:

  • Y (np.ndarray) – The response variable.

  • X (np.ndarray) – The conditioning variable.

Returns:

The estimated conditional S statistic.

Return type:

float

copul.foci.estimate_conditional_t(Y: ndarray, Z: ndarray, X: ndarray) → float[source]

Estimate the conditional T statistic (the conditional CODEC).

Parameters:

  • Y (np.ndarray) – The response variable.

  • Z (np.ndarray) – The primary conditioning variable.

  • X (np.ndarray) – The secondary conditioning variable.

Returns:

The estimated conditional T statistic (CODEC value).

Return type:

float

copul.foci.estimate_q(Y: ndarray, X: ndarray) → float[source]

Estimate the Q statistic for unconditional CODEC calculation.

Parameters:

  • Y (np.ndarray) – The response variable.

  • X (np.ndarray) – The conditioning variable.

Returns:

The estimated Q statistic.

Return type:

float

copul.foci.estimate_s(Y: ndarray) → float[source]

Estimate the S statistic for unconditional CODEC calculation.

Parameters:

Y (np.ndarray) – The response variable.

Returns:

The estimated S statistic.

Return type:

float

copul.foci.estimate_t(Y: ndarray, X: ndarray) → float[source]

Estimate the T statistic (the unconditional CODEC).

Parameters:

  • Y (np.ndarray) – The response variable.

  • X (np.ndarray) – The conditioning variable.

Returns:

The estimated T statistic (CODEC value).

Return type:

float

copul.foci.find_nearest_neighbors(X: ndarray) → ndarray[source]

Find the nearest neighbors for each point in X, handling repeats and ties.

Parameters:

X (np.ndarray) – The data points.

Returns:

Indices of nearest neighbors.

Return type:

np.ndarray

copul.numerics module

Utilities for converting SymPy expressions to fast NumPy callables.

Key improvements over the naive sp.lambdify approach: - NUMPY_SAFE_MAP maps SymPy names that numpy does not expose under the same

name (Max, Min, Heaviside, …) plus several scipy.special functions used in copula densities (erf, erfc, gamma, …).

  • to_numpy_callable caches compiled functions by (expression-string, variable-names) to avoid re-invoking SymPy’s lambdify for the same expression.

copul.numerics.clear_lambdify_cache() → None[source]

Evict all cached lambdified functions.

Useful in long-running sessions or after symbolic manipulations that produce many unique expressions.

copul.numerics.drop_distributions(expr: Expr) → Expr[source]

Remove distributional terms for ‘a.e.’ numeric evaluation (plots, grids).

Specifically: - DiracDelta(·) → 0 - Derivative(Heaviside(·), ·) → 0 (SymPy represents this as DiracDelta)

copul.numerics.to_numpy_callable(expr: Expr, vars: Sequence, *, ae: bool = True)[source]

Compile a SymPy expression to a NumPy-callable with robust function mappings.

Parameters:

  • expr (sympy.Expr) – The symbolic expression to compile.

  • vars (sequence of sympy.Symbol) – Free variables, in the order expected by the returned callable.

  • ae (bool) – If True (default), drop DiracDelta terms so the result is valid almost everywhere — appropriate for density plots and grids.

Returns:

f(*arrays) -> array fully broadcast-compatible with NumPy.

Return type:

callable

Notes

Compiled functions are cached by (str(expr), var_names, ae). The first call for a given expression pays the SymPy compilation overhead; subsequent calls return the cached function instantly.

copul.star_product module

copul.star_product.markov_product(C: BivCopula, D: BivCopula, *, n_grid: int = 400, checkerboard: bool = False) → BivCopula[source]

Module contents

class copul.AliMikhailHaq(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

Ali-Mikhail-Haq copula (Nelsen 3)

ac

alias of BivArchimedeanCopula

chatterjees_xi(*args, **kwargs)[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the bivariate Archimedean copula.

Kendall’s tau is a measure of concordance. For Archimedean copulas, it can be calculated using the generator function.

Returns:

Kendall’s tau value

Return type:

float or sympy expression

spearmans_rho(*args, **kwargs)[source]

Compute Spearman’s rho correlation measure.

This method sets the parameters, computes the corresponding integral, and returns the simplified expression for Spearman’s rho.

Returns:

The symbolic expression for Spearman’s rho.

Return type:

sympy.Expr

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>, 1: <class 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'>}
theta_interval = Interval(-1, 1)
class copul.BB5(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

cdf(u=None, v=None, **kwargs)[source]

Evaluate the CDF numerically via cdf_vectorized.

The symbolic CDF of the BB5 copula contains deeply nested logarithms and powers that are prohibitively slow to evaluate through SymPy’s evalf. This override routes all concrete (u, v) evaluations to the fast numpy path.

delta = delta
intervals: dict = {'delta': Interval.open(0, oo), 'theta': Interval(1, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

params: list = [theta, delta]
property pdf

Numerical PDF via finite-difference on cdf_vectorized.

theta = theta
copul.Bernstein

alias of BernsteinCopula

class copul.BernsteinCopula(theta, *args, **kwargs)[source]

Bases: Check, CopulaPlottingMixin

Represents a d-dimensional Bernstein Copula with possibly different degrees m_i per dimension. This version uses cumulative sum logic (skipping k=0) to compute the CDF/PDF.

cdf(*args)[source]
cond_distr(i, *args)[source]
Numerically compute C_{i|(-i)}(u_i|u_{-i}) using the ratio:

C(u1,…,u_{i-1}, u_i, 1,…,1) / C(u1,…,u_{i-1}, 1,…,1)

cond_distr_1(*args)[source]
cond_distr_2(*args)[source]
property is_absolutely_continuous: bool
pdf(*args)[source]
copul.BivBernstein

alias of BivBernsteinCopula

class copul.BivBernsteinCopula(theta, *args, **kwargs)[source]

Bases: BernsteinCopula, BivCoreCopula, CopulaSamplingMixin

chatterjees_xi(condition_on_y: bool = False) → float[source]
Calculate Chatterjee’s xi using the matrix-trace formula:

xi = 6 * trace( Omega^(m) * D * Lambda^(n) * D^T ) - 2,

where:

D = self._cumsum_theta(), Omega^(m) captures integrals of partial derivatives of Bernstein polynomials, Lambda^(n) captures integrals of Bernstein polynomials themselves.

kendalls_tau() → float[source]
Calculate Kendall’s tau using the matrix formula:

tau = 1 - trace( Theta^(m) * D * Theta^(n) * D^T ).

lambda_L()[source]

Lower tail dependence is zero by 2016 Pfeifer, Tsatedem, Mändle and Girschig - Example 1

lambda_U()[source]

Upper tail dependence is zero by 2016 Pfeifer, Tsatedem, Mändle and Girschig - Example 1

spearmans_rho() → float[source]

Compute Spearman’s rho for a bivariate checkerboard (Bernstein) copula. Formula: rho = 12/( (m+1)*(n+1) ) * sum_{i,j} D_{i,j} - 3 where D = self._cumsum_theta() is the cumulated checkerboard matrix.

class copul.BivCheckMin(matr, *args, **kwargs)[source]

Bases: CheckMin, BivCheckPi

Bivariate Checkerboard Minimum class.

A class that implements bivariate checkerboard minimum operations.

blests_nu() → float[source]

Blest’s measure (nu) for a BivCheckMin copula.

Returns:

Blest’s nu.

Return type:

float

Notes

Decomposes as:

nu(CheckMin) = nu(CheckPi) + singular_add_on,

where the singular add-on arises from the minimum completion placing a singular mass along the main diagonal segments of each square cell (i,i). The add-on equals the diagonal mass weighted by the average of (1-u) along the corresponding diagonal segment.

Closed forms:

nu(CheckPi) = (24 / (m^2 n)) * tr(Δ^T K) - 2, with K as in BivCheckPi.blests_nu().

singular_add_on = (24 / m^2) * sum_{i=1}^m (m - i + 1/2) * Δ_{ii}.

chatterjees_xi(condition_on_y: bool = False) → float[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

classmethod generate_randomly(grid_size: int | list | None = None, n=1)[source]
ginis_gamma() → float[source]

Compute Gini’s Gamma for a BivCheckMin copula.

This method corrects the value from the parent BivCheckPi class. The parent method incorrectly uses the overridden footrule method from this child class, leading to a “contaminated” result that already includes the add-on for the main diagonal integral. We correct this by adding only the missing component from the anti-diagonal integral. Implemented for square checkerboard matrices.

Returns:

The value of Gini’s Gamma.

Return type:

float

property is_absolutely_continuous: bool

Check if the distribution is absolutely continuous.

Returns:

Always returns False for checkerboard distributions

Return type:

bool

property is_symmetric: bool

Check if the matrix is symmetric.

Returns:

True if matrix is symmetric, False otherwise

Return type:

bool

kendalls_tau() → float[source]

Calculate the tau coefficient more efficiently using numpy’s vectorized operations.

Returns:

The calculated tau coefficient.

Return type:

float

lambda_L()[source]

Lower tail dependence (usually 0 for a checkerboard copula).

lambda_U()[source]

Upper tail dependence (usually 0 for a checkerboard copula).

property pdf

PDF is not available for BivCheckMin.

Raises:

PropertyUnavailableException – Always raised, since PDF does not exist for BivCheckMin.

spearmans_footrule() → float[source]

Compute Spearman’s Footrule (psi) for a BivCheckMin copula.

The value is the footrule of the underlying CheckPi copula plus an add-on term accounting for the singular part of the distribution. Implemented for square checkerboard matrices.

Returns:

The value of Spearman’s Footrule.

Return type:

float

spearmans_rho() → float[source]

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()[source]

Transpose the checkerboard matrix.

class copul.BivCheckPi(matr, *args, **kwargs)[source]

Bases: CheckPi, BivCoreCopula

Bivariate Checkerboard Copula class.

This class implements a bivariate checkerboard copula, which is defined by a matrix of values that determine the copula’s distribution.

blests_nu() → float[source]

Blest’s measure of rank association (nu) for a checkerboard copula.

Closed-form matrix formula:

nu(C^Δ_Π) = (24 / (m^2 n)) * tr(Δ^T K) - 2,

where
K = L_m^T U L_n

  • 1/2 L_m^T U

  • 1/2 U L_n

  • 1/4 U

  • 1/2 L_m^T E L_n

  • 1/4 L_m^T E

  • 1/3 E L_n

  • 1/6 E.

Here:

Δ is the m×n checkerboard matrix, L_m (resp. L_n) are strictly lower-triangular “ones” matrices, E is the m×n all-ones matrix, U = w e_n^T with w_i = m - i + 1.

Returns:

Blest’s nu.

Return type:

float

blomqvists_beta()[source]

Blomqvist’s beta.

chatterjees_xi(condition_on_y: bool = False) → float[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(*args)[source]

F_{U_{-1}|U_1}(u_{-1} | u_1).

cond_distr_2(*args)[source]

F_{U_{-2}|U_2}(u_{-2} | u_2).

classmethod generate_randomly(grid_size: int | list | None = None, n: int = 1)[source]
ginis_gamma() → float[source]
intervals: dict = {}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

For checkerboard copulas, this property is always True.

Returns:

Always True for checkerboard copulas.

Return type:

bool

is_cis(i=1) → bool[source]

Check if the copula is cis.

is_ltd()[source]
property is_symmetric: bool

Check if the copula is symmetric (C(u,v) = C(v,u)).

Returns:

True if the copula is symmetric, False otherwise.

Return type:

bool

kendalls_tau() → float[source]

Calculate the tau coefficient more efficiently using numpy’s vectorized operations.

Returns:

The calculated tau coefficient.

Return type:

float

params: List = []
spearmans_footrule() → float[source]
spearmans_rho() → float[source]

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()[source]

Transpose the checkerboard matrix.

class copul.BivCheckW(matr, *args, **kwargs)[source]

Bases: BivCheckPi

Bivariate checkerboard W-copula (2D only).

The copula is defined as follows:

  1. CDF: Uses a piecewise ‘W-fraction’:

    frac_ij = max(0, frac_x + frac_y - 1)

    where frac_x and frac_y (both in [0,1]) are the proportions of cell (i,j) that lie below (u,v).

  2. Conditional Distribution: Uses a discrete approach:

    • Finds the cell-slice in the conditioning dimension.

    • Denominator: Sum of masses in that slice.

    • Numerator: Sum of slice cells that lie fully below the threshold.

    • cond_distr = numerator / denominator

blests_nu() → float[source]

Blest’s measure (nu) for a BivCheckW copula.

nu(W) = nu(CheckPi) - (2 / m^3) * sum_{i=1}^m (m - i + 1/2) * row_sum_i where row_sum_i = sum_j Δ_{ij}.

cdf(*args)[source]

Compute the CDF at one or multiple points using the W-fraction approach.

This method handles both single-point and multi-point CDF evaluation in an efficient vectorized manner.

Parameters:

*args (array-like or float) – Either: - Two separate coordinates (u, v) of a single point - A single array-like object with coordinates [u, v] of a single point - A 2D array where each row represents a separate point [u, v]

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cdf(0.3, 0.7)

# Single point as array value = copula.cdf([0.3, 0.7])

# Multiple points as 2D array values = copula.cdf(np.array([[0.1, 0.2], [0.3, 0.4]]))

chatterjees_xi(condition_on_y: bool = False) → float[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr(i, *args)[source]

Compute the conditional distribution for one or multiple points.

Parameters:

  • i (int) – Dimension index (1-based) to condition on (1 or 2).

  • *args (array-like or float) – Either: - Two separate coordinates (u, v) of a single point - A single array-like object with coordinates [u, v] of a single point - A 2D array where each row represents a separate point [u, v]

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cond_distr(1, 0.3, 0.7)

# Single point as array value = copula.cond_distr(1, [0.3, 0.7])

# Multiple points as 2D array values = copula.cond_distr(1, np.array([[0.1, 0.2], [0.3, 0.4]]))

classmethod generate_randomly(grid_size: int | list | None = None, n=1)[source]
ginis_gamma() → float[source]

Compute Gini’s Gamma for a BivCheckMin copula.

This method corrects the value from the parent BivCheckPi class. The parent method incorrectly uses the overridden footrule method from this child class, leading to a “contaminated” result that already includes the add-on for the main diagonal integral. We correct this by adding only the missing component from the anti-diagonal integral. Implemented for square checkerboard matrices.

Returns:

The value of Gini’s Gamma.

Return type:

float

property is_absolutely_continuous

Checkerboard W-copula is not absolutely continuous (it has jumps along cell edges).

property is_symmetric

Check if m = n and the matrix is symmetric about the diagonal.

kendalls_tau() → float[source]

Calculate the tau coefficient more efficiently using numpy’s vectorized operations.

Returns:

The calculated tau coefficient.

Return type:

float

lambda_L()[source]

Lower tail dependence (0 for W-copula). Must be lower-equal to BivCheckPi(self.matr).lambda_L() = 0.

lambda_U()[source]

Upper tail dependence (0 for W-copula). Must be lower-equal to BivCheckPi(self.matr).lambda_U() = 0.

property pdf

PDF is not available for BivCheckW.

Raises:

PropertyUnavailableException – Always raised, since PDF does not exist for BivCheckMin.

rvs(n=1, **kwargs)[source]

Generate n random samples.

spearmans_footrule() → float[source]

Compute Spearman’s Footrule (psi) for a BivCheckMin copula.

The value is the footrule of the underlying CheckPi copula plus an add-on term accounting for the singular part of the distribution. Implemented for square checkerboard matrices.

Returns:

The value of Spearman’s Footrule.

Return type:

float

spearmans_rho() → float[source]

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()[source]

Transpose the checkerboard matrix.

class copul.BivClayton(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

Bivariate Clayton Copula.

The Clayton copula is defined by its generator: φ(t) = (t^(-θ) - 1) / θ for θ > 0 φ(t) = -log(t) for θ = 0 φ(t) = (t^(-θ) - 1) / θ for θ ∈ [-1, 0) with restricted range

It allows for asymptotic lower tail dependence but no upper tail dependence.

Parameters:

theta (float) – The parameter controlling the strength of dependence. θ > 0 indicates positive dependence, θ = 0 gives independence, and θ ∈ [-1, 0) gives negative dependence.

blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Clayton copula.

\[\beta = 4\,(2^{-\theta}+2^{-\theta}-1)^{-1/\theta}\cdot \bigl[(\text{at } u=v=\tfrac12)\bigr] - 1\]

For \(\theta > 0\):

\[C(\tfrac12,\tfrac12) = (2^{1-\theta}-1)^{-1/\theta} \cdot 2^{-1} \;\Longrightarrow\; \beta = 4\,(2\cdot 2^{-\theta}-1)^{-1/\theta} - 1\]
cond_distr_1(u=None, v=None)[source]

First conditional distribution function: ∂C(u,v)/∂u

Parameters:

  • u (float or None, optional) – Values to evaluate at. If None, returns the symbolic expression.

  • v (float or None, optional) – Values to evaluate at. If None, returns the symbolic expression.

Returns:

The conditional distribution

Return type:

CD1Wrapper

cond_distr_2(u=None, v=None)[source]

Second conditional distribution function: ∂C(u,v)/∂v

Parameters:

  • u (float or None, optional) – Values to evaluate at. If None, returns the symbolic expression.

  • v (float or None, optional) – Values to evaluate at. If None, returns the symbolic expression.

Returns:

The conditional distribution

Return type:

CD2Wrapper

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True for θ ≥ 0, False otherwise

Return type:

bool

lambda_L()[source]

Lower tail dependence coefficient.

For Clayton copula with θ > 0, this is 2^(-1/θ).

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Upper tail dependence coefficient.

For Clayton copula, this is always 0.

Returns:

Always 0 for Clayton

Return type:

float

property pdf

Probability density function of the bivariate Clayton copula.

Returns:

The PDF function c(u,v)

Return type:

SymPyFuncWrapper

rvs(n: int = 1, random_state: int | None = None, approximate: bool = False) → ndarray[source]

Generate random samples from the Clayton copula using a fast, vectorized algorithm.

This method overrides the slow, iterative solver from the parent class. It uses a numerically stable, closed-form inverse of the conditional distribution, allowing for thousands of samples to be generated almost instantly.

Parameters:

  • n (int) – Number of samples to generate.

  • random_state (int, optional) – Seed for the random number generator for reproducibility.

  • approximate (bool) – This parameter is ignored as the exact vectorized method is always fast.

Returns:

Array of shape (n, 2) containing the generated samples.

Return type:

numpy.ndarray

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Clayton copula.

For \(\theta \ge 0\) the Clayton copula is PQD so \(\sigma = \rho_S\). For \(\theta \in [-1,0)\) it is NQD so \(\sigma = -\rho_S\). In both cases \(\sigma = |\rho_S|\).

special_cases = {-1: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>, 0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta_interval = Interval(-1, oo)
class copul.BivCopula(*args, **kwargs)[source]

Bases: Copula, BivCoreCopula

class copul.BivIndependenceCopula(*args, **kwargs)[source]

Bases: Frechet, BivArchimedeanCopula

Bivariate Independence Copula implementation.

The independence copula represents statistical independence between random variables: C(u,v) = u*v

This is a special case of both the Frechet family (with alpha=beta=0) and the Archimedean family (with generator -log(t)).

property alpha
property beta
property cdf

C(u,v) = u*v

Type:

CDF of the independence copula

cond_distr_1(u=None, v=None)[source]

Conditional distribution: C_2(v|u) = v

For an independence copula, the conditional distribution of v given u is just v.

cond_distr_2(u=None, v=None)[source]

Conditional distribution: C_1(u|v) = u

For an independence copula, the conditional distribution of u given v is just u.

lambda_L()[source]

Lower tail dependence coefficient (= 0 for independence).

lambda_U()[source]

Upper tail dependence coefficient (= 0 for independence).

property pdf

PDF of the independence copula is constant 1 on the unit square.

property pickands
class copul.CISRearranger(checkerboard_size: int | None = None)[source]

Bases: object

Class for rearranging copulas to be conditionally increasing in sequence (CIS).

The rearrangement preserves the checkerboard approximation’s margins while creating an ordering such that the conditional distribution functions are ordered decreasingly with respect to the conditioning value.

_checkerboard_size

Size of the checkerboard grid for approximating copulas

static rearrange_checkerboard(ccop: BivCheckPi | List[List[float]] | ndarray[tuple[Any, ...], dtype[_ScalarT]] | MutableDenseMatrix | Any) → MutableDenseMatrix[source]

Rearrange a checkerboard copula to be conditionally increasing in sequence (CIS), using numeric (NumPy) operations for speed. Implements Algorithm 1 from Strothmann, Dette, Siburg (2022).

Parameters:

ccop (Union[BivCheckPi, list, np.ndarray, sympy.Matrix, Any]) –

The checkerboard copula to rearrange. Can be:

  • a BivCheckPi instance,

  • a 2D list of floats,

  • a 2D numpy.ndarray,

  • a sympy.Matrix,

  • or any object with a .matr attribute containing one of the above.

Returns:

The density matrix of the rearranged copula, with shape (n_rows, n_cols). Each entry is a sympy-compatible expression (usually float).

Return type:

sympy.Matrix

rearrange_copula(copula: Any) → MutableDenseMatrix[source]

Rearrange a copula to be conditionally increasing in sequence.

Parameters:

copula – A copula object or BivCheckPi object to rearrange

Returns:

A sympy Matrix representing the rearranged copula’s density

static verify_cis_property(matrix: ndarray | Any) → bool[source]

Verify that a matrix has the conditionally increasing in sequence property.

Parameters:

matrix – The matrix to check

Returns:

True if the matrix has the CIS property, False otherwise

Return type:

bool

class copul.CISVerifier(cond_distr=1)[source]

Bases: object

Verifier for Comprehensive Increasing/Decreasing Stochasticity (CIS) property of copulas. Also known as stochastically increasing/decreasing copulas (CI/CD).

is_cis(copul, range_min=None, range_max=None)[source]

Check if the copula satisfies CIS property.

Parameters:

copulCopula

Copula to check

range_minfloat, optional

Minimum value for parameter range

range_maxfloat, optional

Maximum value for parameter range

Returns:

tuple

(is_ci, is_cd) - whether the copula is CI/CD

class copul.CheckMin(matr, *args, **kwargs)[source]

Bases: Check

Checkerboard “Min” Copula

This copula implements a “min-fraction” approach for computing the cumulative distribution function (CDF) across all dimensions, and a fully discrete method for calculating conditional distributions.

Key features:
  • CDF Calculation:

    Uses a min-fraction partial coverage over all dimensions to aggregate the CDF.

  • Conditional Distribution (cond_distr):
    For any given dimension i and input vector u:

    1. In dimension i, determine the cell index as floor(u[i] * dim[i]). The entire slice corresponding to this index constitutes the conditioning event (denominator).

    2. In every other dimension j ≠ i, only include cells where the cell index c[j] is strictly less than floor(u[j] * dim[j]); this avoids any partial coverage in these dimensions.

    3. Compute the conditional distribution as the ratio of the count of cells meeting the numerator condition (cells matching the target criteria) to the total count of cells in the conditioning event (denominator).

Example

For a 2x2x2 grid and u = (0.5, 0.5, 0.5):

  • In dimension 0, we use floor(0.5 * 2) = 1, selecting the second layer.

  • Within that layer, for dimensions 1 and 2, only cells with indices less than floor(0.5 * 2) = 1 are considered (i.e., only cells with index 0).

  • This results in 1 favorable cell out of 4 in the conditioning event, so:

    cond_distr(1, (0.5, 0.5, 0.5)) = 1 / 4 = 0.25.

cdf(*args)[source]

Compute the CDF at one or multiple points.

This method handles both single-point and multi-point CDF evaluation in an efficient vectorized manner, using the ‘min-fraction’ approach specific to CheckMin.

Parameters:

*args (array-like or float) – Either: - Multiple separate coordinates (x, y, …) of a single point - A single array-like object with coordinates of a single point - A 2D array where each row represents a separate point

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cdf(0.3, 0.7)

# Single point as array value = copula.cdf([0.3, 0.7])

# Multiple points as 2D array values = copula.cdf(np.array([[0.1, 0.2], [0.3, 0.4]]))

cond_distr(i, *args)[source]

Compute the conditional distribution for one or multiple points.

Parameters:

  • i (int) – Dimension index (1-based) to condition on.

  • *args (array-like or float) – Either: - Multiple separate coordinates (x, y, …) of a single point - A single array-like object with coordinates of a single point - A 2D array where each row represents a separate point

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cond_distr(1, 0.3, 0.7)

# Single point as array value = copula.cond_distr(1, [0.3, 0.7])

# Multiple points as 2D array values = copula.cond_distr(1, np.array([[0.1, 0.2], [0.3, 0.4]]))

property is_absolutely_continuous: bool
property pdf
rvs(n=1, random_state=None, **kwargs)[source]

More efficient implementation of random variate sampling.

class copul.CheckPi(matr, *args, **kwargs)[source]

Bases: Check, CopulaPlottingMixin, CopulaApproximatorMixin

cdf(*args)[source]

Compute the CDF at one or multiple points.

This method handles both single-point and multi-point CDF evaluation in an efficient vectorized manner.

Parameters:

*args (array-like or float) – Either: - Multiple separate coordinates (x, y, …) of a single point - A single array-like object with coordinates of a single point - A 2D array where each row represents a separate point

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cdf(0.3, 0.7)

# Single point as array value = copula.cdf([0.3, 0.7])

# Multiple points as 2D array values = copula.cdf(np.array([[0.1, 0.2], [0.3, 0.4]]))

cond_distr(i, *args)[source]

Compute the conditional distribution for one or multiple points.

Parameters:

  • i (int) – Dimension index (1-based) to condition on.

  • *args (array-like or float) – Either: - Multiple separate coordinates (x, y, …) of a single point - A single array-like object with coordinates of a single point - A 2D array where each row represents a separate point

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.cond_distr(1, 0.3, 0.7)

# Single point as array value = copula.cond_distr(1, [0.3, 0.7])

# Multiple points as 2D array values = copula.cond_distr(1, np.array([[0.1, 0.2], [0.3, 0.4]]))

cond_distr_1(u)[source]

F_{U_{-1}|U_1}(u_{-1} | u_1).

cond_distr_2(u)[source]

F_{U_{-2}|U_2}(u_{-2} | u_2).

property is_absolutely_continuous: bool
property is_symmetric: bool
lambda_L()[source]

Lower tail dependence (usually 0 for a checkerboard copula).

lambda_U()[source]

Upper tail dependence (usually 0 for a checkerboard copula).

pdf(*args)[source]

Evaluate the piecewise PDF at one or multiple points.

Parameters:

*args (array-like or float) – Either: - Multiple separate coordinates (x, y, …) of a single point - A single array-like object with coordinates of a single point - A 2D array where each row represents a separate point

Returns:

If a single point is provided, returns a float. If multiple points are provided, returns an array of shape (n_points,).

Return type:

float or numpy.ndarray

Examples

# Single point as separate arguments value = copula.pdf(0.3, 0.7)

# Single point as array value = copula.pdf([0.3, 0.7])

# Multiple points as 2D array values = copula.pdf(np.array([[0.1, 0.2], [0.3, 0.4]]))

rvs(n=1, random_state=None, **kwargs)[source]

Draw random variates from the d-dimensional checkerboard copula efficiently.

Parameters:

  • n (int) – Number of samples to generate.

  • random_state (int, optional) – Seed for random number generator.

Returns:

Array of shape (n, d) containing n samples in d dimensions.

Return type:

np.ndarray

class copul.Checkerboarder(n: int | list = None, dim=2, checkerboard_type='CheckPi')[source]

Bases: object

approximate_shuffle_of_min(copula=None, cmatr=None, order=None)[source]

Fit a Shuffle-of-Min copula to a checkerboard mass matrix by solving an assignment problem that maximizes the captured mass.

Parameters:

  • copula (optional) – If provided, we first compute the checkerboard mass for this copula. Ignored if cmatr is provided.

  • cmatr (np.ndarray, optional) – Precomputed checkerboard mass matrix. If provided, we use it directly.

  • order (int, optional) – Desired SoM order. If None, uses the grid size if square; if not, tries to down/up-sample to a square matrix of size order.

Return type:

ShuffleOfMin

from_data(data: DataFrame | ndarray | list)[source]
get_checkerboard_copula(copula, n_jobs=None)[source]

Compute the checkerboard representation of a copula’s CDF.

copul.Clayton

alias of BivClayton

class copul.CuadrasAuge(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

Cuadras-Auge copula, special case of the Marshall-Olkin copula.

blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Cuadras-Augé copula.

\[\beta = 4\,C(\tfrac12,\tfrac12) - 1 = 4\cdot 2^{-\delta}\cdot 2^{-(2-2\delta)} - 1 = 2^{2-\delta} \cdot 2^{-2+2\delta}\cdot 4 - 1 \;=\; 2^{\delta} - 1\]
chatterjees_xi(*args, **kwargs)[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(u=None, v=None)[source]

First conditional distribution \(\partial C/\partial u\).

Uses exact boundary values where possible, otherwise numerical finite differences on cdf_vectorized().

Parameters:

  • u (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

  • v (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

Returns:

Value of \(\partial C(u,v)/\partial u\).

Return type:

float

delta = delta
gini_gamma(*args, **kwargs)[source]

Gini’s \(\gamma\) for the Cuadras-Augé copula.

\[\gamma = 4\!\left[\int_0^1 C(t,t)\,dt + \int_0^1 C(t,1{-}t)\,dt\right] - 2\]

For the CA copula, \(C(t,t) = t^{2-\delta}\) (since \(\min(t,t)=t\)), so the diagonal integral is \(1/(3-\delta)\). The anti-diagonal \(C(t,1-t)\) requires splitting at \(t=1/2\).

hoeffdings_d(*args, **kwargs)[source]

Hoeffding’s \(D\) for the Cuadras-Augé copula.

Expanding the double integral \(90\iint(C-uv)^2\,du\,dv\) over the two regions \(\{v \le u\}\) and \(\{u < v\}\) (using symmetry) gives:

\[D(\delta) = \frac{10\,\delta^{2}} {18 - 9\,\delta + \delta^{2}}\]

which satisfies \(D(0)=0\) and \(D(1)=1\).

intervals: dict = {'delta': Interval(0, 1)}
property is_absolutely_continuous

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Compute Spearman’s \(\rho\).

Returns:

Symbolic expression of Spearman’s \(\rho\).

Return type:

sympy.Expr

params: list = [delta]
property pdf

Probability density function of the copula.

Returns:

Wrapper around the symbolic or numerical PDF.

Return type:

SymPyFuncWrapper

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Cuadras-Augé copula.

The CA copula is PQD for all \(\delta \in (0,1]\), so \(\sigma = \rho_S = 3\delta/(4-\delta)\).

spearman_footrule(*args, **kwargs)[source]

Spearman’s footrule \(\psi\) for the Cuadras-Augé copula.

\[\psi = 6\int_0^1 C(t,t)\,dt - 2 = \frac{6}{3-\delta} - 2 = \frac{2\delta}{3-\delta}\]
spearmans_rho(*args, **kwargs)[source]

Spearman’s \(\rho\) for the extreme value copula.

Parameters:

  • *args – Copula parameters.

  • **kwargs – Copula parameters.

Returns:

Symbolic expression of Spearman’s \(\rho\).

Return type:

sympy.Expr

class copul.DiagonalBandCopula(*args, **kwargs)[source]

Bases: BivCopula

Bojarski-type diagonal band copula (uniform band along \(y=x\)).

A stripe of half-width \(\alpha\) is laid along the main diagonal and wrapped/reflected at the unit square’s borders so that both marginals remain uniform.

Following Bojarski (2002, J. Math. Sci., Eq. (1)) with a constant base density

\[f(z) \;=\; \frac{1}{2\alpha}\,\mathbf{1}\{|z|\le \alpha\}, \quad z\in\mathbb{R},\]

supported on \([-\alpha,\alpha]\). Using a different symmetric base density (e.g., rescaled Beta) is a straightforward extension, but the uniform band already reproduces the classical diagonal-band example discussed in the paper.

Parameters:

alpha (float in (0, 1]) – Half-width of the diagonal band.

alpha = alpha
cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

intervals: dict = {'alpha': Interval.Lopen(0, 1)}
property is_absolutely_continuous

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

params: list = [alpha]
property pdf

Piecewise density \(g_\alpha(u,v)\) of the diagonal-band construction.

With the base density \(f(z)=\tfrac{1}{2\alpha}\mathbf{1}\{|z|\le \alpha\}\), the copula density is

\[\begin{split}g_\alpha(u,v) \;=\; \begin{cases} f(u-v) + f(u+v), & u+v \le \alpha,\\[0.5ex] f(u-v), & \alpha < u+v < 2-\alpha,\\[0.5ex] f(u-v) + f(u+v-2), & u+v \ge 2-\alpha, \end{cases}\end{split}\]

which enforces uniform margins by wrapping the diagonal band near the corners.

class copul.Families(*values)[source]

Bases: Enum

Registry of all copulas with lazy import of their classes.

ALI_MIKHAIL_HAQ = 'copul.family.archimedean.AliMikhailHaq'
BB5 = 'copul.family.extreme_value.BB5'
BERNSTEIN = 'copul.checkerboard.bernstein.Bernstein'
BIV_CHECK_MIN = 'copul.checkerboard.biv_check_min.BivCheckMin'
BIV_CHECK_PI = 'copul.checkerboard.biv_check_pi.BivCheckPi'
BIV_CHECK_W = 'copul.checkerboard.biv_check_w.BivCheckW'
CHECK_MIN = 'copul.checkerboard.check_min.CheckMin'
CHECK_PI = 'copul.checkerboard.check_pi.CheckPi'
CLAYTON = 'copul.family.archimedean.Clayton'
CUADRAS_AUGE = 'copul.family.extreme_value.CuadrasAuge'
DIAGONAL_BAND = 'copul.family.other.DiagonalBandCopula'
FARLIE_GUMBEL_MORGENSTERN = 'copul.family.other.FarlieGumbelMorgenstern'
FRANK = 'copul.family.archimedean.Frank'
FRECHET = 'copul.family.other.Frechet'
GALAMBOS = 'copul.family.extreme_value.Galambos'
GAUSSIAN = 'copul.family.elliptical.Gaussian'
GENEST_GHOUDI = 'copul.family.archimedean.GenestGhoudi'
GUMBEL_BARNETT = 'copul.family.archimedean.GumbelBarnett'
GUMBEL_HOUGAARD = 'copul.family.archimedean.GumbelHougaard'
GUMBEL_HOUGAARD_EV = 'copul.family.extreme_value.GumbelHougaardEV'
HUESLER_REISS = 'copul.family.extreme_value.HueslerReiss'
INDEPENDENCE = 'copul.family.other.IndependenceCopula'
JOE = 'copul.family.archimedean.Joe'
JOE_EV = 'copul.family.extreme_value.JoeEV'
LOWER_FRECHET = 'copul.family.other.LowerFrechet'
MARDIA = 'copul.family.other.Mardia'
MARSHALL_OLKIN = 'copul.family.extreme_value.MarshallOlkin'
NELSEN1 = 'copul.family.archimedean.Nelsen1'
NELSEN10 = 'copul.family.archimedean.Nelsen10'
NELSEN11 = 'copul.family.archimedean.Nelsen11'
NELSEN12 = 'copul.family.archimedean.Nelsen12'
NELSEN13 = 'copul.family.archimedean.Nelsen13'
NELSEN14 = 'copul.family.archimedean.Nelsen14'
NELSEN15 = 'copul.family.archimedean.Nelsen15'
NELSEN16 = 'copul.family.archimedean.Nelsen16'
NELSEN17 = 'copul.family.archimedean.Nelsen17'
NELSEN18 = 'copul.family.archimedean.Nelsen18'
NELSEN19 = 'copul.family.archimedean.Nelsen19'
NELSEN2 = 'copul.family.archimedean.Nelsen2'
NELSEN20 = 'copul.family.archimedean.Nelsen20'
NELSEN21 = 'copul.family.archimedean.Nelsen21'
NELSEN22 = 'copul.family.archimedean.Nelsen22'
NELSEN3 = 'copul.family.archimedean.Nelsen3'
NELSEN4 = 'copul.family.archimedean.Nelsen4'
NELSEN5 = 'copul.family.archimedean.Nelsen5'
NELSEN6 = 'copul.family.archimedean.Nelsen6'
NELSEN7 = 'copul.family.archimedean.Nelsen7'
NELSEN8 = 'copul.family.archimedean.Nelsen8'
NELSEN9 = 'copul.family.archimedean.Nelsen9'
PI_OVER_SIGMA_MINUS_PI = 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'
PLACKETT = 'copul.family.other.Plackett'
RAFTERY = 'copul.family.other.Raftery'
SHUFFLE_OF_MIN = 'copul.checkerboard.shuffle_min.ShuffleOfMin'
T = 'copul.family.elliptical.StudentT'
TAWN = 'copul.family.extreme_value.Tawn'
T_EV = 'copul.family.extreme_value.tEV'
UPPER_FRECHET = 'copul.family.other.UpperFrechet'
XI_NU_BOUNDARY = 'copul.family.other.XiNuBoundaryCopula'
XI_PSI_BOUNDARY = 'copul.family.other.XiPsiApproxLowerBoundaryCopula'
XI_RHO_BOUNDARY = 'copul.family.other.XiRhoBoundaryCopula'
property cls
classmethod compare_copulas(u: ndarray, families: List[str] | None = None, fit_method: str = 'ml', criteria: str = 'aic') → List[Dict][source]

Compare multiple copula families on the same dataset.

Parameters:

  • u (ndarray) – Pseudo-observations in [0,1]^d.

  • families (list[str] | None) – Enum NAMES to compare; defaults to a common set.

  • fit_method (str) – Method for .fit(), e.g. ‘ml’ (if available).

  • criteria ({'aic','bic','likelihood'}) – Sorting metric; lower is better for aic/bic, higher is better for likelihood.

Returns:

Sorted list of results with keys: ‘family’, ‘copula’, ‘score’, ‘params’.

Return type:

list[dict]

classmethod create(family_name: str, *args, **kwargs)[source]

Instantiate a copula by enum NAME with parameters.

classmethod get_category(family: Families | str) → FamilyCategory[source]

Mathematical category based on import path.

classmethod get_kind(member: Families) → CopulaKind[source]
classmethod get_params_info(family_name: str) → Dict[source]

Inspect __init__ signature and basic param doc of a copula class.

classmethod list_all() → List[str][source]

UPPER_CASE enum names of true modeling families.

classmethod list_all_classnames(lowercase: bool = False) → List[str][source]

Class names of true families (sorted).

classmethod list_approx_classnames(lowercase: bool = False) → List[str][source]

Class names of approximation constructs (sorted).

classmethod list_approximations() → List[str][source]

UPPER_CASE enum names of approximation constructs.

classmethod list_by_category(category: FamilyCategory | str) → List[str][source]

UPPER_CASE enum names of true families within a given category.

classmethod list_classes(kind: CopulaKind | str | None = None, category: FamilyCategory | str | None = None) → List[type][source]

Same as list_names but returns the class objects.

classmethod list_names(kind: CopulaKind | str | None = None, category: FamilyCategory | str | None = None) → List[str][source]

Enum names filtered by semantic kind and/or mathematical category. kind : {‘family’,’approximation’,’special’} or None category : {‘archimedean’,’elliptical’,’extreme_value’,’other’} or None

classmethod list_special_classnames(lowercase: bool = False) → List[str][source]

Class names of notable/special copulas (sorted).

classmethod list_specials() → List[str][source]

UPPER_CASE enum names of notable/special copulas.

class copul.FarlieGumbelMorgenstern(*args, **kwargs)[source]

Bases: BivCopula

Farlie-Gumbel-Morgenstern (FGM) Copula.

The FGM copula is defined as: C(u,v) = u*v + theta*u*v*(1-u)*(1-v)

It has limited dependence range with Spearman’s rho in [-1/3, 1/3] and Kendall’s tau in [-2/9, 2/9].

Parameters:

thetafloat, -1 ≤ theta ≤ 1

Dependence parameter that determines the strength and direction of dependence. theta = 0 gives the independence copula. theta > 0 indicates positive dependence. theta < 0 indicates negative dependence.

blests_nu()[source]

Compute Blest’s rank correlation ν.

Uses the copula form

ν(C) = 24 ∫_0^1 ∫_0^1 (1 - u) C(u, v) du dv - 2

which is linear in C and generally symbolic-friendly.

Returns:

The symbolic expression for Blest’s ν.

Return type:

sympy.Expr

property cdf

Cumulative distribution function of the copula.

C(u,v) = u*v + theta*u*v*(1-u)*(1-v)

cond_distr_2(u=None, v=None)[source]

Conditional distribution function with respect to v.

C_{2}(u,v) = u + theta*u*(1-u)*(1-2*v)

ginis_gamma()[source]

Calculate Gini’s gamma for the FGM copula.

For FGM, Gini’s gamma = 4*theta/15

hoeffdings_d(*args, **kwargs)[source]

Hoeffding’s \(D\) for the FGM copula.

\[D = 90\,\theta^2 \left[\int_0^1 t^2(1-t)^2\,dt\right]^2 = \frac{\theta^2}{10}\]
intervals: dict = {'theta': Interval(-1, 1)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the FGM copula.

For FGM, tau = 2*theta/9

lp_concordance(p: int = 2, *args, **kwargs)[source]

\(L_p\) concordance distance for the FGM copula.

\[\delta_p = k(p)\,|\theta|^p \left[\operatorname{B}(p+1,\,p+1)\right]^2\]

where \(\operatorname{B}\) is the beta function.

mutual_information(*args, **kwargs)[source]

Mutual information for the FGM copula (numerical).

The density is \(c(u,v) = 1 + \theta(1-2u)(1-2v)\). No known simple closed form for \(\int c \ln c\); delegates to the base-class numerical quadrature.

params: list = [theta]
property pdf

Probability density function of the copula.

c(u,v) = 1 + theta*(1-2*u)*(1-2*v)

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the FGM copula.

Since \(C - \Pi = \theta\,u\,v\,(1-u)(1-v)\) has constant sign (PQD when \(\theta>0\), NQD when \(\theta<0\)):

\[\sigma = 12\,|\theta|\, \left[\int_0^1 t(1-t)\,dt\right]^2 = \frac{|\theta|}{3}\]
spearmans_footrule()[source]
spearmans_rho(*args, **kwargs)[source]

Calculate Spearman’s rho for the FGM copula.

For FGM, rho = theta/3

theta = theta
class copul.Frank(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

blests_nu()[source]

Compute Blest’s rank correlation ν.

Uses the copula form

ν(C) = 24 ∫_0^1 ∫_0^1 (1 - u) C(u, v) du dv - 2

which is linear in C and generally symbolic-friendly.

Returns:

The symbolic expression for Blest’s ν.

Return type:

sympy.Expr

blomqvist()[source]
blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Frank copula.

\[\beta = 1 - \frac{4}{\theta}\,\ln\!\cosh\!\bigl(\tfrac{\theta}{4}\bigr)\]

(The Frank CDF at \((1/2,1/2)\) has a neat log-cosh form.)

cdf_vectorized(u: ndarray, v: ndarray) → ndarray[source]

Vectorized implementation of the cumulative distribution function for the Frank copula.

This method uses the explicit mathematical formula for the Frank copula, which is significantly faster than the generic generator-based approach.

Parameters:

  • u (array_like) – First uniform marginal, must be in [0, 1].

  • v (array_like) – Second uniform marginal, must be in [0, 1].

Returns:

The CDF values at the specified points.

Return type:

numpy.ndarray

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the Frank copula using numerical integration.

For theta = 0, returns 0 (independence).

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

rvs(n: int = 1, random_state: int | None = None, approximate: bool = False) → ndarray[source]

Generate random samples from the Frank copula using a fast, vectorized algorithm.

This method uses a numerically stable, closed-form inverse of the conditional distribution, allowing for thousands of samples to be generated almost instantly.

Parameters:

  • n (int) – Number of samples to generate.

  • random_state (int, optional) – Seed for the random number generator for reproducibility.

  • approximate (bool) – This parameter is ignored as the exact vectorized method is always fast.

Returns:

Array of shape (n, 2) containing the generated samples.

Return type:

numpy.ndarray

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Frank copula.

The Frank copula is PQD for \(\theta > 0\) and NQD for \(\theta < 0\), so \(\sigma = |\rho_S|\).

spearmans_rho(*args, **kwargs)[source]

Calculate Spearman’s rho for the Frank copula using numerical integration.

For theta = 0, returns 0 (independence).

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta_interval = Interval(-oo, oo)
class copul.Frechet(*args, **kwargs)[source]

Bases: BivCopula

Bivariate Fréchet copula (a convex combination of the upper/lower Fréchet bounds and independence).

Parameters:

  • alpha (\(\alpha \in [0,1]\)) – Weight of the upper Fréchet bound \(\min(u,v)\).

  • beta (\(\beta \in [0,1]\)) – Weight of the lower Fréchet bound \(\max(u+v-1,0)\).

Notes

The CDF is

\[C(u,v) \;=\; \alpha\,\min(u,v) \;+\; (1-\alpha-\beta)\,u\,v \;+\; \beta\,\max(u+v-1,0).\]

The parameter domain must satisfy \(\alpha\ge 0\), \(\beta\ge 0\) and \(\alpha+\beta \le 1\).

The copula is absolutely continuous iff \(\alpha=\beta=0\).

property alpha
property beta
blests_nu(*args, **kwargs)[source]

Blest’s measure of rank correlation ν. For the Fréchet copula: ν = α − β.

property cdf

Cumulative distribution function

\[C(u,v) \;=\; \alpha\,\min(u,v) \;+\; (1-\alpha-\beta)\,u\,v \;+\; \beta\,\max(u+v-1,0).\]
cdf_vectorized(u, v)[source]

Vectorized CDF on many points.

Parameters:

  • u (array_like) – Uniform marginals in \([0,1]\).

  • v (array_like) – Uniform marginals in \([0,1]\).

Returns:

Values of \(C(u,v)\).

Return type:

numpy.ndarray

Notes

Uses NumPy broadcasting; implements the same formula as above.

chatterjees_xi(*args, **kwargs)[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

ginis_gamma(*args, **kwargs)[source]

Gini’s gamma \(\gamma\).

For the Fréchet copula,

\[\gamma \;=\; \alpha \;-\; \beta,\]

which coincides with Spearman’s \(\rho_S\) for this family.

intervals: dict = {'alpha': Interval(0, 1), 'beta': Interval(0, 1)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether \(C(u,v)=C(v,u)\) (always True for this family).

kendalls_tau(*args, **kwargs)[source]

Kendall’s \(\tau\)

\[\tau \;=\; \frac{(\alpha-\beta)\,\bigl(2+\alpha+\beta\bigr)}{3}.\]
property lambda_L

Compute the lower tail dependence coefficient.

Returns:

The symbolic expression for the lower tail dependence.

Return type:

sympy.Expr

property lambda_U

Compute the upper tail dependence coefficient.

Returns:

The simplified symbolic expression for the upper tail dependence.

Return type:

sympy.Expr

params: list = [alpha, beta]
property pdf

Evaluate (or partially evaluate) the PDF: ∂^d C / ∂u1 … ∂ud

spearmans_footrule(*args, **kwargs)[source]

Spearman’s footrule \(\psi \;=\; \mathbb{E}\,\lvert U-V\rvert\).

Closed form:

\[\psi \;=\; \alpha \;-\; \tfrac{1}{2}\,\beta.\]
spearmans_rho(*args, **kwargs)[source]

Spearman’s rank correlation

\[\rho_S \;=\; \alpha \;-\; \beta.\]
class copul.Galambos(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

Galambos extreme value copula with parameter \(\delta > 0\).

CDF:

C(u,v) = u v exp( ((-log u)^(-delta) + (-log v)^(-delta))^(-1/delta) )

for (u,v) in (0,1]^2, with the usual boundary extensions.

cdf(u=None, v=None, **kwargs)[source]

Evaluate the CDF numerically via cdf_vectorized.

delta = delta
intervals: dict = {'delta': Interval.open(0, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

params: list = [delta]
property pdf

Numerical PDF via finite differences on cdf_vectorized.

class copul.Gaussian(*args, **kwargs)[source]

Bases: MultivariateGaussian, EllipticalCopula

Bivariate Gaussian copula.

Extends MultivariateGaussian for the 2-dimensional case. Characterized by a correlation parameter \(\rho \in [-1,1]\).

Special cases

  • \(\rho=-1\): Lower Fréchet bound (countermonotone)

  • \(\rho=0\): Independence

  • \(\rho=1\): Upper Fréchet bound (comonotone)

blests_nu()[source]

Compute Blest’s rank correlation ν.

Uses the copula form

ν(C) = 24 ∫_0^1 ∫_0^1 (1 - u) C(u, v) du dv - 2

which is linear in C and generally symbolic-friendly.

Returns:

The symbolic expression for Blest’s ν.

Return type:

sympy.Expr

blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Gaussian copula.

\[\beta(\rho) = \frac{2}{\pi}\,\arcsin(\rho)\]
Return type:

float

property cdf

Compute the cumulative distribution function of the Gaussian copula.

For the bivariate case, this can use the statsmodels implementation for efficiency.

Returns:

Function that computes the CDF at given points

Return type:

callable

cdf_vectorized(u, v)[source]

Vectorized CDF for the bivariate Gaussian copula.

Evaluates \(C(u,v)\) at many points simultaneously.

Parameters:

  • u (array_like) – First uniform marginal, values in \([0,1]\).

  • v (array_like) – Second uniform marginal, values in \([0,1]\).

Returns:

CDF values at the specified points.

Return type:

numpy.ndarray

Notes

This implementation leverages the compiled backend in statsmodels. The defining relation is

\[C(u,v) \;=\; \Phi_{\rho}\!\bigl(\Phi^{-1}(u),\,\Phi^{-1}(v)\bigr),\]

where \(\Phi\) is the standard normal CDF and \(\Phi_{\rho}\) is the bivariate normal CDF with correlation \(\rho\).

chatterjees_xi(*args, **kwargs)[source]

Chatterjee’s \(\xi\) dependence measure for the Gaussian copula.

Returns:

Value of \(\xi\).

Return type:

float

cond_distr_1(u=None, v=None)[source]

First conditional distribution \(C(v\mid u)\).

Parameters:

  • u (float, optional) – Conditioning value.

  • v (float, optional) – Evaluation point.

Returns:

Wrapped conditional distribution function or value.

Return type:

SymPyFuncWrapper

cond_distr_2(u=None, v=None)[source]

Second conditional distribution \(C(u\mid v)\).

Parameters:

  • u (float, optional) – Evaluation point.

  • v (float, optional) – Conditioning value.

Returns:

Wrapped conditional distribution function or value.

Return type:

SymPyFuncWrapper

generator = exp(-t/2)
gini_gamma(*args, **kwargs)[source]

Gini’s \(\gamma\) for the Gaussian copula.

\[\gamma(\rho) = \frac{8}{\pi}\,\arcsin(\rho/2)\]

See Nelsen (2006), Exercise 5.19.

Return type:

float

hoeffdings_d(*args, **kwargs)[source]

Hoeffding’s \(D\) for the Gaussian copula (numerical).

No simple closed form is known. Falls back to base-class numerical quadrature.

Return type:

float

kendalls_tau(*args, **kwargs)[source]

Kendall’s \(\tau\) for the Gaussian copula.

Returns:

Value of \(\tau\).

Return type:

float

lambda_L()[source]

Lower tail dependence for the Gaussian copula.

The Gaussian copula has no tail dependence for \(\rho < 1\):

\[\lambda_L = 0 \quad\text{for } \rho \in [-1, 1).\]
Returns:

Always 0 (unless \(\rho = 1\), comonotonic limit).

Return type:

float

lambda_U()[source]

Upper tail dependence for the Gaussian copula.

Same as lambda_L() — zero for \(\rho < 1\).

Return type:

float

property pdf

Probability density function of the Gaussian copula.

In the bivariate case, this uses the optimized statsmodels implementation.

Returns:

Function that computes \(c(u,v)\) at given points \((u,v)\in(0,1)^2\).

Return type:

callable

rvs(n=1, approximate=False, random_state=None, **kwargs)[source]

Generate random samples from the Gaussian copula.

For the bivariate case, a fast implementation from statsmodels is used.

Parameters:

  • n (int, default 1) – Number of samples to generate.

  • approximate (bool, default False) – If True, use the project’s generic approximating sampler.

  • random_state (int or numpy.random.Generator, optional) – Seed or generator for reproducibility.

  • **kwargs – Passed to the multivariate sampler when dim > 2.

Returns:

Array of shape \((n,2)\) with samples on \([0,1]^2\).

Return type:

numpy.ndarray

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Gaussian copula.

The bivariate Gaussian copula is PQD when \(\rho \ge 0\) and NQD when \(\rho < 0\), so the absolute value in the definition of \(\sigma\) is redundant:

\[\sigma(\rho) = \lvert\rho_S\rvert = \frac{6}{\pi}\,\bigl|\!\arcsin(\rho/2)\bigr|\]
Return type:

float

spearmans_footrule(*args, **kwargs) → float[source]

Spearman’s footrule \(F = \mathbb{E}\,\lvert U - V\rvert\) for the Gaussian copula.

Closed form:

\[F(\rho) \;=\; \tfrac{1}{2} \;-\; \frac{3}{\pi}\,\arcsin\!\Bigl(\frac{1+\rho}{2}\Bigr).\]
Returns:

Footrule distance in \([0, \tfrac12]\).

Return type:

float

spearmans_rho(*args, **kwargs)[source]

Spearman’s rank correlation \(\rho_{\!S}\) for the Gaussian copula.

Returns:

Value of \(\rho_{\!S}\).

Return type:

float

t = t
tail_order()[source]

Tail order for the Gaussian copula.

\[\kappa_L = \kappa_U = \frac{1}{1 - \rho}\]

for \(-1 \le \rho < 1\).

Return type:

dict

class copul.GenestGhoudi(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {1: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>}
theta = theta
theta_interval = Interval(1, oo)
class copul.GumbelBarnett(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, 1)
class copul.GumbelHougaard(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Gumbel-Hougaard copula.

\[\beta = 4\,(2^{-1/\theta} + 2^{-1/\theta} - 1)^{1/\theta}\cdot ... - 1\]

The diagonal section \(C(t,t) = t^{2-2^{1-1/\theta}}\) is NOT exact for GH (it uses the Pickands form). Evaluate directly:

\[C(\tfrac12,\tfrac12) = \exp\!\bigl(-[(-\ln\tfrac12)^\theta + (-\ln\tfrac12)^\theta]^{1/\theta}\bigr) = \exp\bigl(-2^{1/\theta}\ln 2\bigr) = 2^{-2^{1/\theta}}\]
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

rvs(n: int = 1, random_state: int | None = None, approximate: bool = False) → ndarray[source]

Fast vectorized Marshall–Olkin sampler for Gumbel–Hougaard.

Steps:

  1. α = 1/θ

  2. Sample V ~ positive α-stable via Kanter’s method

  3. Sample E1,E2 ~ Exp(1) i.i.d.

  4. Return (U, V) with U = exp(-(E1/V)^α), V = exp(-(E2/V)^α)

Independence (θ≈1) is handled by returning U(0,1)^2 directly.

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Gumbel-Hougaard copula.

GH is PQD for \(\theta \ge 1\), so \(\sigma = \rho_S\).

spearmans_footrule(*args, **kwargs)[source]

Compute Spearman’s footrule (ψ) for the Gumbel–Hougaard copula.

Closed-form expression:

ψ(C_θ) = 6 / (2^(1/θ) + 1) - 2

For θ = 1 (independence), this yields ψ = 0. As θ → ∞ (comonotonicity), this yields ψ = 1.

Returns:

Spearman’s footrule value (ψ).

Return type:

float

special_cases = {1: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(1, oo)
class copul.GumbelHougaardEV(*args, **kwargs)[source]

Bases: MultivariateGumbelHougaard, BivExtremeValueCopula

Bivariate Gumbel-Hougaard Extreme Value Copula.

A specialized version of the multivariate Gumbel-Hougaard copula for the bivariate case. This copula combines features of both the bivariate extreme value copula and the multivariate Gumbel-Hougaard copula.

The CDF is given by: C(u,v) = exp(-(((-ln u)^θ + (-ln v)^θ)^(1/θ)))

Special cases: - θ = 1: Independence copula - θ → ∞: Comonotonicity copula (perfect positive dependence)

Parameters:

theta (float, optional) – Dependence parameter (default is None). Must be greater than or equal to 1.

intervals: dict = {'theta': Interval(1, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

The Gumbel-Hougaard copula is absolutely continuous.

Returns:

True

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

The Gumbel-Hougaard copula is symmetric.

Returns:

True

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Compute Kendall’s tau for the Gumbel-Hougaard copula.

For the Gumbel-Hougaard copula, Kendall’s tau has the closed form (θ-1)/θ.

Parameters:

  • *args – Parameters for the copula.

  • **kwargs – Parameters for the copula.

Returns:

Kendall’s tau value or expression.

Return type:

float or sympy.Expr

params: list = [theta]
theta = theta
class copul.HueslerReiss(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

Hüsler–Reiss extreme value copula with parameter \(\delta \ge 0\). When \(\delta=0\), it reduces to the independence copula.

cdf(u=None, v=None, **kwargs)[source]

Evaluate the CDF numerically via cdf_vectorized.

cdf_vectorized(u, v)[source]

Vectorized implementation of the Hüsler–Reiss copula CDF:

C(u,v) = (u * v)^A(t), where t = ln(v) / ln(u*v), A(t) = (1 - t)*Φ(z(1 - t)) + t*Φ(z(t)), z(x) = 1/delta + (delta/2)*ln(x/(1 - x)).

delta = delta
intervals: dict = {'delta': Interval(0, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

params: list = [delta]
property pdf

Numerical PDF via finite-difference on cdf_vectorized.

class copul.Joe(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

cdf_vectorized(u: ndarray, v: ndarray) → ndarray[source]

Vectorized implementation of the cumulative distribution function for the Joe copula.

This method uses the explicit mathematical formula for the Joe copula, which is significantly faster than the generic generator-based approach.

Parameters:

  • u (array_like) – First uniform marginal, must be in [0, 1].

  • v (array_like) – Second uniform marginal, must be in [0, 1].

Returns:

The CDF values at the specified points.

Return type:

numpy.ndarray

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

rvs(n: int = 1, random_state: int | None = None, approximate: bool = False) → ndarray[source]

Generate random samples from the Joe copula using a fast, vectorized algorithm.

This method overrides the slow, iterative solver from the parent class. It uses a numerically stable, closed-form inverse of the conditional distribution, allowing for thousands of samples to be generated almost instantly.

Parameters:

  • n (int) – Number of samples to generate.

  • random_state (int, optional) – Seed for the random number generator for reproducibility.

  • approximate (bool) – This parameter is ignored as the exact vectorized method is always fast.

Returns:

Array of shape (n, 2) containing the generated samples.

Return type:

numpy.ndarray

special_cases = {1: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(1, oo)
class copul.JoeEV(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

alpha_1 = alpha_1
alpha_2 = alpha_2
cdf(u=None, v=None, **kwargs)[source]

Evaluate the CDF numerically via cdf_vectorized.

The symbolic CDF of the JoeEV copula contains deeply nested logarithms and powers that are slow to evaluate through SymPy’s evalf. This override routes all concrete (u, v) evaluations to the fast numpy path.

delta = delta
intervals: dict = {'alpha_1': Interval(0, 1), 'alpha_2': Interval(0, 1), 'delta': Interval.open(0, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

params: list = [alpha_1, alpha_2, delta]
property pdf

Numerical PDF via finite-difference on cdf_vectorized.

class copul.LTDVerifier[source]

Bases: object

Verifier for the left-tail-decreasing (LTD) property of copulas.

A copula \(C\) is LTD iff, for every \(v\in(0,1)\), the mapping

\[u \;\mapsto\; \frac{C(u,v)}{u}, \quad 0<u<1,\]

is non-increasing in \(u\).

is_ltd(copul, range_min=None, range_max=None)[source]

Check whether a copula (or all members of a one-parameter family) satisfy LTD.

Parameters:

  • copul (BivCopula class or instance) – The copula family (class) or a concrete copula (instance).

  • range_min (float, optional) – Parameter range to scan if copul is a family.

  • range_max (float, optional) – Parameter range to scan if copul is a family.

Returns:

True if LTD holds for every parameter tested, False if at least one parameter violates LTD.

Return type:

bool

class copul.Laplace(*args, **kwargs)[source]

Bases: EllipticalCopula

Laplace copula implementation.

The Laplace copula is an elliptical copula based on the multivariate Laplace distribution. It is characterized by a correlation parameter rho in [-1, 1].

Special cases: - rho = -1: Lower Fréchet bound (countermonotonicity) - rho = 1: Upper Fréchet bound (comonotonicity)

property cdf

Compute the cumulative distribution function of the Laplace copula.

Returns:

Wrapped CDF function

Return type:

SymPyFuncWrapper

Note

This method is not yet implemented.

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

True if the copula is symmetric, False otherwise.

Return type:

bool

property pdf

Compute the probability density function of the Laplace copula.

Returns:

Wrapped PDF function

Return type:

SymPyFuncWrapper

Note

This method is not yet implemented.

rho = rho
rvs(n=1)[source]

Generate random samples from the Laplace copula.

Parameters:

n (int) – Number of samples to generate

Returns:

Array of shape (n, 2) containing the samples

Return type:

numpy.ndarray

class copul.LowerFrechet(*args, **kwargs)[source]

Bases: Frechet

property alpha
property beta
class copul.Mardia(*args, **kwargs)[source]

Bases: BivCopula

Mardia Copula.

A convex mixture of the Fréchet bounds and the independence copula.

C(u,v) = theta^2 * (1 + theta) / 2 * min(u,v) +

(1 - theta^2) * u*v + theta^2 * (1 - theta) / 2 * max(u+v-1, 0)

Parameters:

thetafloat, -1 ≤ theta ≤ 1

Dependence parameter

property cdf

Cumulative distribution function of the copula.

C(u,v) = theta^2 * (1 + theta) / 2 * min(u,v) +

(1 - theta^2) * u*v + theta^2 * (1 - theta) / 2 * max(u+v-1, 0)

chatterjees_xi(*args, **kwargs)[source]

Calculate Chatterjee’s xi for the Mardia copula.

For Mardia, xi = theta^4 * (3*theta^2 + 1) / 4

intervals: dict = {'theta': Interval(-1, 1)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the Mardia copula.

For Mardia, tau = theta^3 * (theta^2 + 2) / 3

property lambda_L

Lower tail dependence coefficient.

For Mardia, lambda_L = theta^2 * (1 + theta) / 2

When theta = 1, this equals 1 When theta = -1, this equals 0

property lambda_U

Upper tail dependence coefficient.

For Mardia, lambda_U = theta^2 * (1 + theta) / 2

When theta = 1, this equals 1 When theta = -1, this equals 0

params: list = [theta]
property pdf

Probability density function of the copula.

The Mardia copula does not have a PDF due to its singular components.

spearmans_rho(*args, **kwargs)[source]

Calculate Spearman’s rho for the Mardia copula.

For Mardia, rho = theta^3

theta = theta
class copul.MarshallOlkin(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

property alpha_1
property alpha_2
blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Marshall-Olkin copula.

\[\beta = 4\,C(\tfrac12,\tfrac12) - 1 = 4 \cdot 2^{-\max(\alpha_1,\alpha_2)} \cdot (\tfrac14)^{1-?} - 1\]

Uses the general \(4C(1/2,1/2)-1\) formula directly.

chatterjees_xi(*args, **kwargs)[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(u=None, v=None)[source]

First conditional distribution \(\partial C/\partial u\).

Uses exact boundary values where possible, otherwise numerical finite differences on cdf_vectorized().

Parameters:

  • u (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

  • v (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

Returns:

Value of \(\partial C(u,v)/\partial u\).

Return type:

float

cond_distr_2(u=None, v=None)[source]

Second conditional distribution \(\partial C/\partial v\).

Uses exact boundary values where possible, otherwise numerical finite differences on cdf_vectorized().

Parameters:

  • u (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

  • v (float or tuple) – Evaluation point in \([0,1]^2\). If u is a tuple/list (u_val, v_val) and v is None, the values are unpacked automatically.

Returns:

Value of \(\partial C(u,v)/\partial v\).

Return type:

float

intervals: dict = {'alpha_1': Interval(0, 1), 'alpha_2': Interval(0, 1)}
property is_absolutely_continuous

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Compute Spearman’s \(\rho\).

Returns:

Symbolic expression of Spearman’s \(\rho\).

Return type:

sympy.Expr

params: list = [alpha_1, alpha_2]
property pdf

Probability density function of the copula.

Returns:

Wrapper around the symbolic or numerical PDF.

Return type:

SymPyFuncWrapper

schweizer_wolff_sigma(*args, **kwargs)[source]

Schweizer–Wolff \(\sigma\) for the Marshall-Olkin copula.

The MO copula is PQD for all \(\alpha_1, \alpha_2 \ge 0\), so

\[\sigma = \rho_S = \frac{3\,\alpha_1\,\alpha_2} {2\alpha_1 + 2\alpha_2 - \alpha_1\alpha_2}\]
spearmans_footrule(*args, **kwargs)[source]
spearmans_rho(*args, **kwargs)[source]

Spearman’s \(\rho\) for the extreme value copula.

Parameters:

  • *args – Copula parameters.

  • **kwargs – Copula parameters.

Returns:

Symbolic expression of Spearman’s \(\rho\).

Return type:

sympy.Expr

copul.Nelsen1

alias of BivClayton

class copul.Nelsen10(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, 1)
class copul.Nelsen11(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, 0.500000000000000)
class copul.Nelsen12(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {1: <class 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'>}
theta = theta
theta_interval = Interval(1, oo)
class copul.Nelsen13(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, oo)
class copul.Nelsen14(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {1: <class 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'>}
theta = theta
theta_interval = Interval(1, oo)
copul.Nelsen15

alias of GenestGhoudi

class copul.Nelsen16(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

first_deriv_of_ci_char()[source]

Calculate the first derivative of the CI characteristic.

Returns:

The first derivative of the CI characteristic

Return type:

sympy expression

property generator

The generator function with proper edge case handling. Subclasses should implement _raw_generator instead of _generator.

Returns:

The generator function φ

Return type:

SymPyFuncWrapper

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

second_deriv_of_ci_char()[source]

Calculate the second derivative of the CI characteristic.

Returns:

The second derivative of the CI characteristic

Return type:

sympy expression

special_cases = {0: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>}
theta = theta
theta_interval = Interval(0, oo)
class copul.Nelsen17(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

density_of_log_density()[source]
deriv_of_log_density()[source]
property first_deriv_of_ci_char

Calculate the first derivative of the CI characteristic.

Returns:

The first derivative of the CI characteristic

Return type:

sympy expression

property first_deriv_of_inv_gen

First derivative of the inverse generator function.

Returns:

The derivative φ⁻¹’(y)

Return type:

sympy expression

first_deriv_of_tp2_char()[source]

Calculate the first derivative of the TP2 characteristic.

Returns:

The first derivative of the TP2 characteristic

Return type:

sympy expression

invalid_params = {0}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

property pdf

Probability density function of the bivariate copula.

Returns:

The PDF function c(u,v)

Return type:

sympy expression

property second_deriv_of_inv_gen

Second derivative of the inverse generator function.

Returns:

The second derivative φ⁻¹’’(y)

Return type:

sympy expression

second_deriv_of_tp2_char()[source]

Calculate the second derivative of the TP2 characteristic.

Returns:

The second derivative of the TP2 characteristic

Return type:

sympy expression

special_cases = {-1: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta_interval = Interval(-oo, oo)
class copul.Nelsen18(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

theta = theta
theta_interval = Interval(2, oo)
class copul.Nelsen19(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

special_cases = {0: <class 'copul.family.other.pi_over_sigma_minus_pi.PiOverSigmaMinusPi'>}
theta = theta
theta_interval = Interval(0, oo)
class copul.Nelsen2(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

theta = theta
theta_interval = Interval(1, oo)
class copul.Nelsen20(*args, **kwargs)[source]

Bases: HeavyComputeArch

ac

alias of BivArchimedeanCopula

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, oo)
class copul.Nelsen21(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {1: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>}
theta = theta
theta_interval = Interval(1, oo)
class copul.Nelsen22(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

compute_gen_max()[source]

Compute the maximum value of the generator function.

Returns:

The maximum value of the generator

Return type:

float or sympy expression

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, 1)
copul.Nelsen3

alias of AliMikhailHaq

copul.Nelsen4

alias of GumbelHougaard

copul.Nelsen5

alias of Frank

copul.Nelsen6

alias of Joe

class copul.Nelsen7(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

chatterjees_xi(*args, **kwargs)[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

cond_distr_2(u=None, v=None)[source]

\(F_{U_{-2}\mid U_2}(u_{-2}\mid u_2)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the bivariate Archimedean copula.

Kendall’s tau is a measure of concordance. For Archimedean copulas, it can be calculated using the generator function.

Returns:

Kendall’s tau value

Return type:

float or sympy expression

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {0: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>, 1: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
theta = theta
theta_interval = Interval(0, 1)
class copul.Nelsen8(*args, **kwargs)[source]

Bases: BivArchimedeanCopula

ac

alias of BivArchimedeanCopula

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise

Return type:

bool

lambda_L()[source]

Calculate the lower tail dependence coefficient.

Returns:

The lower tail dependence coefficient

Return type:

float or sympy expression

lambda_U()[source]

Calculate the upper tail dependence coefficient.

Returns:

The upper tail dependence coefficient

Return type:

float or sympy expression

special_cases = {1: <class 'copul.family.frechet.lower_frechet.LowerFrechet'>}
theta = theta
theta_interval = Interval(1, oo)
copul.Nelsen9

alias of GumbelBarnett

class copul.PLODVerifier[source]

Bases: object

Verifier for the Positive–Lower–Orthant–Dependence (PLOD) property.

A copula \(C\) is PLOD iff \(C(u,v) \ge u\,v\) for all \(0<u,v<1\).

is_plod(copul, range_min=None, range_max=None)[source]

Check whether all members of a one-parameter copula family (or a single fixed copula) satisfy the PLOD property.

Parameters:

  • copul (BivCopula (class or instance)) – The copula family or a concrete copula to test.

  • range_min (float, optional) – Parameter range to scan if copul is a family.

  • range_max (float, optional) – Parameter range to scan if copul is a family.

Returns:

True – PLOD holds for every parameter tested. False – at least one parameter violates PLOD.

Return type:

bool

class copul.Plackett(*args, **kwargs)[source]

Bases: BivCopula

blests_nu()[source]

Compute Blest’s rank correlation ν.

Uses the copula form

ν(C) = 24 ∫_0^1 ∫_0^1 (1 - u) C(u, v) du dv - 2

which is linear in C and generally symbolic-friendly.

Returns:

The symbolic expression for Blest’s ν.

Return type:

sympy.Expr

blomqvist(*args, **kwargs)[source]

Nelsen Exercise 5.18

property cdf

Evaluate (or partially evaluate) the CDF.

Supports:

  • C(u1,…,ud) via separate scalars or a 1D array

  • partial substitution via kwargs (u1=…, u2=…, u=…, v=…)

  • returns a callable wrapper if variables remain, otherwise a scalar

cond_distr_1(u=None, v=None)[source]

\(F_{U_{-1}\mid U_1}(u_{-1}\mid u_1)\).

Parameters:

  • *args – See cond_distr().

  • **kwargs – See cond_distr().

get_density_of_density()[source]
get_numerator_double_density()[source]
intervals: dict = {'theta': Interval(0, oo)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

params: list = [theta]
property pdf

Evaluate (or partially evaluate) the PDF: ∂^d C / ∂u1 … ∂ud

spearmans_rho(*args, **kwargs)[source]

Calculate Spearman’s rho for the Plackett copula.

For the Plackett copula, the formula is: rho = (theta + 1) / (theta - 1) - 4 * theta * log(theta) / (theta - 1)^2

Special case: when theta = 1, rho = 0 (independence)

theta = theta
class copul.Raftery(*args, **kwargs)[source]

Bases: BivCopula

Raftery Copula.

This copula has a parameter delta controlling the dependence structure. Special cases: - delta = 0: Independence copula - delta = 1: Upper Fréchet bound (perfect positive dependence)

Parameters:

deltafloat, 0 ≤ delta ≤ 1

Dependence parameter

property cdf

Cumulative distribution function of the copula.

The formula has special cases for delta=0 and delta=1 to avoid division by zero.

cdf_vectorized(u, v)[source]

Vectorized implementation of the cumulative distribution function for Raftery copula.

This method evaluates the CDF at multiple points simultaneously, which is more efficient than calling the scalar CDF function repeatedly.

Parameters:

  • u (array_like) – First uniform marginal, should be in [0, 1].

  • v (array_like) – Second uniform marginal, should be in [0, 1].

Returns:

The CDF values at the specified points.

Return type:

numpy.ndarray

Notes

The Raftery copula CDF is: C(u,v) = min(u, v) + (1 - delta) / (1 + delta) * (u * v)^(1/(1-delta)) * (1 - max(u, v)^(-(1+delta)/(1-delta)))

Special cases: - When delta = 0, it’s the Independence copula (u * v) - When delta = 1, it’s the Upper Fréchet bound (min(u, v))

delta = delta
intervals: dict = {'delta': Interval(0, 1)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

kendalls_tau(*args, **kwargs)[source]

Calculate Kendall’s tau for the Raftery copula.

For Raftery, tau = 2*delta / (3 - delta)

property lambda_L

Lower tail dependence coefficient.

For Raftery, lambda_L = 2*delta / (1 + delta)

property lambda_U

Upper tail dependence coefficient.

For Raftery, lambda_U = 0

params: list = [delta]
property pdf

Probability density function of the copula.

Calculated using the _b function.

spearmans_rho(*args, **kwargs)[source]

Calculate Spearman’s rho for the Raftery copula.

For Raftery, rho = delta * (4 - 3*delta) / (2 - delta)^2

class copul.ShuffleOfMin(pi: Sequence[int])[source]

Bases: BivCoreCopula, CopulaPlottingMixin, CopulaApproximatorMixin

Straight shuffle-of-Min copula \(C_\pi\) of order \(n\).

Parameters:

pi (Sequence[int]) – A permutation of \(\{1,\dots,n\}\) in 1-based notation. pi[i] represents \(\pi(i+1)\).

Notes

The support consists of \(n\) diagonal line segments [ S_i ;=; bigl{,((i-1+t)/n,; (pi(i)-1+t)/n) : 0 le t le 1 ,bigr}. ] The copula is singular (the density is 0 almost everywhere).

A convenient closed form for the CDF is [ C(u,v) ;=; frac{1}{n}sum_{i=1}^n min!Bigl( 1,; max!bigl(0,; min(nu-i+1,; nv-pi(i)+1)bigr) Bigr). ]

For fixed \(u \in ((i-1)/n,\, i/n)\), the conditional CDF \(C_1(v\mid u)\) is a step function: it jumps from 0 to 1 at [ v_0 ;=; frac{pi(i)-1 + t}{n}, qquad t ;=; nu - (i-1). ] At the boundaries, \(C_1(v\mid 0)=v\) and \(C_1(v\mid 1)=v\). Similarly for \(C_2(u\mid v)\) with \(C_2(u\mid 0)=u\) and \(C_2(u\mid 1)=u\).

cdf(*args) → float | ndarray[source]

Copula \(C_\pi(u,v)\) (vectorized).

Multiple call signatures are supported: - cdf(u, v) where u and v are scalars or arrays, - cdf([u, v]) for a single point as a 1-D array, - cdf([[u1, v1], [u2, v2], ...]) for multiple points as a 2-D array.

Returns:

The CDF values at the specified points.

Return type:

float or numpy.ndarray

chatterjee_xi() → float[source]

Chatterjee’s \(\xi\).

For any straight shuffle-of-Min (functional dependence along segments), \(\xi=1\).

Returns:

Always 1.0 (nan only if \(n=0\)).

Return type:

float

cond_distr(i: int, *args) → float | ndarray[source]

Conditional distribution (vectorized).

Computes - \(C_1(v\mid u)\) if i=1 (condition on \(U\)) - \(C_2(u\mid v)\) if i=2 (condition on \(V\))

For interior conditioning values the conditional CDF is a step function jumping from \(0\) to \(1\) at the point where the corresponding support segment is reached. At the boundaries \(u\in\{0,1\}\) or \(v\in\{0,1\}\) the conditionals are uniform (\(v\) or \(u\), respectively).

Parameters:

  • i (int) – 1 for \(C_1(v\mid u)\), 2 for \(C_2(u\mid v)\).

  • *args – Same calling conventions as cdf().

Returns:

Conditional CDF value(s).

Return type:

float or numpy.ndarray

Raises:

ValueError – If i is outside {1, 2} or coordinates lie outside \([0,1]\).

cond_distr_1(*args) → float | ndarray[source]

Conditional distribution of \(V\) given \(U=u\): \(C_1(v\mid u)=\mathbb{P}(V\le v\mid U=u)\). Same calling conventions as cdf().

cond_distr_2(*args) → float | ndarray[source]

Conditional distribution of \(U\) given \(V=v\): \(C_2(u\mid v)=\mathbb{P}(U\le u\mid V=v)\). Same calling conventions as cdf().

kendall_tau() → float[source]

Population Kendall’s \(\tau\) via inversion count.

Let \(N_{\mathrm{inv}}\) be the number of inversions of the 0-based permutation pi0. Then \(\tau = 1 - \dfrac{4\,N_{\mathrm{inv}}}{n^2}\).

Returns:

Kendall’s \(\tau\) (nan if \(n\le 1\)).

Return type:

float

pdf(*args) → float | ndarray[source]

The straight shuffle-of-Min copula is singular ⇒ the density is 0 a.e.

rvs(size: int, **kwargs) → ndarray[source]

Generate \(\texttt{size}\) i.i.d. samples from \(C_{\pi}\).

Sampling picks a segment index uniformly from \(\{0,\dots,n-1\}\) and a parameter \(t\sim U(0,1)\), then sets \(u=(i+t)/n\), \(v=(\pi(i+1)-1+t)/n\).

Parameters:

size (int) – Number of samples.

Returns:

Array of shape (size, 2) with samples in \([0,1]^2\).

Return type:

numpy.ndarray

spearman_rho() → float[source]

Population Spearman’s \(\rho\) via squared rank differences.

With ranks \(1,\dots,n\) and \(\pi(1),\dots,\pi(n)\), \(\rho = 1 - \dfrac{6\sum_{i=1}^n (i-\pi(i))^2}{n^3}\).

Returns:

Spearman’s \(\rho\) (nan if \(n\le 1\)).

Return type:

float

tail_lower() → float[source]

Lower tail dependence coefficient \(\lambda_L\).

It is positive (equal to 1) iff the first segment lies on the main diagonal, i.e. \(\pi(1)=1\); otherwise it is 0.

Returns:

\(\lambda_L \in \{0,1\}\) (nan if \(n=0\)).

Return type:

float

tail_upper() → float[source]

Upper tail dependence coefficient \(\lambda_U\).

It is positive (equal to 1) iff the last segment lies on the main diagonal, i.e. \(\pi(n)=n\); otherwise it is 0.

Returns:

\(\lambda_U \in \{0,1\}\) (nan if \(n=0\)).

Return type:

float

class copul.StudentT(*args, **kwargs)[source]

Bases: EllipticalCopula

Student’s t Copula implementation.

The Student’s t copula is an elliptical copula derived from the multivariate t-distribution. It is characterized by a correlation parameter rho in [-1, 1] and a degrees of freedom parameter nu > 0.

Special cases: - rho = -1: Lower Fréchet bound (countermonotonicity) - rho = 1: Upper Fréchet bound (comonotonicity) - nu → ∞: Approaches the Gaussian copula

blomqvists_beta(*args, **kwargs)[source]

Blomqvist’s \(\beta\) for the Student-t copula.

\[\beta = \frac{2}{\pi}\,\arcsin(\rho)\]

(same formula as the Gaussian copula).

Return type:

float

property cdf

Compute the cumulative distribution function of the Student’s t copula.

Returns:

Function that computes the CDF at given points

Return type:

callable

cond_distr_1(u=None, v=None)[source]

Compute the first conditional distribution C(v|u).

Parameters:

  • u (float, optional) – Conditioning value

  • v (float, optional) – Value at which to evaluate

Returns:

Wrapped conditional distribution function or value

Return type:

CD1Wrapper

cond_distr_2(u=None, v=None)[source]

Compute the second conditional distribution C(u|v).

Parameters:

  • u (float, optional) – Value at which to evaluate

  • v (float, optional) – Conditioning value

Returns:

Wrapped conditional distribution function or value

Return type:

CD2Wrapper

gamma_function = gamma(nu/2)
intervals: dict = {'nu': Interval.open(0, oo), 'rho': Interval(-1, 1)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

True if the copula is absolutely continuous, False otherwise.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

True if the copula is symmetric, False otherwise.

Return type:

bool

kendalls_tau(*args, **kwargs)[source]

Kendall’s \(\tau\) for the Student-t copula.

\[\tau = \frac{2}{\pi}\,\arcsin(\rho)\]

(same formula as the Gaussian copula — independent of \(\nu\)).

Return type:

float

lambda_L()[source]

Lower tail dependence coefficient for the Student-t copula.

\[\lambda_L = 2\,t_{\nu+1}\!\left( -\sqrt{\frac{(\nu+1)(1-\rho)}{1+\rho}} \right)\]

where \(t_{\nu+1}\) is the CDF of the univariate Student-t distribution with \(\nu + 1\) degrees of freedom.

Returns:

Lower tail dependence coefficient in \([0, 1]\).

Return type:

float

References

Demarta & McNeil (2005), The t Copula and Related Copulas, International Statistical Review 73(1), 111–129.

lambda_U()[source]

Upper tail dependence coefficient for the Student-t copula.

The Student-t copula is radially symmetric, so \(\lambda_U = \lambda_L\).

Returns:

Upper tail dependence coefficient in \([0, 1]\).

Return type:

float

modified_bessel_function = K(nu)
nu = nu
params: list = [rho, nu]
property pdf

Compute the probability density function of the Student’s t copula.

Returns:

Function that computes the PDF at given points

Return type:

callable

rho = rho
rvs(n=1, **kwargs)[source]

Generate random samples from the Student’s t copula.

Parameters:

n (int) – Number of samples to generate

Returns:

Array of shape (n, 2) containing the samples

Return type:

numpy.ndarray

spearmans_rho(*args, **kwargs)[source]

Spearman’s \(\rho_S\) for the Student-t copula.

\[\rho_S = \frac{6}{\pi}\,\arcsin\!\left(\frac{\rho}{2}\right)\]

(same formula as the Gaussian copula — independent of \(\nu\)).

Return type:

float

tail_dependence_function(t, lower=True)[source]

Evaluate the tail dependence function at \(t \in [0,1]\).

For the Student-t copula:

\[b_L(t) = (1-t)\,t_{\nu+1}\!\left( -\sqrt{\frac{(\nu+1)(1 - \rho_{t})}{1 + \rho_{t}}} \right) + t\,t_{\nu+1}\!\left( -\sqrt{\frac{(\nu+1)(1 - \tilde\rho_{t})}{1 + \tilde\rho_{t}}} \right)\]

where the mixed-quantile correlations involve the parameter. The simple diagonal case is \(b_L(1/2) = \lambda_L / 2\).

Parameters:

  • t (float or array_like) – Point(s) in \([0, 1]\).

  • lower (bool) – If True, evaluate the lower TDF. If False, upper TDF.

Return type:

float or numpy.ndarray

class copul.Tawn(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

alpha_1 = alpha_1
alpha_2 = alpha_2
property cdf

Cumulative distribution function of the copula.

Returns:

Wrapper around the symbolic CDF expression.

Return type:

CDFWrapper

intervals: dict = {'alpha_1': Interval(0, 1), 'alpha_2': Interval(0, 1), 'theta': Interval(1, oo)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

params: list = [alpha_1, alpha_2, theta]
theta = theta
class copul.UpperFrechet(*args, **kwargs)[source]

Bases: Frechet

property alpha
property beta
property pickands
t = t
class copul.XiNuBoundaryCopula(*args, **kwargs)[source]

Bases: BivCopula

Clamped–parabola copula parameterized by \(b=1/\mu>0\):

\[h_v(t) \;=\; \mathrm{clamp}\!\left(b\big((1-t)^2 - q(v)\big),\,0,\,1\right),\]

where \(q(v)\) is uniquely determined by the marginal constraint \(\int_0^1 h_v(t)\,dt=v\).

b = b
blests_nu()[source]

Signed Blest’s ν(b). Under the σ₂ reflection (b<0) the dependence reverses, so ν must satisfy ν(-b) = -ν(b). We therefore return sign(b) * ν(|b|), where ν(|b|) is the closed form in terms of μ = 1/|b|.

property cdf

Evaluate (or partially evaluate) the CDF.

Supports:

  • C(u1,…,ud) via separate scalars or a 1D array

  • partial substitution via kwargs (u1=…, u2=…, u=…, v=…)

  • returns a callable wrapper if variables remain, otherwise a scalar

cdf_vectorized(u, v)[source]

If b >= 0: C(u,v) = C_base(u,v; |b|). If b < 0 : C(u,v) = u - C_base(u, 1-v; |b|) (σ2 reflection).

chatterjees_xi()[source]

Compute Chatterjee’s xi correlation measure.

This method sets the parameters, computes intermediate integrals, and returns the simplified expression for xi.

Returns:

A wrapper around the symbolic expression for Chatterjee’s xi.

Return type:

SymPyFuncWrapper

cond_distr_1()[source]

h(u,v) = ∂_u C(u,v). If b >= 0: h = clamp(|b|((1-u)^2 - q(v)),0,1). If b < 0 : h = 1 - clamp(|b|((1-u)^2 - q(1-v)),0,1). (since C^σ2) NOTE: q(·) will be evaluated with |b| in the lambdify bridge.

classmethod from_xi(x_target)[source]

Solve for b from target ξ. Since ξ(μ) is strictly decreasing in μ, we solve for μ and return b=1/μ.

intervals: dict = {'b': Interval.open(0, oo)}
property is_absolutely_continuous: bool

XiNuBoundaryCopula has a density everywhere on (0,1)^2.

params: list = [b]
pdf_vectorized(u, v)[source]

If b >= 0: c(u,v) = c_base(u,v; |b|). If b < 0 : c(u,v) = c_base(u, 1-v; |b|) (chain rule for σ2).

plot_cdf(*, plot_type='3d', log_z=False, **kwargs)[source]

Plot the CDF using the numerical cdf_vectorized() implementation.

plot_cond_distr_1(*, plot_type='3d', log_z=False, **kwargs)[source]

Plot h(u,v) = ∂_u C(u,v). Uses the symbolic expression and injects q(v) so the base lambdify has a valid mapping.

plot_cond_distr_2(*, plot_type='3d', log_z=False, **kwargs)[source]

Not available: q(v) is implicit and prevents a closed form.

plot_pdf(*, plot_type='3d', log_z=False, **kwargs)[source]

Plot the PDF using the numerical pdf_vectorized() implementation.

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>, oo: <class 'copul.family.frechet.upper_frechet.UpperFrechet'>}
u = u
v = v
class copul.XiPsiApproxLowerBoundaryCopula(*args, **kwargs)[source]

Bases: BivCopula

Two-parameter “diagonal strip” copula with a rectangular hole.

The copula is defined by a transformation variable T and a hole geometry H. C(u,v) = (u*t - Area(Intersection)) / (1 - beta) where t = F_T^{-1}(v).

Parameters:

  • alpha (float) – Controls the horizontal start of the diagonal slope. alpha in [0, 0.5).

  • beta (float) – Controls the vertical thickness of the hole. beta in (0, 1).

alpha = alpha
beta = beta
cdf(u=None, v=None)[source]

Cumulative distribution function C(u,v).

cdf_vectorized(u, v)[source]

Exact numeric Copula CDF.

cond_distr_1(u=None, v=None)[source]

P(V <= v | U = u) = dC/du.

cond_distr_2(u=None, v=None)[source]

P(U <= u | V = v) = dC/dv.

intervals: dict = {'alpha': Interval.Lopen(0, 1/2), 'beta': Interval.open(0, 1)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

params: list = [alpha, beta]
pdf(u=None, v=None)[source]

Probability Density Function c(u,v).

pdf_vectorized(u, v)[source]

Exact numeric Copula PDF.

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
u = u
v = v
class copul.XiRhoBoundaryCopula(*args, **kwargs)[source]

Bases: BivCopula

Optimal–\(\rho\) diagonal–band copula with dependence parameter \(b\in\mathbb{R}\setminus\{0\}\).

For \(b>0\), the copula is the upper/right boundary copula. For \(b<0\), the lower/left boundary copula is obtained by the reflection

\[C_b(u,v) = v - C_{|b|}(1-u,v).\]

Formulas

  1. Maximal Spearman’s \(\rho\) for \(b>0\):

    \[\begin{split}M(b) = \begin{cases} b - \dfrac{3b^2}{10}, & 0<b\le 1,\\[1ex] 1 - \dfrac{1}{2b^2} + \dfrac{1}{5b^3}, & b\ge 1. \end{cases}\end{split}\]

  2. Shift \(s_v(b)\) for \(b>0\):

    \[\begin{split}s_v = \begin{cases} \sqrt{2v/b}, & v \le \frac{1}{2b}\wedge\frac{b}{2},\\[1ex] v + \frac{1}{2b}, & \frac{1}{2b} < v \le 1-\frac{1}{2b},\\[1ex] \frac{v}{b}+\frac12, & \frac{b}{2} < v \le 1-\frac{b}{2},\\[1ex] 1 + \frac1b - \sqrt{2(1-v)/b}, & v > 1 - \left(\frac{1}{2b}\wedge\frac{b}{2}\right). \end{cases}\end{split}\]

  3. Copula CDF for \(b>0\):

    \[\begin{split}a_v = s_v - 1/b, \qquad C_b(u,v) = \begin{cases} u - \dfrac{b}{2}(u-a_v)^2 + \dfrac{b}{2}(a_v\wedge 0)^2, & a_v < u \le s_v,\\[1ex] \min\{u,v\}, & \text{else}. \end{cases}\end{split}\]
b = b
blests_nu(*args, **kwargs)[source]

Compute Blest’s rank correlation ν.

Uses the copula form

ν(C) = 24 ∫_0^1 ∫_0^1 (1 - u) C(u, v) du dv - 2

which is linear in C and generally symbolic-friendly.

Returns:

The symbolic expression for Blest’s ν.

Return type:

sympy.Expr

cdf_vectorized(u, v)[source]

Vectorized implementation of the cumulative distribution function. This method allows for efficient computation of the CDF for arrays of points, which is detected by the Checkerboarder for fast approximation.

chatterjees_xi()[source]

Closed-form \(\xi(C_b)\) for the original parameter \(b\).

classmethod from_xi(x)[source]

Instantiate from xi. Optimized to use float arithmetic if x is float.

intervals: dict = {'b': Interval(-oo, oo)}
property is_absolutely_continuous: bool

Whether the copula is absolutely continuous.

Returns:

True if the copula has a density a.e. on \([0,1]^d\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

property is_symmetric: bool

Whether the copula is exchangeable (symmetric under coordinate permutations).

Returns:

True if \(C(u_{\pi(1)},\ldots,u_{\pi(d)}) = C(u_1,\ldots,u_d)\) for all permutations \(\pi\), otherwise False.

Return type:

bool

Notes

Subclasses must override this property.

kendalls_tau()[source]

Closed-form Kendall’s \(\tau(C_b)\) for the original parameter \(b\).

params: list = [b]
pdf_vectorized(u, v)[source]

Fully vectorized PDF implementation. Computes density c(u,v) = |b| * s’_v(v) inside the band, 0 outside. Replaces symbolic logic for high performance.

spearmans_rho()[source]

Closed-form Spearman’s \(\rho(C_b)\) for the original parameter \(b\).

special_cases = {0: <class 'copul.family.frechet.biv_independence_copula.BivIndependenceCopula'>}
u = u
v = v
copul.bounds_from_xi(x: float, measure: Literal['rho', 'tau', 'psi', 'nu'], return_lower_bound: bool = False, cls: Literal['all', 'SI'] = 'all') → Tuple[float | None, float][source]

Unified entry point. Returns (min_value, max_value) for the chosen measure given xi=x.

copul.from_cdf(cdf)[source]
copul.from_cond_distr_1(cond)[source]

Build from F_{V|U=u}(v) = ∂C/∂u (u, v).

copul.from_cond_distr_2(cond)[source]

Build from F_{U|V=v}(u) = ∂C/∂v (u, v).

copul.from_data(data, checkerboard_size=None, checkerboard_type='CheckPi')[source]
copul.from_generator(generator, params=None)[source]

Create an Archimedean copula from a generator function.

Parameters:

  • generator (str or sympy expression) – The generator function φ

  • params (list or None) – List of parameters if needed

Returns:

A new copula instance using the provided generator

Return type:

ArchimedeanCopula

copul.from_matrix(matrix, checkerboard_type='CheckPi')[source]
copul.from_pdf(pdf)[source]
copul.from_pickands(pickands, params=None)[source]

Construct a bivariate extreme value copula from a Pickands function.

Parameters:

  • pickands (str or sympy.Expr) – Pickands dependence function. May contain t or another symbol.

  • params (list or str, optional) – Parameter names. If None, symbols are detected automatically.

Returns:

Instance with the specified Pickands function.

Return type:

BivExtremeValueCopula

copul.markov_product(C: BivCopula, D: BivCopula, *, n_grid: int = 400, checkerboard: bool = False) → BivCopula[source]
class copul.tEV(*args, **kwargs)[source]

Bases: BivExtremeValueCopula

Student-t Extreme Value Copula.

Parameters:

  • nu (float) – Degrees of freedom, nu > 0

  • rho (float) – Correlation parameter, -1 < rho < 1

cdf(u=None, v=None, **kwargs)[source]

Evaluate the tEV CDF numerically via cdf_vectorized.

cdf_vectorized(u, v)[source]

Optimized vectorized implementation of the CDF.

intervals: dict = {'nu': Interval.open(0, oo), 'rho': Interval.open(-1, 1)}
property is_absolutely_continuous: bool

Check if the copula is absolutely continuous.

Returns:

Must be implemented by subclasses.

Return type:

bool

property is_symmetric: bool

Check if the copula is symmetric.

Returns:

Must be implemented by subclasses.

Return type:

bool

nu = nu
params: list = [nu, rho]
property pdf

Numerical PDF via finite-difference on cdf_vectorized.

property pickands

Return the Pickands dependence function with parameter values substituted.

Returns:

A wrapper that supports evaluation at \(t\) values and symbolic use.

Return type:

PickandsWrapper

rho = rho
copul.xi_ncalculate(xvec: ndarray, yvec: ndarray) → float[source]

Calculate the Xi_n dependence measure between two vectors of data.

Xi_n is a measure of association that can detect both linear and nonlinear relationships, and is based on the ranks of the data. The measure ranges approximately from 0 to 1, where 0 indicates no association and 1 indicates a perfect deterministic relationship.

Parameters:

  • xvec (np.ndarray) – First vector of data.

  • yvec (np.ndarray) – Second vector of data.

Returns:

The Xi_n dependence measure.

Return type:

float

Notes

  • The measure is not symmetric: xi_n(x, y) may not equal xi_n(y, x).

  • For perfect correlations (positive or negative), the function returns 0.5.

  • For constant data (either x or y), the function returns 0.5.

  • For inputs containing NaN, the function returns 0.5.

  • Empty or single-element vectors return NaN.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 3, 4, 5])
>>> y = np.array([1, 2, 3, 4, 5])  # Perfect positive correlation
>>> xi_ncalculate(x, y)
0.5
>>> y = np.array([5, 4, 3, 2, 1])  # Perfect negative correlation
>>> xi_ncalculate(x, y)
0.5
>>> y = np.array([1, 4, 2, 5, 3])  # Some random association
>>> xi_ncalculate(x, y)  # Will be between 0 and 1