Copula

Copula(family, theta, df=None, margin_x=None, margin_y=None)

A bivariate copula.

Stateless: the object holds its spec as a JSON string and every verb runs one method through _core.copula_run. Nothing holds C++ state, so instances pickle and compare across processes. Mirrors the C# BivariateCopula hierarchy of the Numerics library (ClaytonCopula, GumbelCopula, …).

margin_x and margin_y are optional :class:Distribution marginals, attached exactly as given (with no re-fitting) – see :func:copula_fit for the estimation surface, where a marginal can also be given as a bare family-name string to be fitted.

Parameters

Name	Type	Description	Default
family	str	One of :func:copula_names.	required
theta	float	The dependence parameter.	required
df	float	Degrees of freedom, required for "StudentT" and ignored otherwise.	None
margin_x	Distribution	Marginals, attached exactly as given.	None
margin_y	Distribution	Marginals, attached exactly as given.	None

See Also

copula_fit

Examples

>>> Copula("Clayton", theta=2).pdf(0.3, 0.7) > 0
True

Attributes

Name	Description
df	float or None: Degrees of freedom ("StudentT" only).
family	str: The copula family name.
margin_x	Distribution or None: The x marginal, when attached.
margin_y	Distribution or None: The y marginal, when attached.
theta	float: The fitted or given dependence parameter.

Methods

Name	Description
bounds	The valid range of the dependence parameter for this copula’s family.
cdf	Copula distribution function on the unit square. See :meth:pdf.
exceedance	Joint exceedance probability.
inverse_cdf	Copula inverse CDF.
log_likelihood	Copula log-likelihood over a paired sample.
log_pdf	Copula log-density on the unit square. See :meth:pdf.
params	The copula’s dependence parameter vector.
pdf	Copula density on the unit square.
random	Draw from the copula’s own seeded Mersenne Twister stream.
tail_dependence	Lower and upper tail dependence coefficients.
to_json	This copula’s spec as the JSON the shared C++ core parses.

bounds

Copula.bounds()

The valid range of the dependence parameter for this copula’s family.

Returns

Name	Type	Description
	dict	Keys "minimum" and "maximum".

cdf

Copula.cdf(u, v)

Copula distribution function on the unit square. See :meth:pdf.

exceedance

Copula.exceedance(u, v, type='and')

Joint exceedance probability.

The probability that both variables exceed their thresholds, P(U > u, V > v) (type = "and"), or that at least one does, P(U > u or V > v) = 1 - C(u, v) (type = "or").

Parameters

Name	Type	Description	Default
u	float	Scalars in (0, 1).	required
v	float	Scalars in (0, 1).	required
type	('and', 'or')	"and" for the joint (both-exceed) probability, "or" for the union (either-exceeds) probability.	"and"

Returns

Name	Type	Description
	float	A single value in [0, 1].

inverse_cdf

Copula.inverse_cdf(u, v)

Copula inverse CDF.

Parameters

Name	Type	Description	Default
u	float	Scalars in (0, 1).	required
v	float	Scalars in (0, 1).	required

Returns

Name	Type	Description
	numpy.ndarray	Length two.

log_likelihood

Copula.log_likelihood(x, y, method='pseudo')

Copula log-likelihood over a paired sample.

Three log-likelihoods, differing in how the marginals enter: the pseudo log-likelihood works on the data’s pseudo-observations (no marginals needed), IFM (inference from margins) transforms the raw data through the attached marginal CDFs then evaluates the copula density, and the full log-likelihood adds the marginal log-densities to that. method="ifm" and "full" need margin_x/margin_y attached.

x and y are always raw paired observations on their own data scale. Upstream’s pseudo log-likelihood is defined on values already on (0, 1), so "pseudo" converts the sample to its plotting positions, rank / (n + 1), first; that transform happens inside the shared C++ core (the same one :func:copula_fit’s "mpl" fit uses), so R and Python return the same number for the same input.

Parameters

Name	Type	Description	Default
x	array-like of float	Raw paired observations, the same length.	required
y	array-like of float	Raw paired observations, the same length.	required
method	('pseudo', 'ifm', 'full')	Which log-likelihood to evaluate.	"pseudo"

Returns

Name	Type	Description
	float

log_pdf

Copula.log_pdf(u, v)

Copula log-density on the unit square. See :meth:pdf.

params

Copula.params()

The copula’s dependence parameter vector.

Returns

Name	Type	Description
	numpy.ndarray	theta, and df for "StudentT".

pdf

Copula.pdf(u, v)

Copula density on the unit square.

u and v are recycled to a common length and evaluated pairwise, one returned value per pair.

Parameters

Name	Type	Description	Default
u	float or array - like	Values in (0, 1), the copula’s two arguments.	required
v	float or array - like	Values in (0, 1), the copula’s two arguments.	required

Returns

Name	Type	Description
	float or numpy.ndarray	One value per recycled (u, v) pair; a scalar when both u and v are scalars.

random

Copula.random(n, seed=None)

Draw from the copula’s own seeded Mersenne Twister stream.

Mapped through the attached marginals to the data scale when both margin_x and margin_y were supplied; on the unit square otherwise. A given seed reproduces the same draws bit-for-bit in R, Python, and the upstream C# library.

Parameters

Name	Type	Description	Default
n	int	Number of draws.	required
seed	int	Seed for reproducible draws; None (the default) seeds from the clock.	None

Returns

Name	Type	Description
	numpy.ndarray	n x 2.

tail_dependence

Copula.tail_dependence()

Lower and upper tail dependence coefficients.

Returns

Name	Type	Description
	dict	Keys "lower" and "upper".

to_json

Copula.to_json()

This copula’s spec as the JSON the shared C++ core parses.

Returns

Name	Type	Description
	str	The spec JSON.