copul.family package

Subpackages

Submodules

copul.family.copula_builder module

class copul.family.copula_builder.CopulaBuilder[source]

Bases: object

classmethod from_cdf(cdf)[source]
classmethod from_cond_distr_1(cond)[source]

Build a bivariate copula from the conditional CDF F_{V|U=u}(v) = ∂C/∂u (u, v).

classmethod from_cond_distr_2(cond)[source]

Build a bivariate copula from the conditional CDF F_{U|V=v}(u) = ∂C/∂v (u, v).

classmethod from_pdf(pdf)[source]

Build a copula object from a PDF expression.

Parameters:

pdf (str | sympy.Expr) – A symbolic expression for c(u, v) in the bivariate case or c(u1, …, ud) in the d-variate case. Greek-letter symbols are treated as parameters; all other symbols are taken as the copula’s function variables.

copul.family.copula_builder.from_cdf(cdf)[source]
copul.family.copula_builder.from_cond_distr_1(cond)[source]

Build from F_{V|U=u}(v) = ∂C/∂u (u, v).

copul.family.copula_builder.from_cond_distr_2(cond)[source]

Build from F_{U|V=v}(u) = ∂C/∂v (u, v).

copul.family.copula_builder.from_pdf(pdf)[source]

copul.family.copula_graphs module

class copul.family.copula_graphs.CopulaGraphs(copula, add_params=True)[source]

Bases: object

get_copula_name()[source]
get_copula_title()[source]

copul.family.helpers module

copul.family.helpers.concrete_expand_log(expr, first_call=True)[source]

Recursively expand logarithms in a sympy expression in a concrete manner.

On the first call, the function forces an expansion of logarithms using sympy.expand_log. It then recursively traverses the expression. If an expression is a logarithm of a product (as a concrete Product), it is converted into a Sum representation. The recursion continues until all parts of the expression are processed.

Parameters:

  • expr (sympy expression) – The sympy expression in which to expand logarithms.

  • first_call (bool, optional) – If True (default), forces an initial expansion of logarithms using expand_log.

Returns:

The expression with logarithms expanded into a sum form where applicable.

Return type:

sympy expression

copul.family.helpers.get_simplified_solution(sol)[source]

Simplify a sympy expression and extract the primary result.

This function attempts to simplify the given expression using sympy.simplify. If the result is a Tuple (e.g. multiple solutions), the first element is returned. If simplification fails due to a TypeError, the original expression is returned.

Parameters:

sol (sympy expression) – The sympy expression to simplify.

Returns:

The simplified expression, or the first element if the result is a Tuple. If a TypeError occurs during simplification, returns the original input.

Return type:

sympy expression

copul.family.rank_correlation_plotter module

Minimal, extensible rank-correlation plotting for copulas.

How to add a new measure:

  1. Define a function with signature: f(x, y, rank_x, rank_y) -> float

  2. Decorate it with @measure(“Nice Name”) (that’s all; it will show up automatically in compute/plot/export)

Built-ins: xi, rho, tau, footrule, gini_gamma, blomqvists_beta,

schweizer_wolff_sigma, hoeffdings_d

class copul.family.rank_correlation_plotter.CorrelationData(params: 'np.ndarray', values: 'Dict[str, np.ndarray]')[source]

Bases: object

params: ndarray
values: Dict[str, ndarray]
class copul.family.rank_correlation_plotter.RankCorrelationPlotter(copula: Any, *, measures: Iterable[str] | None = None, images_dir: Path | str = 'images', save_pickles: bool = True)[source]

Bases: object

Minimal runner:

  • param grid

  • sample once per param

  • compute registered measures

  • plot & export

compute(params: ndarray, n_obs: int = 1000000, *, approximate: bool = False) → CorrelationData[source]
For each parameter:

  • sample (x,y)

  • compute ranks once

  • evaluate each registered measure

param_grid(n_params: int = 20, *, log_cut_off: Tuple[float, float] | None = None, xlim: Tuple[float, float] | None = None) → ndarray[source]

Build a grid over the primary parameter interval in the copula. If log_cut_off is provided, use a log grid shifted by the left boundary (inf), matching the behavior of the previous implementation.

plot(data: CorrelationData, *, title: str | None = None, ylim: Tuple[float, float] = (-1, 1), log_x: bool = False, log_cut_off: Tuple[float, float] | None = None) → Dict[str, CubicSpline][source]

Scatter + CubicSpline for each measure. If log_x=True, we plot against x - inf, set log scale, and clamp the axis to the exact range implied by log_cut_off (if provided).

save(base_name: str, data: CorrelationData, splines: Dict[str, CubicSpline]) → None[source]
copul.family.rank_correlation_plotter.m_blomqvists_beta(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.m_footrule(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.m_gini_gamma(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.m_hoeffdings_d(x, y, rx, ry) → float[source]

Hoeffding’s D (dependence index) via empirical copula grid.

D̂ = 90 * mean((Ĉ_n(u,v) - u*v)^2)

copul.family.rank_correlation_plotter.m_nu(x, y, rx, ry) → float[source]

Blest’s rank correlation ν via the empirical copula plug-in.

Using C_n(u,v) = (1/n) Σ 1{R_j/n ≤ u, S_j/n ≤ v} with ranks R,S∈{1,…,n}, we get

∫∫ (1-u) C_n(u,v) du dv

= (1/n) Σ [ ∫_{u=R_j/n}^1 (1-u) du ] [ ∫_{v=S_j/n}^1 dv ] = (1/n) Σ [ (1 - R_j/n)^2 / 2 ] [ 1 - S_j/n ].

Hence the estimator:

ν̂ = 24 * ( (1/n) Σ ((1 - R_j/n)^2 / 2) * (1 - S_j/n) ) - 2.

copul.family.rank_correlation_plotter.m_rho(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.m_schweizer_wolff(x, y, rx, ry) → float[source]

Schweizer–Wolff sigma via the empirical copula.

σ̂ = 12 * mean(|Ĉ_n(u_i, v_i) - u_i * v_i|)

where u_i = R_i/n, v_i = S_i/n and Ĉ_n is the empirical copula. The O(n²) exact sum is replaced by a fast rank-based estimator using the same identity that yields Spearman’s rho.

copul.family.rank_correlation_plotter.m_tau(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.m_xi(x, y, rx, ry) → float[source]
copul.family.rank_correlation_plotter.measure(name: str) → Callable[[Callable[[ndarray, ndarray, ndarray, ndarray], float]], Callable[[ndarray, ndarray, ndarray, ndarray], float]][source]

Decorator to register a rank-correlation-like measure.

copul.family.rank_correlation_plotter.run_plot(copula: Any, *, measures: Iterable[str] | None = None, n_obs: int = 10000, n_params: int = 20, log_cut_off: Tuple[float, float] | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] = (-1, 1), approximate: bool = False, images_dir: str | Path = 'images', save_pickles: bool = True)[source]

copul.family.tp2_verifier module

class copul.family.tp2_verifier.TP2Verifier(range_min: float | None = None, range_max: float | None = None)[source]

Bases: object

Class for verifying if a copula satisfies the TP2 property.

The TP2 (totally positive of order 2) property is an important mathematical property for copulas, indicating that the copula’s density satisfies certain log-supermodularity conditions.

check_violation(copula: Any, log_pdf: Expr, x1: float, x2: float, y1: float, y2: float) → bool[source]

Check if the TP2 property is violated at specific points.

is_tp2(copula: Any) → bool[source]

Check if a copula satisfies the TP2 property.

Parameters:

copula – Copula instance or class to check

Returns:

True if the copula is TP2, False otherwise

verify_tp2(copula: Any) → VerificationResult[source]

Verify the TP2 property for a copula and return detailed results.

Parameters:

copula – Copula class or factory to check

Returns:

VerificationResult object containing verification details

class copul.family.tp2_verifier.VerificationResult(is_tp2: bool, violations: List[Dict[str, float]], tested_params: List[Dict[str, float]])[source]

Bases: object

Class to represent TP2 verification results.

is_tp2: bool
tested_params: List[Dict[str, float]]
violations: List[Dict[str, float]]
copul.family.tp2_verifier.verify_copula_tp2(copula: Any, range_min: float | None = None, range_max: float | None = None) → VerificationResult[source]

Convenience function to verify if a copula satisfies the TP2 property.

Module contents