# copulas.bivariate.base module¶

This module contains a base class for bivariate copulas.

class copulas.bivariate.base.Bivariate(copula_type=None, random_seed=None)[source]

Bases: object

Base class for bivariate copulas.

This class allows to instantiate all its subclasses and serves as a unique entry point for the bivariate copulas classes.

>>> Bivariate(copula_type=CopulaTypes.FRANK).__class__
copulas.bivariate.frank.Frank

>>> Bivariate(copula_type='frank').__class__
copulas.bivariate.frank.Frank

Parameters
• copula_type (Union[CopulaType, str]) – Subtype of the copula.

• random_seed (Union[int, None]) – Seed for the random generator.

copula_type

Family of the copula a subclass belongs to.

Type

CopulaTypes

_subclasses

List of declared subclasses.

Type

list[type]

theta_interval

Interval of valid thetas for the given copula family.

Type

list[float]

invalid_thetas

Values that, even though they belong to theta_interval, shouldn’t be considered valid.

Type

list[float]

tau

Kendall’s tau for the data given at fit().

Type

float

theta

Parameter for the copula.

Type

float

cdf(X)[source]

Shortcut to cumulative_distribution().

check_fit()[source]

Assert that the model is fit and the computed theta is valid.

Raises
• NotFittedError – if the model is not fitted.

• ValueError – if the computed theta is invalid.

check_marginal(u)[source]

The marginals are supposed to be uniformly distributed.

Parameters

u (np.ndarray) – Array of datapoints with shape (n,).

Raises

ValueError – If the data does not appear uniformly distributed.

check_theta()[source]

Validate the computed theta against the copula specification.

This method is used to assert the computed theta is in the valid range for the copula.

Raises

ValueError – If theta is not in theta_interval or is in invalid_thetas,

compute_theta()[source]

Compute theta parameter using Kendall’s tau.

copula_type = None
cumulative_distribution(X)[source]

Compute the cumulative distribution function for the copula, $$C(u, v)$$.

Parameters

X (np.ndarray) –

Returns

cumulative probability

Return type

numpy.array

fit(X)[source]

Fit a model to the data updating the parameters.

Parameters

X (np.ndarray) – Array of datapoints with shape (n,2).

Returns

None

classmethod from_dict(copula_dict)[source]

Create a new instance from the given parameters.

Parameters

copula_dictdict with the parameters to replicate the copula. Like the output of Bivariate.to_dict

Returns

Instance of the copula defined on the parameters.

Return type

Bivariate

generator(t)[source]

Compute the generator function for Archimedian copulas.

The generator is a function $$\psi: [0,1]\times\Theta \rightarrow [0, \infty)$$ that given an Archimedian copula fulills:

$C(u,v) = \psi^{-1}(\psi(u) + \psi(v))$

In a more generic way:

$C(u_1, u_2, ..., u_n;\theta) = \psi^-1(\sum_0^n{\psi(u_i;\theta)}; \theta)$
infer(X)[source]

Take in subset of values and predicts the rest.

invalid_thetas = []
classmethod load(copula_path)[source]

Create a new instance from a file.

Parameters

copula_path (str) – Path to file with the serialized copula.

Returns

Instance with the parameters stored in the file.

Return type

Bivariate

log_probability_density(X)[source]

Return log probability density of model. It should be overridden with numerically stable variants whenever possible.

Parameters

Xnp.ndarray of shape (n, 1).

Returns

np.ndarray

partial_derivative(X)[source]

Compute partial derivative of cumulative distribution.

The partial derivative of the copula(CDF) is the conditional CDF.

$F(v|u) = \frac{\partial C(u,v)}{\partial u}$

The base class provides a finite difference approximation of the partial derivative of the CDF with respect to u.

Parameters
• X (np.ndarray) –

• y (float) –

Returns

np.ndarray

partial_derivative_scalar(U, V)[source]

Compute partial derivative $$C(u|v)$$ of cumulative density of single values.

pdf(X)[source]

Shortcut to probability_density().

percent_point(y, V)[source]

Compute the inverse of conditional cumulative distribution $$C(u|v)^{-1}$$.

Parameters
• ynp.ndarray value of $$C(u|v)$$.

• vnp.ndarray given value of v.

ppf(y, V)[source]

Shortcut to percent_point().

probability_density(X)[source]

Compute probability density function for given copula family.

The probability density(pdf) for a given copula is defined as:

$c(U,V) = \frac{\partial^2 C(u,v)}{\partial v \partial u}$
Parameters

X (np.ndarray) – Shape (n, 2).Datapoints to compute pdf.

Returns

Probability density for the input values.

Return type

np.array

sample(*args, **kwargs)
save(filename)[source]

Save the internal state of a copula in the specified filename.

Parameters

filename (str) – Path to save.

Returns

None

classmethod select_copula(X)[source]

Select best copula function based on likelihood.

Given out candidate copulas the procedure proposed for selecting the one that best fit to a dataset of pairs $$\{(u_j, v_j )\}, j=1,2,...n$$ , is as follows:

1. Estimate the most likely parameter $$\theta$$ of each copula candidate for the given dataset.

2. Construct $$R(z|\theta)$$. Calculate the area under the tail for each of the copula candidates.

3. Compare the areas: $$a_u$$ achieved using empirical copula against the ones achieved for the copula candidates. Score the outcome of the comparison from 3 (best) down to 1 (worst).

4. Proceed as in steps 2- 3 with the lower tail and function $$L$$.

5. Finally the sum of empirical upper and lower tail functions is compared against $$R + L$$. Scores of the three comparisons are summed and the candidate with the highest value is selected.

Parameters

X (np.ndarray) – Matrix of shape (n,2).

Returns

Best copula that fits for it.

Return type

copula

classmethod subclasses()[source]

Return a list of subclasses for the current class object.

Returns

Subclasses for given class.

Return type

list[Bivariate]

tau = None
theta = None
theta_interval = []
to_dict()[source]

Return a dict with the parameters to replicate this object.

Returns

Parameters of the copula.

Return type

dict

class copulas.bivariate.base.CopulaTypes[source]

Bases: enum.Enum

Available copula families.

CLAYTON = 0
FRANK = 1
GUMBEL = 2
INDEPENDENCE = 3