High Performance Algorithms for Vine Copula Modeling

Provides an interface to 'vinecopulib', a C++ library for vine copula modeling. The 'rvinecopulib' package implements the core features of the popular 'VineCopula' package, in particular inference algorithms for both vine copula and bivariate copula models. Advantages over 'VineCopula' are a sleeker and more modern API, improved performances, especially in high dimensions, nonparametric and multi-parameter families, and the ability to model discrete variables. The 'rvinecopulib' package includes 'vinecopulib' as header-only C++ library (currently version 1.0.0). Thus users do not need to install 'vinecopulib' itself in order to use 'rvinecopulib'. Since their initial releases, 'vinecopulib' is licensed under the MIT License, and 'rvinecopulib' is licensed under the GNU GPL version 3.

rvinecopulib

rvinecopulib provides high-performance tools for bivariate and vine copula models. It covers model construction, estimation and selection, simulation, prediction, visualization, discrete and mixed data, and full multivariate distributions with fitted margins. The package is the R interface to the vinecopulib C++ library.

Main capabilities

• fit, select, evaluate, and simulate bivariate copula models, including parametric, nonparametric, rotated, and extreme-value families;
• fit and select high-dimensional vine copula models and structures, with automatic family, structure, truncation, and threshold selection;
• combine vine copulas with nonparametric, parametric, or custom marginal models to form complete multivariate distributions;
• handle continuous, integer-valued discrete, mixed, and zero-inflated data, with optional observation weights;
• perform conditional simulation and Rosenblatt transforms;
• compute likelihood scores and Hessians and evaluate models with observation-specific parameters;
• use parallel fitting, custom marginal families, and custom tree-selection criteria in extensible modeling workflows.

Installation

Install the stable release from CRAN:

install.packages("rvinecopulib")

Install the development version from GitHub:

remotes::install_github("vinecopulib/rvinecopulib")

Examples

rvinecopulib exposes the same modeling framework at three levels:

A bivariate copula

bicop() fits and selects a copula model for two uniform variables. Fixed models can be created with bicop_dist().

u <- rbicop(200, family = "clayton", rotation = 90, parameters = 2)
bivariate_fit <- bicop(u, family_set = "par")
summary(bivariate_fit)

dbicop(u[1:5, ], bivariate_fit)
tail_dep(bivariate_fit)

See the bivariate-copula article for implemented families, rotations, h-functions, dependence measures, and selection controls.

A vine copula on the copula scale

pseudo_obs() converts continuous observations to approximately uniform scores. vinecop() then selects the vine structure, pair-copula families, and parameters.

u <- pseudo_obs(as.matrix(USArrests))
copula_fit <- vinecop(u, family_set = "onepar")
summary(copula_fit)

simulated_u <- rvinecop(100, copula_fit)
dvinecop(simulated_u[1:5, ], copula_fit)

See the vine-copula article for structure construction, selection, truncation, and model inspection.

A full distribution on the original scale

vine() fits one marginal distribution per variable and a vine copula to their probability integral transforms. The default margins are nonparametric; parametric and custom marginal families are also supported.

n <- 150
latent <- rnorm(n)
x <- data.frame(
  amount = exp(latent + rnorm(n, sd = 0.5)),
  duration = exp(0.5 * latent + rnorm(n, sd = 0.7)),
  count = rpois(n, exp(0.2 + 0.3 * latent))
)

fit <- vine(
  x,
  var_types = c("c", "c", "d"),
  copula_controls = list(family_set = "onepar")
)
summary(fit)
rvine(5, fit)

See the marginal-modeling article for parametric selection, custom families, ordered variables, zero inflation, and observation weights. The getting-started article develops the complete workflow.

The constructors bicop_dist(), vinecop_dist(), and vine_dist() create models from components specified directly.

The complete API reference and all articles are available on the package website. Questions and bug reports are welcome in the GitHub issue tracker.