copulas.bivariate.base module
This module contains a base class for bivariate copulas.
- class copulas.bivariate.base.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 = []