copul.family.core package

Submodules

copul.family.core.biv_copula module

class copul.family.core.biv_copula.BivCopula(*args, **kwargs)

Bases: Copula, BivCoreCopula

copul.family.core.biv_core_copula module

class copul.family.core.biv_core_copula.BivCoreCopula

Bases: object

Base class for bivariate copulas using symbolic expressions.

This class extends CoreCopula for the bivariate (2-dimensional) case. It provides functionality for sampling, evaluation of the PDF, conditional distributions, and various dependence measures such as Chatterjee’s xi, Spearman’s rho, and Kendall’s tau. Additionally, plotting utilities are included for visualizing the copula’s functions.

blests_nu(*args, **kwargs)

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

Blomqvist’s β := 4·C(½,½) – 1

chatterjees_xi(*args, **kwargs)

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

concordance_order(other: BivCoreCopula, n_grid: int = 20, tol: float = 1e-09) → bool

Numerically check whether self is concordance-ordered below other.

Returns True if \(C_1(u,v) \le C_2(u,v)\) for all \((u,v)\) on a uniform \(n\_grid \times n\_grid\) grid over \((0.05, 0.95)^2\), i.e. whether \(C_1 \preceq_c C_2\) in the concordance partial order.

Parameters:

• other (BivCoreCopula) – The copula to compare against.

• n_grid (int) – Number of evaluation points per axis (default 20).

• tol (float) – Numerical tolerance for the inequality (default 1e-9).

Returns:

True if self ≤_c other on the grid, False otherwise.

Return type:

bool

cond_distr_1(u=None, v=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=None, v=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

gini_gamma(*args, **kwargs)

Compute Gini’s gamma concordance coefficient.

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

Range: \([-1, 1]\). \(\gamma = 1\) for the upper Fréchet bound (comonotonic), \(\gamma = -1\) for the lower Fréchet bound (countermonotonic), \(\gamma = 0\) for independence.

Returns:

The symbolic expression for Gini’s gamma.

Return type:

sympy.Expr

hoeffdings_d(*args, **kwargs)

Hoeffding’s \(D\) dependence measure (also called the dependence index or \(\Phi^2\)).

\[D(C) = 90 \iint_{[0,1]^2} \bigl[C(u,v) - uv\bigr]^2\,du\,dv\]

This is the squared \(L_2\) analogue of Spearman’s \(\rho\) (which uses an \(L_1\) integral of the signed deviation). It measures any departure from independence, monotone or not.

Range: \([0, 1]\). \(D = 0\) iff \(C = \Pi\) (independence).

Falls back to numerical quadrature when SymPy cannot evaluate the double integral in closed form.

Return type:

sympy.Expr or float

References

Hoeffding, W. (1940). “Masstabinvariante Korrelationstheorie.” Schweizer, B. & Wolff, E. F. (1981). “On Nonparametric Measures of Dependence for Random Variables.” Ann. Statist. 9(4).

intervals: dict = {}

is_cis(cond_distr=1)

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

is_tp2(range_min=None, range_max=None)

Check if the copula satisfies the TP2 (Total Positivity of order 2) property.

Parameters:

• range_min (numeric, optional) – Minimum value of the range for testing (default is None).

• range_max (numeric, optional) – Maximum value of the range for testing (default is None).

Returns:

True if the copula is TP2, False otherwise.

Return type:

bool

kendalls_tau(*args, **kwargs)

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

lambda_L()

Compute the lower tail dependence coefficient.

Returns:

The symbolic expression for the lower tail dependence.

Return type:

sympy.Expr

lambda_U()

Compute the upper tail dependence coefficient.

Returns:

The simplified symbolic expression for the upper tail dependence.

Return type:

sympy.Expr

log_cut_off = 4

lower_tail_concentration(t_val=None)

Lower tail concentration function \(L(t) = C(t,t)\,/\,t\).

This function interpolates between \(L(t)\to\lambda_L\) as \(t\to 0^+\) (lower tail dependence coefficient) and \(L(1) = C(1,1) = 1\). A plot of \(L(t)\) vs \(t\) visualises how tail dependence builds up.

Parameters:

t_val (float or None) – If given, evaluate numerically at this point in \((0,1)\). If None, return the SymPy expression in the symbol t.

Return type:

sympy.Expr or float

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

\(L_p\) concordance distance from independence.

\[\delta_p(C) = k(p)\, \iint_{[0,1]^2} \lvert C(u,v) - uv \rvert^{p}\,du\,dv\]

where \(k(p)\) is chosen so that \(\delta_p(M) = 1\) for the Fréchet upper bound \(M(u,v) = \min(u,v)\).

Special cases:

Parameters:

p (int) – The exponent (default 2). Pre-tabulated for p = 1 … 5.

Return type:

sympy.Expr or float

mutual_information(*args, **kwargs)

Copula-based mutual information (negative copula entropy).

\[I(C) = -\iint_{[0,1]^2} c(u,v)\,\ln c(u,v)\,du\,dv\]

where \(c(u,v) = \partial^2 C/\partial u\,\partial v\) is the copula density. This equals the mutual information of a pair \((X,Y)\) whose copula is \(C\), regardless of the marginals.

Range: \([0, \infty)\). \(I = 0\) iff \(C = \Pi\) (independence).

Because the integrand involves \(\ln(c)\), symbolic evaluation rarely succeeds; the method defaults to numerical quadrature.

Parameters:

n_grid (int) – Number of grid points per axis for quadrature (default 80).

Return type:

float

params: list = []

property pdf

Evaluate the probability density function (PDF) of the copula.

The PDF is computed by differentiating the conditional distribution.

Returns:

A wrapper around the simplified symbolic expression for the PDF.

Return type:

SymPyFuncWrapper

plot(*args, **kwargs)

Plot one or more functions related to the copula.

If no functions are provided as arguments, the CDF is plotted by default. Additional functions can be passed as positional arguments and are labeled automatically in the legend.

Parameters:

• *args – One or more functions to be plotted.

• **kwargs – Additional keyword arguments where keys become labels for the functions.

Notes

The function uses the free symbolic parameters to determine plotting ranges.

plot_cdf(data=None, title=None, zlabel=None, *, plot_type='3d', log_z=False, **kwargs) → Figure

Plot the cumulative distribution function (CDF).

Parameters:

• plot_type ({"3d", "contour"}) – Choose visualisation style.

• log_z (bool, optional (contour only)) – Use logarithmic colour scaling (matplotlib.colors.LogNorm).

plot_cond_distr_1(*, plot_type='3d', log_z=False, **kwargs) → Figure

plot_cond_distr_2(*, plot_type='3d', log_z=False, **kwargs)

plot_pdf(*args, plot_type='3d', log_z=False, **kwargs) → Figure

Plot the probability density function (PDF).

Parameters:

• plot_type ({"3d", "contour"})

• log_z (bool, optional (contour only))

plot_rank_correlations(n_obs=10000, n_params=20, plot_var=False, ylim=(-1, 1), params=None, log_cut_off=None, approximate=False)

Plot rank correlations for the copula.

This method creates a RankCorrelationPlotter instance for the current copula, and uses it to plot various rank correlation measures (e.g. Chatterjee’s xi). Optionally, variance bands can be plotted along with the main correlation curve.

Parameters:

• n_obs (int, optional) – Number of observations to simulate per evaluation point (default is 10,000).

• n_params (int, optional) – Number of parameter values to evaluate (default is 20).

• plot_var (bool, optional) – Whether to plot variance bands in the correlation plot (default is False).

• ylim (tuple of float, optional) – Y-axis limits for the plot (default is (-1, 1)).

• params (dict or None, optional) – Dictionary of additional parameters for mixed-parameter plotting. If None, only the main parameter is used (default is None).

• log_cut_off (int, float, tuple, or None, optional) – Cut-off value(s) for applying a logarithmic scale to the x-axis. If provided, the plot will use a log scale (default is None).

• approximate (bool, optional) – Whether to use approximate sampling via checkerboard copulas.

Returns:

This method displays the plot using matplotlib.

Return type:

None

plot_tail_concentration(n_pts: int = 200) → Figure

Plot the lower and upper tail concentration functions on one figure.

The lower curve \(L(t)=C(t,t)/t\) and the upper curve \(R(t)=(1-2t+C(t,t))/(1-t)\) are drawn against \(t\in(0,1)\). Horizontal dashed lines mark the tail dependence coefficients \(\lambda_L\) and \(\lambda_U\).

Parameters:

n_pts (int) – Number of grid points (default 200).

Return type:

matplotlib.figure.Figure

schweizer_wolff_sigma(*args, **kwargs)

Schweizer–Wolff’s \(\sigma\) dependence measure.

\[\sigma(C) = 12 \iint_{[0,1]^2} \lvert C(u,v) - uv \rvert\,du\,dv\]

Unlike Spearman’s \(\rho\) (which uses the signed deviation \(C - \Pi\)), this measure takes the absolute value and therefore captures any departure from independence, including non-monotone dependence.

Range: \([0, 1]\). \(\sigma = 0\) iff \(C = \Pi\) (independence).

When the integral cannot be evaluated symbolically (because \(|C - \Pi|\) introduces piecewise terms that SymPy cannot always simplify), the method falls back to numerical quadrature on a 50 × 50 grid.

Return type:

sympy.Expr or float

spearman_footrule(*args, **kwargs)

Compute Spearman’s footrule coefficient \(\psi\).

\[\psi(C) = 6 \int_0^1 C(t,t)\,dt - 2\]

Equivalently, \(\psi(C) = 6\,\mathbb{E}[\min(U,V)] - 2\) where \((U,V) \sim C\).

Range: \([-\tfrac{1}{2}, 1]\). \(\psi = 1\) for the upper Fréchet bound, \(\psi = -\tfrac{1}{2}\) for the lower Fréchet bound, \(\psi = 0\) for independence.

Returns:

The symbolic expression for Spearman’s footrule coefficient.

Return type:

sympy.Expr

spearmans_rho(*args, **kwargs)

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

tail_dependence_function(t, lower=True)

Tail dependence function (TDF) evaluated numerically.

The lower TDF is defined as

\[b_L(t) = \lim_{s\to 0^+} \frac{C\bigl(s(1-t),\, st\bigr)}{s}, \qquad t\in[0,1],\]

and the upper TDF as

\[b_U(t) = \lim_{s\to 0^+} \frac{\hat C\bigl(s(1-t),\, st\bigr)}{s}\]

where \(\hat C\) is the survival copula.

The diagonal value \(b(1/2)\) equals \(\lambda / 2\) where \(\lambda\) is the corresponding tail dependence coefficient. The full function describes how probability mass concentrates in the tail.

Parameters:

• t (float or array_like) – Point(s) in \([0,1]\).

• lower (bool) – True for the lower TDF, False for the upper TDF.

Return type:

float or numpy.ndarray

References

Joe & Li (2011), Tail Risk of Multivariate Regular Variation, Methodology and Computing in Applied Probability 13, 671–693.

tail_order()

Tail order \(\kappa\) (lower and upper).

The tail order describes the polynomial rate at which \(C(t,t)\) vanishes as \(t\to 0^+\):

\[C(t,t) \sim t^{\kappa_L} \ell(t), \qquad t \to 0^+.\]

Analogously, \(\hat C(t,t) \sim t^{\kappa_U}\ell(t)\) as \(t\to 0^+\) defines the upper tail order.

• \(\kappa = 1\) ⟹ tail dependence (\(\lambda > 0\)).

• \(1 < \kappa < 2\) ⟹ intermediate tail dependence.

• \(\kappa = 2\) ⟹ tail independence (same rate as Π).

Computed here by a log–log regression on small quantiles.

Returns:

{"lower": kappa_L, "upper": kappa_U}

Return type:

dict

References

Ledford & Tawn (1996), Statistics for near independence in multivariate extreme values, Biometrika 83, 169–187.

u = u

upper_tail_concentration(t_val=None)

Upper tail concentration function \(R(t) = (1 - 2t + C(t,t))\,/\,(1-t)\).

This function satisfies \(R(t)\to\lambda_U\) as \(t\to 1^-\) (upper tail dependence coefficient) and \(R(0) = 1\).

Parameters:

t_val (float or None) – If given, evaluate numerically at this point in \((0,1)\). If None, return the SymPy expression in the symbol t.

Return type:

sympy.Expr or float

v = v

copul.family.core.copula module

class copul.family.core.copula.Copula(dimension, *args, **kwargs)

Bases: CoreCopula, CopulaSamplingMixin, CopulaPlottingMixin, CopulaApproximatorMixin

copul.family.core.copula_approximator_mixin module

class copul.family.core.copula_approximator_mixin.CopulaApproximatorMixin

Bases: object

A mixin class providing methods to approximate a copula using various checkerboard-based structures.

dim: int

to_bernstein(grid_size: Tuple[int, ...] | int = 10)

Convert the copula to a Bernstein copula approximation.

Parameters:

grid_size (tuple or int, optional) – Order of the Bernstein polynomial basis (default is 10). If int, assumes equal order m in all dimensions.

Returns:

A BernsteinCopula object representing the copula approximation.

Return type:

BernsteinCopula

to_check_min(grid_size: Tuple[int, ...] | int = 20)

Convert the copula to a CheckMin object.

Parameters:

grid_size (tuple or int, optional) – Size of the grid for the checkerboard (default is 100). If int, assumes equal size in all dimensions.

Returns:

A CheckMin object representing the copula approximation.

Return type:

CheckMin

to_check_pi(grid_size: Tuple[int, ...] | int = 20)

Convert the copula to a CheckPi object.

Parameters:

grid_size (tuple or int, optional) – Size of the grid for the checkerboard (default is 100). If int, assumes equal size in all dimensions.

Returns:

A CheckPi object representing the copula approximation.

Return type:

CheckPi

to_check_w(grid_size: Tuple[int, ...] | int = 20)

Convert the copula to a CheckW object.

Parameters:

grid_size (tuple or int, optional) – Size of the grid for the checkerboard (default is 100). If int, assumes equal size in all dimensions.

Returns:

A CheckW object representing the copula approximation.

Return type:

CheckW

to_checkerboard(grid_size: Tuple[int, ...] | int = 20, checkerboard_type: str = 'BivCheckPi')

Generic method to convert the copula to a specified checkerboard type.

Parameters:

• grid_size (tuple or int, optional) – Size of the grid for the checkerboard (default is 100). If int, assumes equal size n, resulting in an n x n x … grid.

• checkerboard_type (str, optional) – Type of checkerboard copula (default is “BivCheckPi”). This string is passed to the Checkerboarder to determine which copula type to instantiate and return.

Returns:

An instance of the specified checkerboard copula type, approximating the original copula.

Return type:

object

to_shuffle_of_min(grid_size: int = 5000)

Approximate the copula using a ShuffleOfMin copula.

This method uses the checkerboard framework to find the permutation ‘pi’ for a ShuffleOfMin copula of order ‘n’ (determined by grid_size) that best approximates the mass distribution of the original bivariate copula.

Parameters:

grid_size (int, optional) – The order ‘n’ of the resulting ShuffleOfMin copula, which defines the number of segments used in the approximation (default is 100). This corresponds to an n x n grid for the underlying checkerboard calculation.

Returns:

A ShuffleOfMin object approximating the original copula.

Return type:

ShuffleOfMin

Raises:

• ValueError – If the original copula is not bivariate (self.dim != 2), as ShuffleOfMin is defined for two dimensions.

• AttributeError – If the object using the mixin doesn’t have a ‘dim’ attribute.

copul.family.core.copula_plotting_mixin module

class copul.family.core.copula_plotting_mixin.CopulaPlottingMixin

Bases: object

Mixin class for copula sampling methods. This class provides methods for sampling from copulas using different techniques.

create_comparison_plot(other_copula, n=1000, figsize=(15, 7), colormap='viridis', style='default', dpi=120)

Create a comparison plot between this copula and another one.

Parameters:

• other_copula (Copula) – Another copula to compare with.

• n (int, optional) – Number of samples to generate from each copula.

• figsize (tuple, optional) – Figure size as (width, height) in inches.

• colormap (str, optional) – Colormap to use for the plots.

• style (str, optional) – Matplotlib style to use.

• dpi (int, optional) – Resolution of the figure.

Returns:

fig – The created figure object.

Return type:

matplotlib.figure.Figure

plot_c_over_u(*, plot_type='3d', log_z=False, **kwargs)

Plot the ratio C(u,v) / u on (0,1)².

Works whether cdf is a SymPy expression/wrapper or a numeric Python function (e.g. in ShuffleOfMin).

Parameters:

• plot_type ({"3d", "contour", "functions"}, optional) –

  • “3d” : surface plot (default)

  • ”contour” : filled contour plot

  • ”functions”: 9 one-dimensional slices v = 0.1,…,0.9

• log_z (bool, optional) – Log–colour scale for the contour plot.

• **kwargs (forwarded to the internal plotting routine.)

plot_c_over_v(*, plot_type='3d', log_z=False, **kwargs)

Plot the ratio C(u,v) / v on (0,1)².

The interface is identical to plot_c_over_u.

plot_density(grid_size=50, figsize=(10, 8), colormap='viridis', style='default', dpi=120, add_contours=True, contour_levels=10, contour_colors='black', contour_alpha=0.6, add_colorbar=True)

Create a density plot of the copula.

Parameters:

• grid_size (int, optional) – Number of grid points in each dimension.

• figsize (tuple, optional) – Figure size as (width, height) in inches.

• colormap (str, optional) – Colormap to use for the density plot.

• style (str, optional) – Matplotlib style to use.

• dpi (int, optional) – Resolution of the figure.

• add_contours (bool, optional) – Whether to add contour lines to the density plot.

• contour_levels (int, optional) – Number of contour levels to add.

• contour_colors (str or list, optional) – Color(s) for contour lines.

• contour_alpha (float, optional) – Transparency of contour lines (0 to 1).

• add_colorbar (bool, optional) – Whether to add a colorbar to the plot.

Returns:

fig – The created figure object.

Return type:

matplotlib.figure.Figure

save_plot(filename, n=1000, approximate=False, figsize=(12, 10), alpha=0.7, colormap='viridis', style='default', point_size=None, dpi=300, grid_alpha=0.2, contour_levels=10, add_contours=True, add_marginals=True, format='png', transparent=False)

Create and save a scatter plot of random variates from the copula.

Parameters:

• filename (str) – Path where the plot will be saved.

• n (int, optional) – The number of samples to generate (default is 1,000).

• approximate (bool, optional) – Whether to use explicit sampling or approximate sampling.

• figsize (tuple, optional) – Figure size as (width, height) in inches.

• alpha (float, optional) – Transparency of points (0 to 1).

• colormap (str, optional) – Colormap to use for plots.

• style (str, optional) – Matplotlib style to use.

• point_size (int, optional) – Size of scatter points.

• dpi (int, optional) – Resolution of the saved figure.

• grid_alpha (float, optional) – Transparency of grid lines (0 to 1).

• contour_levels (int, optional) – Number of contour levels to add.

• add_contours (bool, optional) – Whether to add density contours to 2D plots.

• add_marginals (bool, optional) – Whether to add marginal distributions to 2D plots.

• format (str, optional) – File format to save the plot (e.g., ‘png’, ‘pdf’, ‘svg’).

• transparent (bool, optional) – Whether to save with a transparent background.

Return type:

None

scatter_plot(n=1000, approximate=False, figsize=(10, 8), alpha=0.6, colormap='viridis', samples=None)

Create a scatter plot of random variates from the copula.

Parameters:

• n (int, optional) – The number of samples to generate (default is 1,000).

• approximate (bool, optional) – Whether to use explicit sampling from the conditional distributions or approximate sampling with a checkerboard copula

• figsize (tuple, optional) – Figure size as (width, height) in inches.

• alpha (float, optional) – Transparency of points (0 to 1).

• colormap (str, optional) – Colormap to use for 3D plots.

• samples (np.ndarray, optional) – Pre-generated samples to plot. If provided, n is ignored.

Return type:

None

copul.family.core.copula_sampling_mixin module

class copul.family.core.copula_sampling_mixin.CopulaSamplingMixin

Bases: object

Mixin class for copula sampling methods. This class provides methods for sampling from copulas using different techniques.

rvs(n=1, random_state=None, approximate=False)

Generate random variates from the copula.

Parameters:

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

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

• approximate (bool, optional) – Whether to use approximate sampling.

Returns:

An array of shape (n, dim) containing samples from the copula.

Return type:

np.ndarray

scatter_plot(n=1000, approximate=False, figsize=(10, 8), alpha=0.6, colormap='viridis')

Create a scatter plot of random variates from the copula.

Parameters:

• n (int, optional) – The number of samples to generate (default is 1,000).

• approximate (bool, optional) – Whether to use explicit sampling from the conditional distributions or approximate sampling with a checkerboard copula

• figsize (tuple, optional) – Figure size as (width, height) in inches.

• alpha (float, optional) – Transparency of points (0 to 1).

• colormap (str, optional) – Colormap to use for 3D plots.

Return type:

None

copul.family.core.core_copula module

class copul.family.core.core_copula.CoreCopula(dimension, *args, **kwargs)

Bases: object

Unified core for copula classes.

This class consolidates functionality that was previously split between CoreCopula and Copula. It manages symbolic CDF/PDF expressions, parameters and their admissible intervals, and provides flexible evaluation utilities (single point, vectorized, and partially substituted forms).

cdf(*args, **kwargs)

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(i, *args, **kwargs)

Evaluate (or partially evaluate) the conditional distribution F_{U_{-i}|U_i}(u_{-i} | u_i) = ∂C/∂u_i.

cond_distr_1(*args, **kwargs)

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

Parameters:

• *args – See cond_distr().

• **kwargs – See cond_distr().

cond_distr_2(*args, **kwargs)

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

Parameters:

• *args – See cond_distr().

• **kwargs – See cond_distr().

intervals = {}

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.

is_copula(m: int = 21, tol: float = 1e-08, return_details: bool = False)

is_fully_specified() → bool

True iff all parameters have been assigned concrete values.

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.

log_cut_off = 4

property parameters

Parameter intervals of the copula.

Returns:

Mapping name -> sympy.Interval for the remaining (not yet fixed) parameters.

Return type:

dict

params = []

pdf(*args, **kwargs)

Evaluate (or partially evaluate) the PDF:

∂^d C / ∂u1 … ∂ud

slice_interval(param, interval_start=None, interval_end=None)

Restrict the admissible interval of a parameter.

Parameters:

• param (str or sympy.Symbol) – Parameter to restrict.

• interval_start (float, optional) – New lower bound (inclusive).

• interval_end (float, optional) – New upper bound (inclusive).

Notes

If a bound is not provided, the corresponding bound from the current interval is kept. Open bounds are closed when explicitly set.

survival_copula()

Return the survival (upper-tail) copula \(\widehat C\) corresponding to self.

In \(d\) dimensions, the survival copula is given by the inclusion–exclusion formula

\[\widehat C(u) \;=\; \sum_{J\subseteq\{1,\dots,d\}} (-1)^{|J|} \, C\!\big(u^{(J)}\big),\]

where \(u^{(J)}\) denotes the vector obtained from \(u\) by replacing \(u_j\) with \(1\) for all \(j\in J\).

Returns:

A new copula object whose CDF expression is the survival copula of the current one.

Return type:

CoreCopula

validate_copula(m: int = 21, tol: float = 1e-08, return_details: bool = False)

Numerically validate copula properties on an (m+1)^d grid.

Parameters:

• m (int) – Number of intervals per axis (grid has m+1 knots).

• tol (float) – Numerical tolerance for checks.

• return_details (bool) – If True, returns a dict with diagnostics in addition to the boolean.

Returns:

ok

Return type:

bool (and optionally details : dict)

vertical_reflection(margin: int = 2)

Vertical reflection \(C^{\vee}\) of self with respect to one margin.

By default (margin=2) and in the bivariate case, [ C^{vee}(u,v) ;=; u ;-; Cbigl(u,,1-vbigr). ] For general margin=j (1 \le j \le \mathrm{dim}), [ C^{vee}(u) ;=; u_j ;-; Cbigl(u_1,dots,u_{j-1},,1-u_j,,u_{j+1},dots,u_dbigr). ]

Parameters:

margin (int, optional) – 1-based index of the reflected coordinate (default 2).

Returns:

A new copula object whose CDF expression is the vertical reflection of the current one.

Return type:

CoreCopula

Module contents