<a id="skfolio-distribution-joecopula"></a>

# skfolio.distribution.JoeCopula

<a id="skfolio.distribution.JoeCopula"></a>

### *class* skfolio.distribution.JoeCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Joe Copula Estimation.

The Joe 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.

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

It is defined by:

$$
C_{\theta}(u, v) = 1-\Bigl[(1 - u)^{\theta} + (1 - v)^{\theta} -
    (1 - u)^{\theta} (1 - v)^{\theta}\Bigr]^{\frac{1}{\theta}}

$$

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

#### NOTE
Rotation are needed for archimedean copulas (e.g., Joe, Gumbel, Clayton)
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:**
  **itau** *bool, 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_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this value is used;
    otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, 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.

### Methods

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

### References

* <a id='r86860317e993-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r86860317e993-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r86860317e993-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r86860317e993-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r86860317e993-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import JoeCopula, 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 = JoeCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
JoeCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
JoeCopula(theta=1.48, rot=180°)
>>> print(model.lower_tail_dependence)
0.402...
>>> print(model.upper_tail_dependence)
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()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.JoeCopula.aic"></a>

#### 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:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : 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

* <a id='ra3d6a7c9ca96-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.JoeCopula.bic"></a>

#### 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:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : 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

* <a id='r7ba13b427350-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.JoeCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Joe copula.

* **Parameters:**
  **X** *array-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:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.JoeCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Joe Copula.

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

* **Parameters:**
  **X** *array-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.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *object*
  : Returns the instance itself.

<a id="skfolio.distribution.JoeCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.JoeCopula.get_metadata_routing"></a>

#### get_metadata_routing()

Get metadata routing of this object.

Please check [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

* **Returns:**
  **routing** *MetadataRequest*
  : A `MetadataRequest` encapsulating
    routing information.

<a id="skfolio.distribution.JoeCopula.get_params"></a>

#### get_params(deep=True)

Get parameters for this estimator.

* **Parameters:**
  **deep** *bool, default=True*
  : If True, will return the parameters for this estimator and
    contained subobjects that are estimators.
* **Returns:**
  **params** *dict*
  : Parameter names mapped to their values.

<a id="skfolio.distribution.JoeCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function [[1]](#rf0ec9f4ea0c3-1).

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:**
  **X** *array-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_margin** *bool, 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:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

### References

* <a id='rf0ec9f4ea0c3-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='rf0ec9f4ea0c3-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)
* <a id='rf0ec9f4ea0c3-3'>**[3]**</a> . “Nested Archimedean Copulas Meet “, Hofert & Mächler (2011)

<a id="skfolio.distribution.JoeCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.JoeCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.JoeCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Joe 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{aligned}
h(u \mid v)
  &= \frac{\partial C(u,v)}{\partial v} \\[6pt]
  &= (1-v)^{\theta-1}\,\Bigl[1 \;-\;(1-u)^{\theta}\Bigr]\,
     \Bigl[(1-u)^{\theta} \;+\;(1-v)^{\theta}
           \;-\;(1-u)^{\theta}(1-v)^{\theta}\Bigr]^{\frac{1}{\theta}-1} \\[6pt]
  &= \left( 1 \;+\;\frac{(1-u)^{\theta}}{(1-v)^{\theta}}
           \;-\;(1-u)^{\theta} \right)^{-1 + \frac{1}{\theta}}
     \;\cdot\;\bigl[\,1 \;-\;(1-u)^{\theta}\bigr].
\end{aligned}

$$

* **Parameters:**
  **X** *array-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_margin** *bool, 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:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v) \;=\; p$ for each observation in X.

<a id="skfolio.distribution.JoeCopula.plot_pdf_2d"></a>

#### 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:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.JoeCopula.plot_pdf_3d"></a>

#### 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:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.JoeCopula.plot_tail_concentration"></a>

#### 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:**
  **X** *array-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.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='r36592470e977-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.JoeCopula.sample"></a>

#### sample(n_samples=1)

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

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-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]`.

<a id="skfolio.distribution.JoeCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.JoeCopula.score_samples"></a>

#### score_samples(X)

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

* **Parameters:**
  **X** *array-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:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.JoeCopula.set_params"></a>

#### 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:**
  **\*\*params** *dict*
  : Estimator parameters.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.distribution.JoeCopula.tail_concentration"></a>

#### 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:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray 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

* <a id='rd013f05b5432-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.JoeCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.