`skfolio.distribution`.GumbelCopula#

class skfolio.distribution.GumbelCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)[source]#

Bivariate Gumbel Copula Estimation.

The Gumbel copula is an Archimedean copula characterized by strong upper tail dependence and little to no lower tail dependence.

In its unrotated form, it is used for modeling extreme co-movements in the upper tail (i.e. simultaneous extreme gains).

Rotations allow the copula to be adapted for different types of tail dependence:

A 180° rotation captures extreme co-movements in the lower tail (i.e. simultaneous extreme losses).
A 90° rotation captures scenarios where one variable exhibits extreme losses while the other shows extreme gains.
A 270° rotation captures the opposite scenario, where one variable experiences extreme gains while the other suffers extreme losses.

Gumbel copula generally exhibits weaker upper tail dependence than the Joe copula.

It is defined by:

\[C_{\theta}(u, v) = \exp\Bigl(-\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{1/\theta}\Bigr)\]

where \(\theta \ge 1\) is the dependence parameter. When \(\theta = 1\), the Gumbel copula reduces to the independence copula. Larger values of \(\theta\) result in stronger upper-tail dependence.

Note

Rotations are needed for Archimedean copulas (e.g., Joe, Gumbel, Gumbel) because their parameters only model positive dependence, and they exhibit asymmetric tail behavior. To model negative dependence, one uses rotations to “flip” the copula’s tail dependence.

Parameters:

itaubool, default=True: If True, \(\theta\) is estimated using the Kendall’s tau inversion method; otherwise, the Maximum Likelihood Estimation (MLE) method is used. The MLE is slower but more accurate.
kendall_taufloat, optional: If itau is True and kendall_tau is provided, this value is used; otherwise, it is computed.
tolerancefloat, default=1e-4: Convergence tolerance for the MLE optimization.
random_stateint, RandomState instance or None, default=None: Seed or random state to ensure reproducibility.

Attributes:

theta_float: Fitted theta coefficient \(\theta\) > 1.
rotation_CopulaRotation: Fitted rotation of the copula.

References

[1]

“An Introduction to Copulas (2nd ed.)”, Nelsen (2006)

[2]

“Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)

[3]

“Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)

[4]

“The t Copula and Related Copulas”, Demarta & McNeil (2005)

[5]

“Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

Examples

>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import GumbelCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = GumbelCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
GumbelCopula(theta=1.27, rot=180°)
>>> print(model.lower_tail_dependence)
0.2735
>>> print(model.upper_tail_dependence)
0.0
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>> fig.show()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>> fig.show()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
>>> fig.show()

Methods

`aic`(X)	Compute the Akaike Information Criterion (AIC) for the model given data X.
`bic`(X)	Compute the Bayesian Information Criterion (BIC) for the model given data X.
`cdf`(X)	Compute the CDF of the bivariate Gumbel copula.
`fit`(X[, y])	Fit the Bivariate Gumbel Copula.
`get_metadata_routing`()	Get metadata routing of this object.
`get_params`([deep])	Get parameters for this estimator.
`inverse_partial_derivative`(X[, first_margin])	Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function.
`partial_derivative`(X[, first_margin])	Compute the h-function (partial derivative) for the bivariate Gumbel copula with respect to a specified margin.
`plot_pdf_2d`([title])	Plot a 2D contour of the estimated probability density function (PDF).
`plot_pdf_3d`([title])	Plot a 3D surface of the estimated probability density function (PDF).
`plot_tail_concentration`([X, title])	Plot the tail concentration function.
`sample`([n_samples])	Generate random samples from the bivariate copula using the inverse Rosenblatt transform.
`score`(X[, y])	Compute the total log-likelihood under the model.
`score_samples`(X)	Compute the log-likelihood of each sample (log-pdf) under the model.
`set_params`(**params)	Set the parameters of this estimator.
`tail_concentration`(quantiles)	Compute the tail concentration function for a set of quantiles.

aic(X)#

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

\[\mathrm{AIC} = -2 \, \log L \;+\; 2 k,\]

where

\(\log L\) is the total log-likelihood
\(k\) is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

Parameters:

Xarray-like of shape (n_observations, n_features): The input data on which to compute the AIC.

Returns:

aicfloat: The AIC of the fitted model on the given data.

Notes

In practice, both AIC and BIC measure the trade-off between model fit and complexity, but BIC tends to prefer simpler models for large \(n\) because of the \(\ln(n)\) term.

References

[1]

“A new look at the statistical model identification”, Akaike (1974).

bic(X)#

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

\[\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),\]

where

\(\log L\) is the (maximized) total log-likelihood
\(k\) is the number of parameters in the model
\(n\) is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty for model complexity than the AIC.

Parameters:

Xarray-like of shape (n_observations, n_features): The input data on which to compute the BIC.

Returns:

bicfloat: The BIC of the fitted model on the given data.

Notes

In practice, both AIC and BIC measure the trade-off between model fit and complexity, but BIC tends to prefer simpler models for large \(n\) because of the \(\ln(n)\) term.

References

[1]

“Estimating the dimension of a model”, Schwarz, G. (1978).

cdf(X)[source]#

Compute the CDF of the bivariate Gumbel copula.

\[C(u,v) = \exp\Bigl(-\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{1/\theta}\Bigr).\]

Parameters:

Xarray-like of shape (n_observations, 2): An array of bivariate inputs (u, v) where each row represents a bivariate observation. Both u and v must be in the interval [0, 1], having been transformed to uniform marginals.

Returns:

cdfndarray of shape (n_observations,): CDF values for each observation in X.

fit(X, y=None)[source]#

Fit the Bivariate Gumbel Copula.

If itau is True, estimates \(\theta\) using Kendall’s tau inversion. Otherwise, uses MLE by maximizing the log-likelihood.

Parameters:

Xarray-like of shape (n_observations, 2): An array of bivariate inputs (u, v) where each row represents a bivariate observation. Both u and v must be in the interval [0, 1], having been transformed to uniform marginals.
yNone: Ignored. Provided for compatibility with scikit-learn’s API.

Returns:

selfobject: Returns the instance itself.

property fitted_repr#: String representation of the fitted copula.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

inverse_partial_derivative(X, first_margin=False)[source]#

Compute the inverse of the bivariate copula’s partial derivative, commonly known as the inverse h-function.

Let \(C(u, v)\) be a bivariate copula. The h-function with respect to the second margin is defined by

\[h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},\]

which is the conditional distribution of \(U\) given \(V = v\). The inverse h-function, denoted \(h^{-1}(p \mid v)\), is the unique value \(u \in [0,1]\) such that

\[h(u \mid v) \;=\; p, \quad \text{where } p \in [0,1].\]

In practical terms, given \((p, v)\) in \([0, 1]^2\), \(h^{-1}(p \mid v)\) solves for the \(u\) satisfying \(p = \partial C(u, v)/\partial v\).

Parameters:

Xarray-like of shape (n_observations, 2): An array of bivariate inputs (p, v), each in the interval [0, 1]. - The first column p corresponds to the value of the h-function. - The second column v is the conditioning variable.
first_marginbool, default=False: If True, compute the inverse partial derivative with respect to the first margin u; otherwise, compute the inverse partial derivative with respect to the second margin v.

Returns:

undarray of shape (n_observations,): A 1D-array where each element is the computed \(u = h^{-1}(p \mid v)\) for the corresponding pair in X.

property lower_tail_dependence#: Theoretical lower tail dependence coefficient.

property n_params#: Number of model parameters.

partial_derivative(X, first_margin=False)[source]#

Compute the h-function (partial derivative) for the bivariate Gumbel copula with respect to a specified margin.

The h-function with respect to the second margin represents the conditional distribution function of \(u\) given \(v\):

\[\begin{split}\begin{aligned} h(u \mid v) &= \frac{\partial C(u,v)}{\partial v}\\[6pt] &= C(u,v)\,\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{\frac{1}{\theta}-1} \,(-\ln v)^{\theta-1}\,\frac{1}{v}. \end{aligned}\end{split}\]

Parameters:

Xarray-like of shape (n_observations, 2): An array of bivariate inputs (u, v) where each row represents a bivariate observation. Both u and v must be in the interval [0, 1], having been transformed to uniform marginals.
first_marginbool, default=False: If True, compute the partial derivative with respect to the first margin u; otherwise, compute the partial derivative with respect to the second margin v.

Returns:

pndarray of shape (n_observations,): h-function values \(h(u \mid v)\) for each observation in X.

plot_pdf_2d(title=None)#

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a contour plot of the PDF. Contour levels are limited to the 97th quantile to avoid extreme densities.

Parameters:

titlestr, optional: The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.

Returns:

figgo.Figure: A Plotly figure object containing the 2D contour plot of the PDF.

plot_pdf_3d(title=None)#

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a 3D surface plot of the PDF using Plotly.

Parameters:

titlestr, optional: The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.

Returns:

figgo.Figure: A Plotly figure object containing a 3D surface plot of the PDF.

plot_tail_concentration(X=None, title=None)#

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced quantile levels between 0.005 and 0.995. The plot displays the concentration values on the y-axis and the quantile levels on the x-axis.

The tail concentration is defined as:

Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables, respectively.

Parameters:

Xarray-like of shape (n_samples, 2), optional: If provided, it is used to plot the empirical tail concentration for comparison versus the model tail concentration.
titlestr, optional: The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.

Returns:

figgo.Figure: A Plotly figure object containing the tail concentration curve.

References

[1]

“Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

sample(n_samples=1)#

Generate random samples from the bivariate copula using the inverse Rosenblatt transform.

Parameters:

n_samplesint, default=1: Number of samples to generate.

Returns:

Xarray-like of shape (n_samples, 2): An array of bivariate inputs (u, v) where each row represents a bivariate observation. Both u and v are uniform marginals in the interval [0, 1].

score(X, y=None)#

Compute the total log-likelihood under the model.

Parameters:

Xarray-like of shape (n_observations, n_features): An array of data points for which the total log-likelihood is computed.
yNone: Ignored. Provided for compatibility with scikit-learn’s API.

Returns:

logprobfloat: The total log-likelihood (sum of log-pdf values).

score_samples(X)[source]#

Compute the log-likelihood of each sample (log-pdf) under the model.

For Gumbel, the PDF is given by:

\[c(u,v) = \exp\Bigl(-\Bigl((-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr)^{1/\theta}\Bigr) \cdot \left[\Bigl((-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr)^{1/\theta-1} \left\{ \frac{(-\ln u)^{\theta}}{u}+\frac{(-\ln v)^{\theta}}{v}\right\}\right].\]

Parameters:

Xarray-like of shape (n_observations, 2): An array of bivariate inputs (u, v) where each row represents a bivariate observation. Both u and v must be in the interval [0, 1], having been transformed to uniform marginals.

Returns:

densityndarray of shape (n_observations,): The log-likelihood of each sample under the fitted copula.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

tail_concentration(quantiles)#

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:

For quantiles q ≤ 0.5:
C(q) = P(U ≤ q, V ≤ q) / q
For quantiles q > 0.5:
C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables, respectively. This function returns the concentration values for each q provided.

Parameters:

quantilesndarray of shape (n_quantiles,): A 1D array of quantile levels (values between 0 and 1) at which to compute the tail concentration.

Returns:

concentrationndarray of shape (n_quantiles,): The computed tail concentration values corresponding to each quantile.

Raises:

ValueError: If any value in quantiles is not in the interval [0, 1].

References

[1]

“Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

property upper_tail_dependence#: Theoretical upper tail dependence coefficient.

skfolio.distribution.GumbelCopula#

`skfolio.distribution`.GumbelCopula#