`skfolio.distribution`.StudentTCopula#

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

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:

itaubool, 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_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:

rho_float: Fitted correlation coefficient (\(\rho\)) in [-1, 1].
dof_float: Fitted degrees of freedom (\(\nu\)) > 2.

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 StudentTCopula, 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 = StudentTCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
StudentTCopula(rho=0.327, dof=5.14)
>>> print(model.lower_tail_dependence)
0.1270
>>> print(model.upper_tail_dependence)
0.1270
>>>
>>> # 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 Student-t copula.
`fit`(X[, y])	Fit the Bivariate Student's t 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 [1].
`partial_derivative`(X[, first_margin])	Compute the h-function (partial derivative) for the bivariate Student's t copula.
`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 Student-t copula.

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 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:

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:

selfStudentTCopula: 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 [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:

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 of length n_observations, where each element is the computed \(u = h^{-1}(p \mid v)\) for the corresponding pair in X.

References

[1] (1,2)

“Multivariate Models and Dependence Concepts”, Joe, H. (1997)

[2]

“An Introduction to Copulas”, Nelsen, R. B. (2006)

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 Student’s t copula.

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} \\ &= 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}\end{split}\]

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:

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) \;=\; p\) 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.

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.StudentTCopula#

`skfolio.distribution`.StudentTCopula#