copulas.bivariate package
Submodules
- copulas.bivariate.base module
BivariateBivariate.copula_typeBivariate._subclassesBivariate.theta_intervalBivariate.invalid_thetasBivariate.tauBivariate.thetaBivariate.cdf()Bivariate.check_fit()Bivariate.check_marginal()Bivariate.check_theta()Bivariate.compute_theta()Bivariate.copula_typeBivariate.cumulative_distribution()Bivariate.fit()Bivariate.from_dict()Bivariate.generator()Bivariate.infer()Bivariate.invalid_thetasBivariate.load()Bivariate.log_probability_density()Bivariate.partial_derivative()Bivariate.partial_derivative_scalar()Bivariate.pdf()Bivariate.percent_point()Bivariate.ppf()Bivariate.probability_density()Bivariate.sample()Bivariate.save()Bivariate.select_copula()Bivariate.set_random_state()Bivariate.subclasses()Bivariate.tauBivariate.thetaBivariate.theta_intervalBivariate.to_dict()
CopulaTypes
- copulas.bivariate.clayton module
- copulas.bivariate.frank module
- copulas.bivariate.gumbel module
- copulas.bivariate.independence module
- copulas.bivariate.utils module
Module contents
Bivariate copulas.
- class copulas.bivariate.Bivariate(*args, **kwargs)[source]
Bases:
objectBase 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_intervalor 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(n_samples)[source]
Generate specified n_samples of new data from model.
The sampled are generated using the inverse transform method v~U[0,1],v~C^-1(u|v)
- Parameters:
n_samples (int) – amount of samples to create.
- Returns:
Array of length n_samples with generated data from the model.
- Return type:
np.ndarray
- 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(*args, **kwargs)[source]
Bases:
BivariateClass 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(*values)[source]
Bases:
EnumAvailable copula families.
- CLAYTON = 0
- FRANK = 1
- GUMBEL = 2
- INDEPENDENCE = 3
- class copulas.bivariate.Frank(*args, **kwargs)[source]
Bases:
BivariateClass 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(*args, **kwargs)[source]
Bases:
BivariateClass 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]