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

# skfolio.distribution.GaussianCopula

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

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

Bivariate Gaussian Copula Estimation.

The bivariate Gaussian copula is defined as:

$$
C_{\rho}(u, v) = \Phi_2\left(\Phi^{-1}(u), \Phi^{-1}(v) ; \rho\right)

$$

where:
: - $\Phi_2$ is the bivariate normal CDF with correlation $\rho$.
  - $\Phi$ is the standard normal CDF and $\Phi^{-1}$ its quantile function.
  - $\rho \in (-1, 1)$ is the correlation coefficient.

#### NOTE
Rotations are not needed for elliptical copula (e.g., Gaussian or Student-t)
because its correlation parameter $\rho \in (-1, 1)$ naturally covers
both positive and negative dependence, and they exhibit symmetric tail behavior.

* **Parameters:**
  **itau** *bool, default=True*
  : If True, $\rho$ is estimated using the Kendall’s tau inversion method;
    otherwise, we use the MLE (Maximum Likelihood Estimation) method. 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:**
  **rho_** *float*
  : Fitted parameter ($\rho$) in [-1, 1].

### Methods

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

### References

* <a id='r1ac6c90fd463-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r1ac6c90fd463-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r1ac6c90fd463-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r1ac6c90fd463-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r1ac6c90fd463-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 GaussianCopula, 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 = GaussianCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
GaussianCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
GaussianCopula(rho=0.327)
>>> print(model.lower_tail_dependence)
0
>>> 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.GaussianCopula.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='r2388a775ea66-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.GaussianCopula.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='rfabb84626bba-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

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

#### cdf(X)

Compute the CDF of the bivariate Gaussian 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.GaussianCopula.fit"></a>

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

Fit the Bivariate Gaussian Copula.

If `itau` is True, estimates $\rho$ 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** *GaussianCopula*
  : Returns the instance itself.

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

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.GaussianCopula.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.GaussianCopula.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.GaussianCopula.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]](#r8bb0201ee017-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='r8bb0201ee017-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='r8bb0201ee017-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)

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

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

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

#### *property* n_params

Number of model parameters.

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

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

Compute the h-function (partial derivative) for the bivariate Gaussian
copula.

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} \\
&= \Phi\Bigl(\frac{\Phi^{-1}(u)-\rho\,\Phi^{-1}(v)}{\sqrt{1-\rho^2}}\Bigr)
\end{aligned}

$$

where $\Phi$ is the standard normal CDF and $\Phi^{-1}$ is its
inverse (the quantile function).

* **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.GaussianCopula.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.GaussianCopula.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.GaussianCopula.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='reacd953c84ec-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.GaussianCopula.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.GaussianCopula.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.GaussianCopula.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.GaussianCopula.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.GaussianCopula.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='r64a287356d1b-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

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

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.