copul.schur_order package

Submodules

copul.schur_order.bounds_from_xi module

copul.schur_order.bounds_from_xi.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]

Unified entry point. Returns (min_value, max_value) for the chosen measure given xi=x.

copul.schur_order.bounds_from_xi.nu_bounds_from_xi(x: float) → Tuple[float, float]

Exact bounds (nu_min, nu_max) given xi=x, via the parametric boundary y = ±N(b) with Xi(b)=x.

copul.schur_order.bounds_from_xi.psi_bounds_from_xi(x: float, cls: Literal['all', 'SI'] = 'all', return_lower_bound: bool = True) → Tuple[float, float]

Returns (psi_min, psi_max) for a given xi.

copul.schur_order.bounds_from_xi.psi_max_given_xi(x: float, cls: Literal['all', 'SI'] = 'all') → float

Maximal psi given xi. - For all copulas: exact psi_max = sqrt(xi). - For SI copulas: same upper bound.

copul.schur_order.bounds_from_xi.psi_min_given_xi_si(x: float) → float

Minimal psi given xi for SI copulas (exact).

copul.schur_order.bounds_from_xi.psi_min_lower_bound_given_xi_all(x: float) → float

Rigorous LOWER BOUND for the minimal psi over ALL copulas at fixed xi=x.

copul.schur_order.bounds_from_xi.rho_bounds_from_xi(x: float) → Tuple[float, float]

Returns (rho_min, rho_max). Exact symmetry: rho_min = -rho_max.

copul.schur_order.bounds_from_xi.rho_max_given_xi(x: float) → float

Maximal rho given xi, over all copulas (exact).

copul.schur_order.bounds_from_xi.tau_bounds_from_xi(x: float) → Tuple[float, float]

Returns (tau_min, tau_max). Exact symmetry: tau_min = -tau_max.

copul.schur_order.bounds_from_xi.tau_max_given_xi(x: float) → float

Maximal Kendall’s tau given xi, over all copulas (exact).

copul.schur_order.cis_rearranger module

CISRearranger module for rearranging copulas to be conditionally increasing in sequence.

This module implements the rearrangement algorithm from: Strothmann, Dette, Siburg (2022) - “Rearranged dependence measures”

class copul.schur_order.cis_rearranger.CISRearranger(checkerboard_size: int | None = None)

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

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

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

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

copul.schur_order.cis_rearranger.apply_cis_rearrangement(copula: Any, grid_size: int | None = None) → BivCheckPi

Apply CIS rearrangement to a copula and return as a BivCheckPi object.

This convenience function rearranges a copula and returns it as a BivCheckPi object for easy use in further computations.

Parameters:

• copula – The copula to rearrange

• grid_size – Size of the checkerboard grid (optional)

Returns:

A checkerboard copula with the CIS property

Return type:

BivCheckPi

copul.schur_order.cis_verifier module

class copul.schur_order.cis_verifier.CISVerifier(cond_distr=1)

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)

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

copul.schur_order.ltd_verifier module

class copul.schur_order.ltd_verifier.LTDVerifier

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)

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

copul.schur_order.plod_verifier module

class copul.schur_order.plod_verifier.PLODVerifier

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)

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

copul.schur_order.schur_order_verifier module

Module for verifying Schur ordering of copula families.

This module provides tools to check if a copula family satisfies the Schur ordering property as the parameter varies.

class copul.schur_order.schur_order_verifier.SchurOrderVerifier(copula, n_theta=40, chess_board_size=10, tolerance=1e-10)

Bases: object

A class to verify if a copula family satisfies the Schur ordering property.

Schur ordering is a property related to the dependence structure of copulas. This class provides methods to check if a copula family is positively or negatively Schur ordered with respect to its parameter.

Parameters:

• copula (Copula object) – The copula family to verify.

• n_theta (int, optional) – Number of parameter values to check. Default is 40.

• chess_board_size (int, optional) – Size of the chess board for discretization. Default is 10.

• tolerance (float, optional) – Numerical tolerance for comparisons. Default is 1e-10.

verify(range_min=None, range_max=None, verbose=True)

Verify if the copula family is Schur ordered.

Parameters:

• range_min (float, optional) – Minimum value of the parameter range. If None, uses the lower bound of the copula parameter interval.

• range_max (float, optional) – Maximum value of the parameter range. If None, uses the upper bound of the copula parameter interval.

• verbose (bool, optional) – Whether to print progress and result messages. Default is True.

Returns:

True if the copula is Schur ordered (either positively or negatively), False otherwise.

Return type:

bool

Notes

The function checks for positive Schur ordering first. If that fails, it checks for negative Schur ordering. A copula is Schur ordered if either of these checks passes.

copul.schur_order.schur_visualizer module

SchurVisualizer module for visualizing properties of copulas.

class copul.schur_order.schur_visualizer.SchurVisualizer(copula, v=0.5, x_vals=None)

Bases: object

Class for visualizing Schur-related properties of copulas.

copula

Copula object to visualize

_v

Conditional value for visualization

_x_vals

Array of x values for evaluation

compute()

Compute conditional distribution values.

Returns:

Array of conditional distribution values

plot_for(thetas)

Plot conditional distributions for specified parameter values.

Parameters:

thetas – Parameter value or list of parameter values

Returns:

Dictionary mapping parameter values to computed y values

copul.schur_order.schur_visualizer.visualize_rearranged(nelsen, thetas, v, grid_size=10)

Visualize rearranged copula.

Parameters:

• nelsen – Copula class or factory

• thetas – Parameter values for the copula

• v – Conditional value

• grid_size – Size of grid for rearrangement (default: 10)

Module contents