copulas.bivariate package¶
Submodules¶
Module contents¶
Bivariate copulas.
-
class
copulas.bivariate.
Bivariate
(copula_type=None, random_state=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_state (Union[int, np.random.RandomState, None]) – Seed or RandomState for the random generator.
-
copula_type
¶ Family of the copula a subclass belongs to.
- Type
-
_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]
-
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]¶ Check that the marginals are 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 ininvalid_thetas
,
-
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_dict – dict 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
-
generator
(t)[source]¶ Compute the generator function for Archimedian copulas.
The generator is a function \(\psi: [0,1]\times\Theta \rightarrow [0, \infty)\) # noqa: JS101
that given an Archimedian copula fulfills: .. math:: 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)\]
-
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
-
log_probability_density
(X)[source]¶ Return log probability density of model.
The log probability should be overridden with numerically stable variants whenever possible.
- Parameters
X – np.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
y – np.ndarray value of \(C(u|v)\).
v – np.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:
Estimate the most likely parameter \(\theta\) of each copula candidate for the given dataset.
Construct \(R(z|\theta)\). Calculate the area under the tail for each of the copula candidates.
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).
Proceed as in steps 2- 3 with the lower tail and function \(L\).
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
-
set_random_state
(random_state)[source]¶ Set the random state.
- Parameters
random_state (int, np.random.RandomState, or None) – Seed or RandomState for the random generator.
-
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
= []
-
class
copulas.bivariate.
Clayton
(copula_type=None, random_state=None)[source]¶ Bases:
copulas.bivariate.base.Bivariate
Class for clayton copula model.
-
compute_theta
()[source]¶ Compute theta parameter using Kendall’s tau.
On Clayton copula this is
\[τ = θ/(θ + 2) \implies θ = 2τ/(1-τ)\]\[θ ∈ (0, ∞)\]On the corner case of \(τ = 1\), return infinite.
-
copula_type
= 0¶
-
cumulative_distribution
(X)[source]¶ Compute the cumulative distribution function for the clayton copula.
The cumulative density(cdf), or distribution function for the Clayton family of copulas correspond to the formula:
\[C(u,v) = (u^{-θ} + v^{-θ} - 1)^{-1/θ}\]- Parameters
X (numpy.ndarray) –
- Returns
cumulative probability.
- Return type
numpy.ndarray
-
generator
(t)[source]¶ Compute the generator function for Clayton copula family.
The generator is a function \(\psi: [0,1]\times\Theta \rightarrow [0, \infty)\) # noqa: JS101
that given an Archimedian copula fulfills: .. math:: C(u,v) = psi^{-1}(psi(u) + psi(v))
- Parameters
t (numpy.ndarray) –
- Returns
numpy.ndarray
-
invalid_thetas
= []¶
-
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} = u^{- \theta - 1}(u^{-\theta} + v^{-\theta} - 1)^{-\frac{\theta+1}{\theta}}\]- Parameters
X (np.ndarray) –
y (float) –
- Returns
Derivatives
- Return type
numpy.ndarray
-
percent_point
(y, V)[source]¶ Compute the inverse of conditional cumulative distribution \(C(u|v)^{-1}\).
- Parameters
y (numpy.ndarray) – Value of \(C(u|v)\).
v (numpy.ndarray) – given value of v.
-
probability_density
(X)[source]¶ Compute probability density function for given copula family.
The probability density(PDF) for the Clayton family of copulas correspond to the formula:
\[c(U,V) = \frac{\partial^2}{\partial v \partial u}C(u,v) = (\theta + 1)(uv)^{-\theta-1}(u^{-\theta} + v^{-\theta} - 1)^{-\frac{2\theta + 1}{\theta}}\]- Parameters
X (numpy.ndarray) –
- Returns
Probability density for the input values.
- Return type
numpy.ndarray
-
theta_interval
= [0, inf]¶
-
-
class
copulas.bivariate.
CopulaTypes
[source]¶ Bases:
enum.Enum
Available copula families.
-
CLAYTON
= 0¶
-
FRANK
= 1¶
-
GUMBEL
= 2¶
-
INDEPENDENCE
= 3¶
-
-
class
copulas.bivariate.
Frank
(copula_type=None, random_state=None)[source]¶ Bases:
copulas.bivariate.base.Bivariate
Class for Frank copula model.
-
compute_theta
()[source]¶ Compute theta parameter using Kendall’s tau.
On Frank copula, the relationship between tau and theta is defined by:
\[\tau = 1 − \frac{4}{\theta} + \frac{4}{\theta^2}\int_0^\theta \! \frac{t}{e^t -1} \mathrm{d}t.\]In order to solve it, we can simplify it as
\[0 = 1 + \frac{4}{\theta}(D_1(\theta) - 1) - \tau\]where the function D is the Debye function of first order, defined as:
\[D_1(x) = \frac{1}{x}\int_0^x\frac{t}{e^t -1} \mathrm{d}t.\]
-
copula_type
= 1¶
-
cumulative_distribution
(X)[source]¶ Compute the cumulative distribution function for the Frank copula.
The cumulative density(cdf), or distribution function for the Frank family of copulas correspond to the formula:
\[C(u,v) = −\frac{\ln({\frac{1 + g(u) g(v)}{g(1)}})}{\theta}\]- Parameters
X – np.ndarray
- Returns
cumulative distribution
- Return type
np.array
-
invalid_thetas
= [0]¶
-
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}{\partial u}C(u,v) = \frac{g(u)g(v) + g(v)}{g(u)g(v) + g(1)}\]- Parameters
X (np.ndarray) –
y (float) –
- Returns
np.ndarray
-
percent_point
(y, V)[source]¶ Compute the inverse of conditional cumulative distribution \(C(u|v)^{-1}\).
- Parameters
y – np.ndarray value of \(C(u|v)\).
v – np.ndarray given value of v.
-
probability_density
(X)[source]¶ Compute probability density function for given copula family.
The probability density(PDF) for the Frank family of copulas correspond to the formula:
\[c(U,V) = \frac{\partial^2 C(u,v)}{\partial v \partial u} = \frac{-\theta g(1)(1 + g(u + v))}{(g(u) g(v) + g(1)) ^ 2}\]Where the g function is defined by:
\[g(x) = e^{-\theta x} - 1\]- Parameters
X – np.ndarray
- Returns
probability density
- Return type
np.array
-
theta_interval
= [-inf, inf]¶
-
-
class
copulas.bivariate.
Gumbel
(copula_type=None, random_state=None)[source]¶ Bases:
copulas.bivariate.base.Bivariate
Class for clayton copula model.
-
compute_theta
()[source]¶ Compute theta parameter using Kendall’s tau.
On Gumbel copula \(\tau\) is defined as \(τ = \frac{θ−1}{θ}\) that we solve as \(θ = \frac{1}{1-τ}\)
-
copula_type
= 2¶
-
cumulative_distribution
(X)[source]¶ Compute the cumulative distribution function for the Gumbel copula.
The cumulative density(cdf), or distribution function for the Gumbel family of copulas correspond to the formula:
\[C(u,v) = e^{-((-\ln u)^{\theta} + (-\ln v)^{\theta})^{\frac{1}{\theta}}}\]- Parameters
X (np.ndarray) –
- Returns
cumulative probability for the given datapoints, cdf(X).
- Return type
np.ndarray
-
invalid_thetas
= []¶
-
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} = C(u,v)\frac{((-\ln u)^{\theta} + (-\ln v)^{\theta})^{\frac{1}{\theta} - 1}} {\theta(- \ln u)^{1 -\theta}}\]- Parameters
X (np.ndarray) –
y (float) –
- Returns
numpy.ndarray
-
percent_point
(y, V)[source]¶ Compute the inverse of conditional cumulative distribution \(C(u|v)^{-1}\).
- Parameters
y (np.ndarray) – value of \(C(u|v)\).
v (np.ndarray) – given value of v.
-
probability_density
(X)[source]¶ Compute probability density function for given copula family.
The probability density(PDF) for the Gumbel family of copulas correspond to the formula:
\[\begin{align} c(U,V) &= \frac{\partial^2 C(u,v)}{\partial v \partial u} &= \frac{C(u,v)}{uv} \frac{((-\ln u)^{\theta} # noqa: JS101 + (-\ln v)^{\theta})^{\frac{2} # noqa: JS101 {\theta} - 2 }}{(\ln u \ln v)^{1 - \theta}} # noqa: JS101 ( 1 + (\theta-1) \big((-\ln u)^\theta + (-\ln v)^\theta\big)^{-1/\theta}) \end{align}\]- Parameters
X (numpy.ndarray) –
- Returns
numpy.ndarray
-
theta_interval
= [1, inf]¶
-