# skfolio.distribution.BaseBivariateCopula ### *class* skfolio.distribution.BaseBivariateCopula(random_state=None) Base class for Bivariate Copula Estimators. This abstract class defines the interface for bivariate copula models, including methods for fitting, sampling, scoring, and computing partial derivatives. * **Parameters:** **random_state** *int, RandomState instance or None, default=None* : Seed or random state to ensure reproducibility. * **Attributes:** [`fitted_repr`](#skfolio.distribution.BaseBivariateCopula.fitted_repr) : String representation of the fitted copula. [`lower_tail_dependence`](#skfolio.distribution.BaseBivariateCopula.lower_tail_dependence) : Theoretical lower tail dependence coefficient. [`n_params`](#skfolio.distribution.BaseBivariateCopula.n_params) : Number of model parameters. [`upper_tail_dependence`](#skfolio.distribution.BaseBivariateCopula.upper_tail_dependence) : Theoretical upper tail dependence coefficient. ### Methods | [`aic`](#skfolio.distribution.BaseBivariateCopula.aic)(X) | Compute the Akaike Information Criterion (AIC) for the model given data X. | |------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`bic`](#skfolio.distribution.BaseBivariateCopula.bic)(X) | Compute the Bayesian Information Criterion (BIC) for the model given data X. | | [`cdf`](#skfolio.distribution.BaseBivariateCopula.cdf)(X) | Compute the CDF of the bivariate copula. | | [`fit`](#skfolio.distribution.BaseBivariateCopula.fit)(X[, y]) | Fit the copula model. | | [`get_metadata_routing`](#skfolio.distribution.BaseBivariateCopula.get_metadata_routing)() | Get metadata routing of this object. | | [`get_params`](#skfolio.distribution.BaseBivariateCopula.get_params)([deep]) | Get parameters for this estimator. | | [`inverse_partial_derivative`](#skfolio.distribution.BaseBivariateCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function [[1]](#rb4c56b3b5247-1). | | [`partial_derivative`](#skfolio.distribution.BaseBivariateCopula.partial_derivative)(X[, first_margin]) | Compute the h-function (partial derivative) for the bivariate copula with respect to a specified margin. | | [`plot_pdf_2d`](#skfolio.distribution.BaseBivariateCopula.plot_pdf_2d)([title]) | Plot a 2D contour of the estimated probability density function (PDF). | | [`plot_pdf_3d`](#skfolio.distribution.BaseBivariateCopula.plot_pdf_3d)([title]) | Plot a 3D surface of the estimated probability density function (PDF). | | [`plot_tail_concentration`](#skfolio.distribution.BaseBivariateCopula.plot_tail_concentration)([X, title]) | Plot the tail concentration function. | | [`sample`](#skfolio.distribution.BaseBivariateCopula.sample)([n_samples]) | Generate random samples from the bivariate copula using the inverse Rosenblatt transform. | | [`score`](#skfolio.distribution.BaseBivariateCopula.score)(X[, y]) | Compute the total log-likelihood under the model. | | [`score_samples`](#skfolio.distribution.BaseBivariateCopula.score_samples)(X) | Compute the log-likelihood of each sample (log-pdf) under the model. | | [`set_params`](#skfolio.distribution.BaseBivariateCopula.set_params)(\*\*params) | Set the parameters of this estimator. | | [`tail_concentration`](#skfolio.distribution.BaseBivariateCopula.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:** **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 * **[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:** **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 * **[1]** “Estimating the dimension of a model”, Schwarz, G. (1978). #### *abstractmethod* cdf(X) Compute the CDF of the bivariate 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. #### *abstractmethod* fit(X, y=None) Fit the copula 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. **y** *None* : Ignored. Provided for compatibility with scikit-learn’s API. * **Returns:** **self** *BaseBivariateCopula* : Returns the instance itself. #### *abstract property* fitted_repr String representation of the fitted copula. #### 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. #### 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. #### *abstractmethod* 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]](#rb4c56b3b5247-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 * **[1]** “Multivariate Models and Dependence Concepts”, Joe, H. (1997) * **[2]** “An Introduction to Copulas”, Nelsen, R. B. (2006) #### *abstract property* lower_tail_dependence Theoretical lower tail dependence coefficient. #### *property* n_params Number of model parameters. #### *abstractmethod* partial_derivative(X, first_margin=False) Compute the h-function (partial derivative) for the bivariate 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$: $$ h(u \mid v) = \frac{\partial C(u,v)}{\partial v} $$ * **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. #### 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. #### 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. #### 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 * **[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_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]`. #### 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). #### *abstractmethod* 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. #### 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 `__` so that it’s possible to update each component of a nested object. * **Parameters:** **\*\*params** *dict* : Estimator parameters. * **Returns:** **self** *estimator 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:** **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 * **[1]** “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005) #### *abstract property* upper_tail_dependence Theoretical upper tail dependence coefficient.