vinecopulib::Bicop class
#include <vinecopulib/include/vinecopulib/bicop/class.hpp>

A class for bivariate copula models.

The model is fully characterized by the family, rotation (one of 0, 90, 180, 270), a matrix of parameters, and variable types (two strings, one for each variable, either "c" for continuous or "d" for discrete).

Implemented families (see BicopFamily):

| type          | full name             | string identifier     |
|---------------|-----------------------|-----------------------|
| -             | Independence          | "indep"               |
| Elliptical    | Gaussian              | "gaussian"            |
|               | Student t             | "student"             |
| Archimedean   | Clayton               | "clayton"             |
|               | Gumbel                | "gumbel"              |
|               | Frank                 | "frank"               |
|               | Joe                   | "joe"                 |
|               | Clayton-Gumbel (BB1)  | "bb1"                 |
|               | Joe-Gumbel (BB6)      | "bb6"                 |
|               | Joe-Clayton (BB7)     | "bb7"                 |
|               | Joe-Frank (BB8)       | "bb8"                 |
| Extreme-Value | Tawn                  | "tawn"                |
| Nonparametric | Transformation kernel | "tll"                 |

Public types

struct ScoresResult
Bundles the per-observation scores.

Constructors, destructors, conversion operators

Bicop(const BicopFamily family = BicopFamily::indep, const int rotation = 0, const Eigen::MatrixXd& parameters = Eigen::MatrixXd(), const std::vector<std::string>& var_types = { "c", "c" })
Instantiates a specific bivariate copula model.
Bicop(const Eigen::MatrixXd& u, const FitControlsBicop& controls = FitControlsBicop(), const std::vector<std::string>& var_types = { "c", "c" }) explicit
Instantiates from data.
Bicop(const Bicop& other)
Copy constructor (deep copy)
Bicop(Bicop&& other) defaulted
Bicop(const std::string& filename) explicit
Instantiates from a JSON or CBOR file.
Bicop(const nlohmann::json& input) explicit
Instantiates from a nlohmann::json object.

Public functions

auto operator=(Bicop other) -> Bicop&
Copy assignment operator (deep copy)
auto to_json() const -> nlohmann::json
Convert the copula into a nlohmann::json object.
auto to_file(const std::string& filename) const -> void
Writes the copula object into a JSON or CBOR file.
auto get_npars() const -> double
The number of parameters of the copula model.
auto simulate(const size_t& n, const bool qrng = false, const std::vector<int>& seeds = std::vector<int>()) const -> Eigen::MatrixXd
Simulates from a bivariate copula.
auto simulate(const Eigen::MatrixXd& parameters, const bool qrng = false, const std::vector<int>& seeds = std::vector<int>(), const size_t num_threads = 1) const -> Eigen::MatrixXd
Simulates from a bivariate copula with per-row parameters.
auto fit(const Eigen::MatrixXd& u, const FitControlsBicop& controls = FitControlsBicop()) -> void
Fits a bivariate copula (with fixed family) to data.
auto select(const Eigen::MatrixXd& u, FitControlsBicop controls = FitControlsBicop()) -> void
Selects the best fitting model.
auto loglik(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const -> double
Evaluates the log-likelihood.
auto aic(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const -> double
Evaluates the Akaike information criterion (AIC).
auto bic(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const -> double
Evaluates the Bayesian information criterion (BIC).
auto mbic(const Eigen::MatrixXd& u = Eigen::MatrixXd(), const double psi0 = 0.9) const -> double
Evaluates the modified Bayesian information criterion (mBIC).
auto parameters_to_tau(const Eigen::MatrixXd& parameters) const -> double
Converts the copula parameters to Kendall's $ \tau $ .
auto parameters_to_taildep(const Eigen::MatrixXd& parameters) const -> Eigen::MatrixXd
Converts the copula parameters to the tail dependence coefficients.
auto parameters_to_beta(const Eigen::MatrixXd& parameters) const -> double
Converts the copula parameters to Blomqvist's $ \beta $ .
auto tau_to_parameters(const double& tau) const -> Eigen::MatrixXd
Converts a Kendall's $ \tau $ into copula parameters for one-parameter families.
auto with_var_types(const std::vector<std::string>& var_types = { "c", "c" }) const -> Bicop
The same copula under different variable types.

Getters and setters

auto get_family() const -> BicopFamily
Gets the copula family.
auto get_family_name() const -> std::string
Gets the copula family as a string.
auto get_rotation() const -> int
Gets the rotation.
auto get_parameters() const -> Eigen::MatrixXd
Gets the parameters.
auto get_tau() const -> double
Gets the Kendall's tau.
auto get_taildep() const -> Eigen::MatrixXd
Gets the tail dependence coefficients.
auto get_beta() const -> double
Gets Blomqvist's beta.
auto get_loglik() const -> double
Gets the log-likelihood (only for fitted objects).
auto get_nobs() const -> size_t
Gets the number of observations (only for fitted objects).
auto get_aic() const -> double
Gets the aic (only for fitted objects).
auto get_bic() const -> double
Gets the bic (only for fitted objects).
auto get_mbic(const double psi0 = 0.9) const -> double
Gets the modified bic (only for fitted objects).
auto set_rotation(const int rotation) -> void
Sets the rotation.
auto set_parameters(const Eigen::MatrixXd& parameters) -> void
auto set_var_types(const std::vector<std::string>& var_types = { "c", "c" }) -> void
Sets variable types.
auto get_var_types() const -> std::vector<std::string>
Gets variable types.

Stats methods

These evaluate the copula at the object's stored parameters. See below for the overloads taking one parameter set per row.

auto pdf(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the copula density.
auto cdf(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the copula distribution.
auto hfunc1(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the first h-function.
auto hfunc2(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the second h-function.
auto hinv1(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the inverse of the first h-function.
auto hinv2(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the inverse of the second h-function.

Stats methods with per-row parameters

These overloads evaluate the copula at a different parameter set per row of u, in a single call, without mutating the object's stored parameters. The family, rotation, and variable types are taken from the object; only the parameter values vary by row. They are available for parametric families only (nonparametric families store an interpolation grid rather than a per-observation parameter vector).

Common arguments:

  • u: an $ n \times 2 $ matrix for a continuous model. For a model with k discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
  • parameters: an $ n \times p $ matrix, where p is the number of family parameters (get_parameters().size()) and row i holds the parameter set used for row i of u. Parameters are given in the family's natural (unrotated) parameterization, as for get_parameters().
  • num_threads: the number of threads to parallelize over rows.
auto pdf(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the copula density with per-row parameters.
auto cdf(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the copula distribution with per-row parameters.
auto hfunc1(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the first h-function with per-row parameters.
auto hfunc2(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the second h-function with per-row parameters.
auto hinv1(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the inverse of the first h-function with per-row parameters.
auto hinv2(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the inverse of the second h-function with per-row parameters.
auto loglik(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> double
Evaluates the log-likelihood contributions with per-row parameters and returns their sum (NaNs are ignored).

Derivatives of the density and h-functions

These methods evaluate partial derivatives of the copula density $ c(u_1, u_2; \theta) $ , its logarithm, and the h-functions with respect to the parameters and/or the arguments. The derivative is chosen by the selector deriv, a concatenation of the components "par1", "par2", ... (the k-th parameter, in the family's natural parameterization as returned by get_parameters()), "u1", and "u2". First-order methods take one component ("par" is short for "par1"); second-order methods take two in any order (a single component means differentiating twice, so "par" is short for "par1par1").

Rotations are handled internally via the chain rule, so derivatives are always w.r.t. the arguments and (positive, natural) parameters of the rotated copula. Closed-form expressions are used for the families in bicop_families::analytic_derivs; other parametric families fall back to central finite differences of the corresponding function. Derivatives require continuous variable types; nonparametric families throw.

The per-row-parameter overloads evaluate the derivative at a different parameter set per row of u (see the corresponding pdf() overload for the layout and validation rules).

Common arguments: u is an $ n \times 2 $ matrix of observations in $ (0, 1)^2 $ and deriv selects the derivative; each method returns a length-n vector evaluated at u.

auto pdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a first derivative of the copula density.
auto pdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a second derivative of the copula density.
auto hfunc1_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a first derivative of the first h-function $ h_1(u_1, u_2) = P(U_2 \le u_2 | U_1 = u_1) $ .
auto hfunc1_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a second derivative of the first h-function.
auto hfunc2_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a first derivative of the second h-function $ h_2(u_1, u_2) = P(U_1 \le u_1 | U_2 = u_2) $ .
auto hfunc2_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a second derivative of the second h-function.
auto logpdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a first derivative of the log-density $ \partial \log c / \partial \cdot $ .
auto logpdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const -> Eigen::VectorXd
Evaluates a second derivative of the log-density.
auto pdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a first derivative of the copula density with per-row parameters.
auto pdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a second derivative of the copula density with per-row parameters.
auto hfunc1_deriv(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a first derivative of the first h-function with per-row parameters.
auto hfunc1_deriv2(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a second derivative of the first h-function with per-row parameters.
auto hfunc2_deriv(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a first derivative of the second h-function with per-row parameters.
auto hfunc2_deriv2(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a second derivative of the second h-function with per-row parameters.
auto logpdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a first derivative of the log-density with per-row parameters.
auto logpdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates a second derivative of the log-density with per-row parameters.

Scores, gradient, and Hessian of the log-likelihood

These methods aggregate the log-density parameter derivatives into the score (the gradient of each observation's log-density contribution), its observation-average (gradient), and the Hessian. They are thin wrappers around logpdf_deriv() / logpdf_deriv2(): with p = get_parameters() parameters, the score of observation i w.r.t. parameter k is $ \partial \log c(u_i; \theta) / \partial \theta_k $ , and the (per-obs and averaged) Hessians collect the second log-density derivatives. Like the derivatives they build on, they require parametric families and continuous variable types; nonparametric or discrete models throw.

The per-row-parameter overloads evaluate at a different parameter set per row of u (see the corresponding pdf() overload for the layout and validation rules).

In every method here, u is an $ n \times 2 $ matrix of observations in $ (0, 1)^2 $ .

auto scores(const Eigen::MatrixXd& u) const -> Eigen::MatrixXd
Evaluates the per-observation scores.
auto gradient(const Eigen::MatrixXd& u) const -> Eigen::VectorXd
Evaluates the gradient of the average log-likelihood.
auto hessian(const Eigen::MatrixXd& u) const -> Eigen::MatrixXd
Evaluates the Hessian of the average log-likelihood.
auto hessian_full(const Eigen::MatrixXd& u) const -> std::vector<Eigen::MatrixXd>
Evaluates the per-observation Hessians.
auto scores_cov(const Eigen::MatrixXd& u) const -> Eigen::MatrixXd
Computes the covariance matrix of the scores.
auto scores_full(const Eigen::MatrixXd& u) const -> ScoresResult
Evaluates the scores, bundled in a ScoresResult.
auto scores(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::MatrixXd
Evaluates the per-observation scores with per-row parameters.
auto gradient(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::VectorXd
Evaluates the gradient of the average log-likelihood with per-row parameters.
auto hessian(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::MatrixXd
Evaluates the Hessian of the average log-likelihood with per-row parameters.
auto hessian_full(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> std::vector<Eigen::MatrixXd>
Evaluates the per-observation Hessians with per-row parameters.
auto scores_cov(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> Eigen::MatrixXd
Computes the covariance matrix of the scores with per-row parameters.
auto scores_full(const Eigen::MatrixXd& u, const Eigen::MatrixXd& parameters, const size_t num_threads = 1) const -> ScoresResult
Evaluates the scores with per-row parameters, bundled in a ScoresResult.

Utilities

useful functions for bivariate copulas

auto str() const -> std::string
Summarizes the model into a string (can be used for printing).
auto flip() -> void
Adjusts the copula model to a change in the variable order.
auto get_parameters_lower_bounds() const -> Eigen::MatrixXd
Gets lower bounds for copula parameters.
auto get_parameters_upper_bounds() const -> Eigen::MatrixXd
Gets upper bounds for copula parameters.

Function documentation

vinecopulib::Bicop::Bicop(const BicopFamily family = BicopFamily::indep, const int rotation = 0, const Eigen::MatrixXd& parameters = Eigen::MatrixXd(), const std::vector<std::string>& var_types = { "c", "c" })

Instantiates a specific bivariate copula model.

Parameters
family The copula family.
rotation The rotation of the copula; one of 0, 90, 180, or 270 (for Independence, Gaussian, Student, Frank, and nonparametric families, only 0 is allowed).
parameters The copula parameters.
var_types Two strings specifying the types of the variables, e.g., ("c", "d") means first variable continuous, second discrete.

vinecopulib::Bicop::Bicop(const Eigen::MatrixXd& u, const FitControlsBicop& controls = FitControlsBicop(), const std::vector<std::string>& var_types = { "c", "c" }) explicit

Instantiates from data.

Parameters
u See Bicop::select().
controls See Bicop::select().
var_types Two strings specifying the types of the variables, e.g., ("c", "d") means first variable continuous, second discrete.

Equivalent to creating a default Bicop() and then selecting the model using Bicop::select().

vinecopulib::Bicop::Bicop(const Bicop& other)

Copy constructor (deep copy)

Parameters
other Bicop object to copy.

vinecopulib::Bicop::Bicop(const std::string& filename) explicit

Instantiates from a JSON or CBOR file.

Parameters
filename The name of the file to read.

Files ending in .cbor are read as CBOR. All other filenames are read as JSON for backwards compatibility. The input contains four attributes: "fam", "rot", "par", "vt" respectively a string for the family name, an integer for the rotation, and a numeric matrix for the parameters, and a list of two strings for the variable types.

vinecopulib::Bicop::Bicop(const nlohmann::json& input) explicit

Instantiates from a nlohmann::json object.

Parameters
input The nlohmann::json object to convert from (see to_json() for the structure of the input).

Bicop& vinecopulib::Bicop::operator=(Bicop other)

Copy assignment operator (deep copy)

Parameters
other Bicop object to copy.

nlohmann::json vinecopulib::Bicop::to_json() const

Convert the copula into a nlohmann::json object.

Returns The nlohmann::json object containing the copula.

The nlohmann::json is contains of three values named "fam", "rot", "par", "vt", respectively a string for the family name, an integer for the rotation, a numeric matrix for the parameters and a list of two strings for the variables types.

void vinecopulib::Bicop::to_file(const std::string& filename) const

Writes the copula object into a JSON or CBOR file.

Parameters
filename The name of the file to write.

Filenames ending in .cbor are written as CBOR. All other filenames are written as JSON for backwards compatibility. The written representation contains four attributes: "fam", "rot", "par", "vt", "nobs", "ll", "npars" respectively a string for the family name, an integer for the rotation, and a numeric matrix for the parameters, a list of two strings for the variable types, an integer for the number of observations (if fitted), a double for the log-likelihood (if fitted), and a double for the number of parameters (can be non-integer in nonparametric models).

double vinecopulib::Bicop::get_npars() const

The number of parameters of the copula model.

Returns the number of parameters in the copula model. For nonparametric families, this is a conceptually similar effective-parameter count.

Returns the actual number of parameters for parametric families. For nonparametric families, there is a conceptually similar definition in the sense that it can be used in the calculation of fit statistics.

Eigen::MatrixXd vinecopulib::Bicop::simulate(const size_t& n, const bool qrng = false, const std::vector<int>& seeds = std::vector<int>()) const

Simulates from a bivariate copula.

Parameters
n Number of observations.
qrng Set to true for quasi-random numbers.
seeds Seeds of the (quasi-)random number generator; if empty (default), the (quasi-)random number generator is seeded randomly.
Returns An $ n \times 2 $ matrix of samples from the copula model.

If qrng = TRUE, generalized Halton sequences are used. For more information on Generalized Halton sequences, see Faure, H., Lemieux, C. (2009). Generalized Halton Sequences in 2008: A Comparative Study. ACM-TOMACS 19(4), Article 15.

Eigen::MatrixXd vinecopulib::Bicop::simulate(const Eigen::MatrixXd& parameters, const bool qrng = false, const std::vector<int>& seeds = std::vector<int>(), const size_t num_threads = 1) const

Simulates from a bivariate copula with per-row parameters.

Parameters
parameters An $ n \times p $ matrix of parameters, where n is the number of observations to simulate, p is the number of family parameters (get_parameters().size()), and row i holds the parameter set used for observation i. Parameters are given in the family's natural (unrotated) parameterization, as for get_parameters().
qrng Set to true for quasi-random numbers.
seeds Seeds of the (quasi-)random number generator; if empty (default), the (quasi-)random number generator is seeded randomly.
num_threads The number of threads to parallelize the simulation over observations.
Returns An $ n \times 2 $ matrix of samples from the copula model.

Observation i is drawn from the copula carrying row i of parameters, without mutating the object's stored parameters. The family, rotation, and variable types are taken from the object; only the parameter values vary by observation. Available for parametric families only.

void vinecopulib::Bicop::fit(const Eigen::MatrixXd& u, const FitControlsBicop& controls = FitControlsBicop())

Fits a bivariate copula (with fixed family) to data.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
controls The controls (see FitControlsBicop).

For parametric models, two different methods are available. "mle" fits the parameters by maximum-likelihood. "itau" uses inversion of Kendall's $ \tau $ , but is only available for one-parameter families and the Student t copula. For the latter, there is a one-to-one transformation for the first parameter, the second is found by profile likelihood optimization (with accuracy of at least 0.5). Nonparametric families have specialized methods, no specification is required.

When at least one variable is discrete, two types of "observations" are required: the first $ n \times 2 $ block contains realizations of $ F_{X_1}(X_1), F_{X_2}(X_2) $ . Let $ k $ denote the number of discrete variables (either one or two). The second $ n \times 2 $ block contains realizations of $ F_{X_j}(X_j^-) $ . The minus indicates a left-sided limit of the cdf. For continuous variables the left limit and the cdf itself coincide, and their columns can be omitted from the second block. For, e.g., an integer-valued variable, it holds $ F_{X_j}(X_j^-) = F_{X_j}(X_j - 1) $ .

Incomplete observations (i.e., ones with a NaN value) are discarded.

void vinecopulib::Bicop::select(const Eigen::MatrixXd& u, FitControlsBicop controls = FitControlsBicop())

Selects the best fitting model.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
controls The controls (see FitControlsBicop).

The function calls Bicop::fit() for all families in family_set and selecting the best fitting model by either BIC or AIC, see Bicop::bic() and Bicop::aic().

When at least one variable is discrete, two types of "observations" are required: the first $ n \times 2 $ block contains realizations of $ F_{X_1}(X_1), F_{X_2}(X_2) $ . Let $ k $ denote the number of discrete variables (either one or two). The second $ n \times 2 $ block contains realizations of $ F_{X_j}(X_j^-) $ . The minus indicates a left-sided limit of the cdf. For continuous variables the left limit and the cdf itself coincide, and their columns can be omitted from the second block. For, e.g., an integer-valued variable, it holds $ F_{X_j}(X_j^-) = F_{X_j}(X_j - 1) $ .

Incomplete observations (i.e., ones with a NaN value) are discarded.

double vinecopulib::Bicop::loglik(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const

Evaluates the log-likelihood.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns The log-likelihood evaluated at u.

The log-likelihood is defined as

\[ \mathrm{loglik} = \sum_{i = 1}^n \log c(U_{1, i}, U_{2, i}), \]

where $ c $ is the copula density, see Bicop::pdf().

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

double vinecopulib::Bicop::aic(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const

Evaluates the Akaike information criterion (AIC).

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns The AIC evaluated at u.

The AIC is defined as

\[ \mathrm{AIC} = -2\, \mathrm{loglik} + 2 p, \]

where $ \mathrm{loglik} $ is the log-liklihood (see Bicop::loglik()) and $ p $ is the (effective) number of parameters of the model. The AIC is a consistent model selection criterion even for nonparametric models.

double vinecopulib::Bicop::bic(const Eigen::MatrixXd& u = Eigen::MatrixXd()) const

Evaluates the Bayesian information criterion (BIC).

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns The BIC evaluated at u.

The BIC is defined as

\[ \mathrm{BIC} = -2\, \mathrm{loglik} + \log(n) p, \]

where $ \mathrm{loglik} $ is the log-liklihood (see Bicop::loglik()) and $ p $ is the (effective) number of parameters of the model. The BIC is a consistent model selection criterion for parametric models.

double vinecopulib::Bicop::mbic(const Eigen::MatrixXd& u = Eigen::MatrixXd(), const double psi0 = 0.9) const

Evaluates the modified Bayesian information criterion (mBIC).

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
psi0 Prior probability of a non-independence copula.
Returns The mBIC evaluated at u.

The mBIC is defined as

\[ \mathrm{BIC} = -2\, \mathrm{loglik} + p \log(n) - 2 (I \log(\psi_0) + (1 - I) \log(1 - \psi_0), \]

where $ \mathrm{loglik} $ is the log-likelihood (see Bicop::loglik()), $ p $ is the (effective) number of parameters of the model, and $ \psi_0 $ is the prior probability of having a non-independence copula and $ I $ is an indicator for the family being non-independence.

double vinecopulib::Bicop::parameters_to_tau(const Eigen::MatrixXd& parameters) const

Converts the copula parameters to Kendall's $ \tau $ .

Parameters
parameters The parameters (must be a valid parametrization of the current family).

Available for every family. For the families whose $ \tau $ has no closed form (bb6, bb7, bb8, tawn) it is computed by quadrature. The sign is flipped for the 90 and 270 degree rotations.

Eigen::MatrixXd vinecopulib::Bicop::parameters_to_taildep(const Eigen::MatrixXd& parameters) const

Converts the copula parameters to the tail dependence coefficients.

Parameters
parameters The parameters (must be a valid parametrization of the current family).

The result is a $ 2 \times 2 $ matrix $ M $ collecting the tail dependence coefficients in the four corners of the unit square: $ M(i, j) $ is the coefficient as $ U_1 \to i $ and $ U_2 \to j $ , with $ i, j \in \{0, 1\} $ (0 = lower, 1 = upper). Thus $ M(0, 0) $ is the classical lower and $ M(1, 1) $ the classical upper tail dependence coefficient.

For the unrotated family, the lower $ \lambda_L = M(0, 0) $ and upper $ \lambda_U = M(1, 1) $ coefficients are:

FamilyLower $ \lambda_L $ Upper $ \lambda_U $
Independence, Gaussian, Frank $ 0 $ $ 0 $
Student t $ \lambda_t $ (see below) $ \lambda_t $
Clayton $ 2^{-1/\theta} $ $ 0 $
Gumbel $ 0 $ $ 2 - 2^{1/\theta} $
Joe $ 0 $ $ 2 - 2^{1/\theta} $
BB1 $ 2^{-1/(\theta\delta)} $ $ 2 - 2^{1/\delta} $
BB6 $ 0 $ $ 2 - 2^{1/(\theta\delta)} $
BB7 $ 2^{-1/\delta} $ $ 2 - 2^{1/\theta} $
BB8 $ 0 $ $ 2 - 2^{1/\theta} $ if $ \delta=1 $ , else 0
Tawn (extreme-value) $ 0 $ $ 2 (1 - A(1/2)) $
TLL (nonparametric)NaNNaN

Here $ \theta $ (and $ \delta $ for two-parameter families) denote the copula parameters and $ A $ the Pickands dependence function. For the Student t copula, with correlation $ \rho $ , degrees of freedom $ \nu $ , and $ t_{\nu+1} $ the Student t cdf, $ \lambda_t = 2\, t_{\nu+1}(-\sqrt{(\nu+1)(1-\rho)/(1+\rho)}) $ ; it additionally has equal dependence in the two off-diagonal (discordant) corners, obtained by replacing $ \rho $ with $ -\rho $ . All other parametric families have zero off-diagonal coefficients. Rotations permute the corners: 180 degrees swaps lower/upper, while 90/270 degrees move dependence to the off-diagonal corners.

double vinecopulib::Bicop::parameters_to_beta(const Eigen::MatrixXd& parameters) const

Converts the copula parameters to Blomqvist's $ \beta $ .

Parameters
parameters The parameters (must be a valid parametrization of the current family).

Blomqvist's beta is computed from the copula cdf as $ \beta = 4\, C(0.5, 0.5) - 1 $ , using the same formula for every family (including the nonparametric tll).

Eigen::MatrixXd vinecopulib::Bicop::tau_to_parameters(const double& tau) const

Converts a Kendall's $ \tau $ into copula parameters for one-parameter families.

Parameters
tau A value in $ (-1, 1) $ .
Exceptions
std::runtime_error if the family is not one of those listed above.

Only available where $ \tau $ determines the parameters completely: the one-parameter families in bicop_families::itau, i.e. indep, gaussian, clayton, gumbel, frank and joe. Note that student belongs to bicop_families::itau — it can be fitted by inverting $ \tau $ — but is not invertible here, because $ \tau $ pins its correlation and leaves the degrees of freedom free.

Bicop vinecopulib::Bicop::with_var_types(const std::vector<std::string>& var_types = { "c", "c" }) const

The same copula under different variable types.

Parameters
var_types A vector specifying the types of the variables, e.g., {"c", "d"} means first variable continuous, second discrete. Defaults to both continuous.
Returns A copy with the given variable types.
Exceptions
std::runtime_error if var_types is not two entries, each "c" or "d".

The model is unchanged: only the variable types change, so a fitted copula can be evaluated on a continuous, discrete or mixed edge without being refitted. The types decide which layout pdf(), cdf() and the h-functions expect and what they return (see Discrete variables).

BicopFamily vinecopulib::Bicop::get_family() const

Gets the copula family.

Returns the copula family.

std::string vinecopulib::Bicop::get_family_name() const

Gets the copula family as a string.

Returns the human-readable name of the copula family.

int vinecopulib::Bicop::get_rotation() const

Gets the rotation.

Returns the copula rotation in degrees (one of 0, 90, 180, 270).

Eigen::MatrixXd vinecopulib::Bicop::get_parameters() const

Gets the parameters.

Returns the copula parameter(s) as a matrix (shape depends on the family).

double vinecopulib::Bicop::get_tau() const

Gets the Kendall's tau.

Returns Kendall's tau implied by the current parameters.

Eigen::MatrixXd vinecopulib::Bicop::get_taildep() const

Gets the tail dependence coefficients.

Returns the tail dependence coefficients implied by the current parameters, as a 2x2 matrix; see parameters_to_taildep().

See Bicop::parameters_to_taildep() for the layout of the returned $ 2 \times 2 $ matrix.

double vinecopulib::Bicop::get_beta() const

Gets Blomqvist's beta.

Returns Blomqvist's beta implied by the current parameters.

double vinecopulib::Bicop::get_loglik() const

Gets the log-likelihood (only for fitted objects).

Returns the log-likelihood of the data the copula was fitted to.

size_t vinecopulib::Bicop::get_nobs() const

Gets the number of observations (only for fitted objects).

Returns the number of observations used to fit the copula (0 until fit() has been called).

double vinecopulib::Bicop::get_aic() const

Gets the aic (only for fitted objects).

Returns Akaike's information criterion at the fitted parameters.

double vinecopulib::Bicop::get_bic() const

Gets the bic (only for fitted objects).

Returns the Bayesian information criterion at the fitted parameters.

double vinecopulib::Bicop::get_mbic(const double psi0 = 0.9) const

Gets the modified bic (only for fitted objects).

Returns the modified Bayesian information criterion at the fitted parameters; psi0 is the prior probability of a non-independence copula.

void vinecopulib::Bicop::set_rotation(const int rotation)

Sets the rotation.

Parameters
rotation one of 0, 90, 180, 270.

Sets the copula rotation.

void vinecopulib::Bicop::set_parameters(const Eigen::MatrixXd& parameters)

Parameters
parameters parameter matrix; shape must match the family's expected parameter layout.

Sets the copula parameters.

void vinecopulib::Bicop::set_var_types(const std::vector<std::string>& var_types = { "c", "c" })

Sets variable types.

Parameters
var_types a length-2 vector with each entry either "c" (continuous, default) or "d" (discrete).

Sets the variable types.

std::vector<std::string> vinecopulib::Bicop::get_var_types() const

Gets variable types.

Returns the variable types of the two variables (each "c" for continuous or "d" for discrete).

Eigen::VectorXd vinecopulib::Bicop::pdf(const Eigen::MatrixXd& u) const

Evaluates the copula density.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of copula densities evaluated at u.

The copula density is defined as joint density divided by marginal densities, irrespective of variable types.

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::cdf(const Eigen::MatrixXd& u) const

Evaluates the copula distribution.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of copula probabilities evaluated at u.

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::hfunc1(const Eigen::MatrixXd& u) const

Evaluates the first h-function.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of the first h-function evaluated at u.

The first h-function is $ h_1(u_1, u_2) = P(U_2 \le u_2 | U_1 = u_1) $ .

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::hfunc2(const Eigen::MatrixXd& u) const

Evaluates the second h-function.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of the second h-function evaluated at u.

The second h-function is $ h_2(u_1, u_2) = P(U_1 \le u_1 | U_2 = u_2) $ .

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::hinv1(const Eigen::MatrixXd& u) const

Evaluates the inverse of the first h-function.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of the inverse of the first h-function evaluated at u.

The first h-function is $ h_1(u_1, u_2) = P(U_2 \le u_2 | U_1 = u_1) $ . The inverse is calculated w.r.t. the second argument.

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::hinv2(const Eigen::MatrixXd& u) const

Evaluates the inverse of the second h-function.

Parameters
u An $ n \times 2 $ matrix of observations for a continuous model. For a model with $ k $ discrete variables, use an $ n \times 4 $ matrix containing the values and their left-limits; left-limit columns for continuous variables may be omitted to obtain the compact $ n \times (2 + k) $ layout (see Discrete variables).
Returns A length n vector of the inverse of the second h-function evaluated at u.

The second h-function is $ h_2(u_1, u_2) = P(U_1 \le u_1 | U_2 = u_2) $ . The inverse is calculated w.r.t. the first argument.

When at least one variable is discrete, more than two columns are required for u: the first $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1), F_{X_2}(x_2)) $ . The second $ n \times 2 $ block contains realizations of $ (F_{X_1}(x_1^-), F_{X_2}(x_2^-)) $ . The minus indicates a left-sided limit of the cdf. For, e.g., an integer-valued variable, it holds $ F_{X_1}(x_1^-) = F_{X_1}(x_1 - 1) $ . For continuous variables the left limit and the cdf itself coincide. Respective columns can be omitted in the second block.

Eigen::VectorXd vinecopulib::Bicop::pdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a first derivative of the copula density.

deriv is one of "par1", "par2", ... (short form "par"), "u1", or "u2".

Eigen::VectorXd vinecopulib::Bicop::pdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a second derivative of the copula density.

deriv combines two first-order components, e.g. "par1par1", "par1u1", "u1u2"; a single component means differentiating twice.

Eigen::VectorXd vinecopulib::Bicop::hfunc1_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a first derivative of the first h-function $ h_1(u_1, u_2) = P(U_2 \le u_2 | U_1 = u_1) $ .

deriv is one of "par1", "par2", ... (short form "par"), "u1" (the conditioning argument), or "u2" (which equals the copula density).

Eigen::VectorXd vinecopulib::Bicop::hfunc1_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a second derivative of the first h-function.

deriv combines two first-order components; any selector containing "u2" reduces to a density derivative (e.g. "par1u2" equals pdf_deriv(u, "par1")).

Eigen::VectorXd vinecopulib::Bicop::hfunc2_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a first derivative of the second h-function $ h_2(u_1, u_2) = P(U_1 \le u_1 | U_2 = u_2) $ .

deriv is one of "par1", "par2", ... (short form "par"), "u2" (the conditioning argument), or "u1" (which equals the copula density).

Eigen::VectorXd vinecopulib::Bicop::hfunc2_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a second derivative of the second h-function.

deriv combines two first-order components; any selector containing "u1" reduces to a density derivative (e.g. "par1u1" equals pdf_deriv(u, "par1")).

Eigen::VectorXd vinecopulib::Bicop::logpdf_deriv(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a first derivative of the log-density $ \partial \log c / \partial \cdot $ .

For parameter selectors, dedicated closed forms are used where available (numerically stabler than pdf_deriv() / pdf() when the density is small); argument selectors are composed by the quotient rule.

Eigen::VectorXd vinecopulib::Bicop::logpdf_deriv2(const Eigen::MatrixXd& u, const std::string& deriv) const

Evaluates a second derivative of the log-density.

See logpdf_deriv(); selectors involving the arguments are composed from density derivatives by the quotient rule.

Eigen::MatrixXd vinecopulib::Bicop::scores(const Eigen::MatrixXd& u) const

Evaluates the per-observation scores.

Returns An $ n \times p $ matrix whose column k is $ \partial \log c / \partial \theta_{k+1} $ .

Eigen::VectorXd vinecopulib::Bicop::gradient(const Eigen::MatrixXd& u) const

Evaluates the gradient of the average log-likelihood.

Returns The observation-average of scores(), a vector of length p.

Eigen::MatrixXd vinecopulib::Bicop::hessian(const Eigen::MatrixXd& u) const

Evaluates the Hessian of the average log-likelihood.

Returns A symmetric $ p \times p $ matrix whose entry $ (a, b) $ is the observation-average of $ \partial^2 \log c / \partial \theta_{a+1} \partial \theta_{b+1} $ .

std::vector<Eigen::MatrixXd> vinecopulib::Bicop::hessian_full(const Eigen::MatrixXd& u) const

Evaluates the per-observation Hessians.

Returns A vector of n symmetric $ p \times p $ matrices; entry i's $ (a, b) $ element is $ \partial^2 \log c(u_i; \theta) / \partial \theta_{a+1} \partial \theta_{b+1} $ .

Eigen::MatrixXd vinecopulib::Bicop::scores_cov(const Eigen::MatrixXd& u) const

Computes the covariance matrix of the scores.

Returns The mean-centered, divided-by-n covariance of scores(), a $ p \times p $ matrix.

ScoresResult vinecopulib::Bicop::scores_full(const Eigen::MatrixXd& u) const

Evaluates the scores, bundled in a ScoresResult.

Provided for parity with Vinecop::scores_full(); a single pair copula has no cascade caches, so the result only carries the score matrix.