copul.checkerboard package

Submodules

copul.checkerboard.bernstein module

copul.checkerboard.bernstein.Bernstein

alias of BernsteinCopula

class copul.checkerboard.bernstein.BernsteinCopula(theta, *args, **kwargs)

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)

cond_distr(i, *args)

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)

cond_distr_2(*args)

property is_absolutely_continuous: bool

pdf(*args)

copul.checkerboard.biv_bernstein module

copul.checkerboard.biv_bernstein.BivBernstein

alias of BivBernsteinCopula

class copul.checkerboard.biv_bernstein.BivBernsteinCopula(theta, *args, **kwargs)

Bases: BernsteinCopula, BivCoreCopula, CopulaSamplingMixin

chatterjees_xi(condition_on_y: bool = False) → float

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

Calculate Kendall’s tau using the matrix formula:

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

lambda_L()

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

lambda_U()

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

spearmans_rho() → float

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.

copul.checkerboard.biv_block_diag_mixed module

class copul.checkerboard.biv_block_diag_mixed.BivBlockDiagMixed(sizes: Sequence[int], *, sign: ndarray | Sequence[Sequence[int]] | None = None, **kwargs)

Bases: BivCheckMixed

Block–diagonal mixed checkerboard copula.

Parameters:

• sizes (Sequence[int]) – Block sizes \(n_1,\dots,n_k\) along the diagonal (with \(\sum_r n_r = d\)).

• sign (array-like of shape (d,d), optional) –

  Sign matrix \(S \in \{-1,0,+1\}^{d\times d}\) choosing per cell:

  • 0 → \(\Pi\) (independence)

  • +1 → ↗ (check-min; perfect positive dependence)

  • −1 → ↘ (check-w; perfect negative dependence)

Notes

• Inside a block \(I_r \times I_r\), every cell mass is \(\Delta_{ij} = 1/(d\,n_r)\).

• All piece-wise numerics are inherited from copul.checkerboard.biv_check_mixed.BivCheckMixed.

Closed-form dependence measures:

\[\begin{split}\xi &= 1 - \tfrac{B_2}{d^2} + \tfrac{1}{d^2}\sum_r \tfrac{P_r}{n_r^2}, \\ \tau &= 1 - \tfrac{B_2}{d^2} + \tfrac{1}{d^2}\sum_r \tfrac{S_r}{n_r^2}, \\ \rho &= 3\,d^{-3}\sum_r n_r\,(2d-2a_r-n_r)^2 \;-\; 3 \;+\; d^{-3}\sum_r \tfrac{S_r}{n_r},\end{split}\]

where

• \(B_2=\sum_r n_r^2\)

• \(S_r=\sum_{i,j\in I_r} S_{ij}\)

• \(P_r=\sum_{i,j\in I_r} |S_{ij}|\)

• \(a_r\) = starting index of block \(r\) (0-based).

chatterjees_xi(*, condition_on_y: bool = False) → float

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

kendalls_tau() → float

Compute Kendall’s tau correlation measure.

This method sets the parameters, computes necessary integrals, and returns the simplified expression for Kendall’s tau.

Returns:

The symbolic expression for Kendall’s tau.

Return type:

sympy.Expr

static make_block_diag_delta(block_sizes: list[int]) → ndarray

Canonical block-diagonal checkerboard matrix \(\Delta\).

Each diagonal block \(I_r\times I_r\) of size \(n_r\times n_r\) receives cell mass \(1/(d\,n_r)\), where \(d=\sum_r n_r\).

spearmans_rho() → float

Closed-form Spearman’s \(\rho\) for the block-diagonal mixed copula: [ rho ;=; 3 d^{-3}!sum_r n_r,(2d-2a_r-n_r)^2 ;-; 3 ;+; d^{-3}!sum_r frac{S_r}{n_r}. ] Note the second term uses the factor \(d^{-3}\) (not \(d^{-1}\)).

copul.checkerboard.biv_check_min module

class copul.checkerboard.biv_check_min.BivCheckMin(matr, *args, **kwargs)

Bases: CheckMin, BivCheckPi

Bivariate Checkerboard Minimum class.

A class that implements bivariate checkerboard minimum operations.

blests_nu() → float

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

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)

ginis_gamma() → float

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

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

Returns:

The calculated tau coefficient.

Return type:

float

lambda_L()

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

lambda_U()

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

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

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()

Transpose the checkerboard matrix.

copul.checkerboard.biv_check_mixed module

class copul.checkerboard.biv_check_mixed.BivCheckMixed(matr: ndarray | List[List[float]], sign: ndarray | List[List[int]] | None = None, **kwargs)

Bases: BivCoreCopula, CopulaPlottingMixin, CopulaApproximatorMixin

Mixed checkerboard copula (per–cell choice of \(\Pi\) / ↗ / ↘).

A sign matrix \(S\) with entries \(\{0,+1,-1\}\) selects, in every checkerboard rectangle, which base copula to use:

• \(0\) → independence (\(\Pi\))

• \(+1\) → perfect positive dependence (check-min, ↗)

• \(-1\) → perfect negative dependence (check-w, ↘)

The probability matrix \(\Delta\) (argument matr) is shared across all three modes.

cdf(u: float | ndarray, v: float | ndarray)

Piecewise delegates to \(\Pi\), ↗ or ↘ according to sign.

For each evaluation point \((u,v)\), the method chooses the base checkerboard copula dictated by the cell’s sign entry and returns the corresponding CDF value.

Parameters:

• u (float or ndarray) – Coordinates in \([0,1]\). Must have identical shapes.

• v (float or ndarray) – Coordinates in \([0,1]\). Must have identical shapes.

Returns:

CDF value(s) with the same shape as the broadcasted inputs.

Return type:

float or ndarray

chatterjees_xi(*, condition_on_y: bool = False) → float

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(dim: int, u: float | ndarray | None = None, v: float | ndarray | None = None)

Compute conditional distribution F_{U_{-dim}|U_{dim}}.

Calculates the partial derivative of the Copula. If dim=1, returns dC(u,v)/du = P(V <= v | U=u). If dim=2, returns dC(u,v)/dv = P(U <= u | V=v).

cond_distr_1(u: float | None = None, v: float | None = None)

Compute the first conditional distribution F_{U_{-1}|U_1}(u_{-1}|u_1).

This method differentiates the CDF with respect to the first variable.

Parameters:

• u (optional) – The u-coordinate; if provided, passed to the wrapper.

• v (optional) – The v-coordinate; if provided, passed to the wrapper.

Returns:

A callable (wrapped via CD1Wrapper) representing the conditional distribution.

Return type:

callable

cond_distr_2(u: float | None = None, v: float | None = None)

Compute the second conditional distribution F_{U_{-2}|U_2}(u_{-2}|u_2).

This method differentiates the CDF with respect to the second variable.

Parameters:

• u (optional) – The u-coordinate; if provided, passed to the wrapper.

• v (optional) – The v-coordinate; if provided, passed to the wrapper.

Returns:

A callable (wrapped via CD2Wrapper) representing the conditional distribution.

Return type:

callable

intervals: dict = {}

property is_absolutely_continuous: bool

is_cis(i: int = 1) → bool

Check if the copula satisfies the CIS (Conditional Increasing in Sequence) property.

Parameters:

cond_distr (int, optional) – Specifies which conditional distribution to use (default is 1).

Returns:

True if the copula is CIS, False otherwise.

Return type:

bool

property is_symmetric: bool

kendalls_tau() → float

Compute Kendall’s tau correlation measure.

This method sets the parameters, computes necessary integrals, and returns the simplified expression for Kendall’s tau.

Returns:

The symbolic expression for Kendall’s tau.

Return type:

sympy.Expr

params: List = []

rvs(n: int = 1, *, random_state: int | None = None, **kwargs) → ndarray

Draw \(n\) i.i.d. samples from the mixed checkerboard copula.

Sampling proceeds by (i) selecting a cell according to \(\Delta\), then (ii) drawing a point inside that cell according to the cell’s mode (uniform for \(\Pi\), diagonal ↗ or ↘ for the two perfect-dependence cases).

Parameters:

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

• random_state (int, optional) – Seed for the RNG (reproducibility).

Returns:

Samples \((U,V)\) in \([0,1]^2\).

Return type:

ndarray of shape (n, 2)

spearmans_rho() → float

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

copul.checkerboard.biv_check_pi module

Bivariate Checkerboard Copula module.

This module provides a bivariate checkerboard copula implementation that combines properties of both CheckPi and BivCopula classes.

class copul.checkerboard.biv_check_pi.BivCheckPi(matr, *args, **kwargs)

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

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()

Blomqvist’s beta.

chatterjees_xi(condition_on_y: bool = False) → float

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)

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

cond_distr_2(*args)

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

dim: int

classmethod generate_randomly(grid_size: int | list | None = None, n: int = 1)

ginis_gamma() → float

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

Check if the copula is cis.

is_ltd()

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

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

Returns:

The calculated tau coefficient.

Return type:

float

params: List = []

spearmans_footrule() → float

spearmans_rho() → float

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()

Transpose the checkerboard matrix.

copul.checkerboard.biv_check_w module

class copul.checkerboard.biv_check_w.BivCheckW(matr, *args, **kwargs)

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

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)

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

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)

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)

ginis_gamma() → float

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

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

Returns:

The calculated tau coefficient.

Return type:

float

lambda_L()

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

lambda_U()

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)

Generate n random samples.

spearmans_footrule() → float

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

Compute Spearman’s rho for a bivariate checkerboard copula.

transpose()

Transpose the checkerboard matrix.

copul.checkerboard.biv_check_w.CheckW

alias of BivCheckW

copul.checkerboard.check module

class copul.checkerboard.check.Check(matr)

Bases: object

chatterjees_xi(n=100000, seed=None, i=1, samples=None)

classmethod from_data(data, num_bins=None, kappa=0.3333333333333333, **kwargs)

Create a checkerboard copula from raw data very quickly by:

1. Sorting each dimension to compute ordinal ranks.

2. Mapping those ranks directly to bin indices.

3. Building the d-dimensional histogram in a single pass.

This is an O(d * n log n) algorithm (due to sorting each dimension). It avoids building an intermediate uniform array, and it does NOT do average ranking for ties (which speeds things up significantly).

Parameters:

• data (array-like, shape (n_samples, n_features)) – The raw data. Each row is a sample.

• num_bins (int or list/array of int, optional) – Number of bins in each dimension. If None, defaults to ~ n^(1/(2*d)) per dimension.

• kappa (float, optional) – Exponent for the number of bins. Default is 1/3. This is a heuristic to control the number of bins vs number of observations per bin. Recommended range is 1.0 to 2.0.

Returns:

A new Check instance (the histogram is normalized in __init__).

Return type:

Check

is_copula(tol=1e-10, warn=False, raise_on_fail=False, report_details=False)

lambda_L()

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

lambda_U()

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

validate_copula(tol=1e-10, warn=False, raise_on_fail=False, report_details=False)

Validate that the checkerboard weights define a proper d-dimensional copula density: - All cell masses are nonnegative (within tol). - Total mass is 1 (within tol). - Each marginal along every axis is uniform: for axis a with size m_a,

the marginal vector equals 1/m_a (within tol).

Parameters:

• tol (float) – Numerical tolerance for validations.

• warn (bool) – If True, emit logging warnings for any violations.

• raise_on_fail (bool) – If True, raise ValueError on the first failure. Otherwise return a report.

Returns:

{

‘ok’: bool, ‘total_mass’: float, ‘mass_error’: float, ‘min_cell’: float, ‘negativity_violation’: float, ‘marginal_errors’: list of dicts per axis with keys:

{‘axis’: int, ‘target’: float, ‘max_abs_dev’: float,

’mean’: float, ‘min’: float, ‘max’: float},

’violations’: list of str

}

Return type:

dict

copul.checkerboard.check_min module

class copul.checkerboard.check_min.CheckMin(matr, *args, **kwargs)

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)

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)

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)

More efficient implementation of random variate sampling.

copul.checkerboard.check_pi module

class copul.checkerboard.check_pi.CheckPi(matr, *args, **kwargs)

Bases: Check, CopulaPlottingMixin, CopulaApproximatorMixin

cdf(*args)

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)

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)

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

cond_distr_2(u)

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

property is_absolutely_continuous: bool

property is_symmetric: bool

lambda_L()

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

lambda_U()

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

pdf(*args)

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)

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

copul.checkerboard.checkerboarder module

class copul.checkerboard.checkerboarder.Checkerboarder(n: int | list = None, dim=2, checkerboard_type='CheckPi')

Bases: object

approximate_shuffle_of_min(copula=None, cmatr=None, order=None)

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)

get_checkerboard_copula(copula, n_jobs=None)

Compute the checkerboard representation of a copula’s CDF.

copul.checkerboard.checkerboarder.from_data(data, checkerboard_size=None, checkerboard_type='CheckPi')

copul.checkerboard.checkerboarder.from_samples(samples, checkerboard_size=None, checkerboard_type='CheckPi')

copul.checkerboard.matrix module

copul.checkerboard.matrix.from_matrix(matrix, checkerboard_type='CheckPi')

copul.checkerboard.shuffle_min module

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

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

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

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

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

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

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

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

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

rvs(size: int, **kwargs) → ndarray

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

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

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

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

Module contents