copulas.bivariate.base module¶
This module contains a base class for bivariate copulas.
-
class
copulas.bivariate.base.Bivariate(copula_type=None, random_state=None)[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(*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= []