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

# skfolio.distribution.StudentTCopula

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

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

Bivariate Student’s t Copula Estimation.

The bivariate Student’s t copula density is defined as:

$$
C_{\nu, \rho}(u, v) = T_{\nu, \rho} \Bigl(t_{\nu}^{-1}(u),\;t_{\nu}^{-1}(v)\Bigr)

$$

where:
: - $\nu > 0$ is the degrees of freedom.
  - $\rho \in (-1, 1)$ is the correlation coefficient.
  - $T_{\nu, \rho}(x, y)$ is the CDF of the bivariate t-distribution.
  - $t_{\nu}^{-1}(p)$ is the quantile function (inverse CDF) of the
    univariate t-distribution.

Student’s t copula with degrees of freedom (dof) less than 2.0 is extremely
heavy-tailed, to the extent that even the mean (and many moments) do not exist,
rendering it impractical. Conversely, for dof above 50 the t copula behaves
similarly to a Gaussian copula. Thus, for improved stability and robustness,
the dof is limited to the interval [2, 50].

#### 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*
  : 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 correlation coefficient ($\rho$) in [-1, 1].

  **dof_** *float*
  : Fitted degrees of freedom ($\nu$) > 2.

### Methods

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

### References

* <a id='r77ea93c803cf-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r77ea93c803cf-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r77ea93c803cf-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r77ea93c803cf-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r77ea93c803cf-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 StudentTCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = StudentTCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
StudentTCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
StudentTCopula(rho=0.385, dof=4.90)
>>> print(model.lower_tail_dependence)
0.157...
>>> print(model.upper_tail_dependence)
0.157...
>>>
>>> # 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.StudentTCopula.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='r85028b203ba8-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

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

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

#### cdf(X)

Compute the CDF of the bivariate Student-t 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.StudentTCopula.fit"></a>

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

Fit the Bivariate Student’s t Copula.

If `itau` is True, it uses a Kendall-based two-step method:
: - Estimates the correlation parameter ($\rho$) from Kendall’s
    tau inversion.
  - Optimizes the degrees of freedom ($\nu$) by maximizing the
    log-likelihood.

Otherwise, it uses the full MLE method: optimizes both $\rho$ and
$\nu$ 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** *StudentTCopula*
  : Returns the instance itself.

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

#### *property* fitted_repr

String representation of the fitted copula.

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

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

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

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

#### *property* n_params

Number of model parameters.

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

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

Compute the h-function (partial derivative) for the bivariate Student’s t
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} \\
             &= t_{\nu+1}\!\left(\frac{t_\nu^{-1}(u) - \rho\,t_\nu^{-1}(v)}
                {\sqrt{\frac{(1-\rho^2)\left(\nu + \left(t_\nu^{-1}(v)\right)^2\right)}{\nu+1}}}\right).
\end{aligned}

$$

where:
: - $\nu > 0$ is the degrees of freedom.
  - $\rho \in (-1, 1)$ is the correlation coefficient.
  - $t_{\nu}^{-1}(p)$ is the quantile function (inverse CDF) of the
    univariate (t)-distribution.

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

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

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

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.