5

rvinecopulib

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 0.5.2). 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.

Build status Linux Windows Build status Coverage Status CRAN version CRAN downloads

Vine copulas are a flexible class of dependence models consisting of bivariate building blocks (see e.g., Aas et al., 2009). You can find a comprehensive list of publications and other materials on vine-copula.org.

This package is the R API to the C++ library vinecopulib, a header-only C++ library for vine copula models based on Boost and Eigen.

It provides high-performance implementations of the core features of the popular VineCopula R library, in particular inference algorithms for both vine copula and bivariate copula models. Advantages over VineCopula are

  • a sleaker and more modern API,
  • shorter runtimes, especially in high dimensions,
  • nonparametric and multi-parameter families.

As VineCopula, the package is primarily made for the statistical analysis of vine copula models. The package includes tools for parameter estimation, model selection, simulation, and visualization. Tools for estimation, selection and exploratory data analysis of bivariate copula models are also provided. Please see the API documentation for a detailed description of all functions.

Table of contents

How to install

You can install:

  • the stable release on CRAN:

    install.packages("rvinecopulib")

  • the latest development version:

    devtools::install_github("vinecopulib/rvinecopulib")

Package overview

Below, we list most functions and features you should know about. As usual in copula models, data are assumed to be serially independent and lie in the unit hypercube.

  • bicop_dist: Creates a bivariate copula by specifying the family, rotation and parameters. Returns an object of class bicop_dist. The class has the following methods:

    • print: a brief overview of the bivariate copula.

    • plot, contour: surface/perspective and contour plots of the copula density. Possibly coupled with standard normal margins (default for contour).

  • dbicop, pbicop, rbicop, hbicop: Density, distribution function, random generation and H-functions (with their inverses) for bivariate copula distributions. Additionally to the evaluation points, you can provide either family, rotation and parameter, or an object of class bicop_dist.

  • bicop: Estimates parameters of a bivariate copula. Estimation can be done by maximum likelihood (par_method = "mle") or inversion of the empirical Kendall's tau (par_method = "itau", only available for one-parameter families) for parametric families, and using local-likelihood approximations of order zero/one/two for nonparametric models (nonpar_method="constant"/nonpar_method="linear"/nonpar_method="quadratic"). If family_set is a vector of families, then the family is selected using selcrit="loglik", selcrit="aic" or selcrit="bic". The function returns an object of classes bicop and bicop_dist. The class bicop has the following following methods:

    • print: a more comprehensive overview of the bivariate copula model with fit statistics.

    • predict, fitted: predictions and fitted values for a bivariate copula model.

    • nobs, logLik, AIC, BIC: usual fit statistics.

Vine copula modeling: vinecop_dist and vinecop

  • vinecop_dist: Creates a vine copula by specifying a nested list of bicop_dist objects and a quadratic structure matrix. Returns an object of class vinecop_dist. The class has the following methods:

    • print, summary: a brief and more comprehensive overview of the vine copula.

    • plot: plots of the vine structure.

  • dvinecop, pvinecop, rvinecop: Density, distribution function, random generation for vine copula distributions.

  • vinecop: automated fitting for vine copula models. The function inherits the parameters of bicop. Optionally, a quadratic matrix can be used as input to pre-specify the vine structure. tree_crit describes the criterion for tree selection, one of "tau", "rho", "hoeffd" for Kendall's tau, Spearman's rho, and Hoeffding's D, respectively. Additionally, threshold allows to threshold the tree_crit and trunc_lvl to truncate the vine copula, with threshold_sel and trunc_lvl_sel to automatically select both parameters. The function returns an object of classes vinecop and vinecop_dist. The class has the vinecop has the following following methods:

    • print, summary: a brief and more comprehensive overview of the vine copula with additional fit statistics information.

    • predict, fitted: predictions and fitted values for a vine copula model.

    • nobs, logLik, AIC, BIC: usual fit statistics.

Bivariate copula families

In this package several bivariate copula families are included for bivariate and multivariate analysis using vine copulas. It provides functionality of elliptical (Gaussian and Student-t) as well as Archimedean (Clayton, Gumbel, Frank, Joe, BB1, BB6, BB7 and BB8) copulas to cover a large range of dependence patterns. For Archimedean copula families, rotated versions are included to cover negative dependence as well. Additionally, nonparametric families are also supported.

type name name in R
- 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"
Nonparametric Transformation kernel "tll"

Note that several convenience vectors of families are included:

  • "all" contains all the families
  • "parametric" contains the parametric families (all except "tll")
  • "nonparametric" contains the nonparametric families ("indep" and "tll")
  • "one_par" contains the parametric families with a single parameter ("gaussian", "clayton", "gumbel", "frank", and "joe")
  • "two_par" contains the parametric families with two parameters ("student", "bb1", "bb6", "bb7", and "bb8")
  • "elliptical" contains the elliptical families
  • "archimedean" contains the archimedean families
  • "BB" contains the BB families
  • "itau" families for which estimation by Kendall's tau inversion is available ("indep","gaussian", "student","clayton", "gumbel", "frank", "joe")

The following table shows the parameter ranges of bivariate copula families with one or two parameters:

Copula family par[1] par[2]
Gaussian (-1, 1) -
Student t (-1, 1) (2,Inf)
Clayton (0, Inf) -
Gumbel [1, Inf) -
Frank R \ {0} -
Joe (1, Inf) -
Clayton-Gumbel (BB1) (0, Inf) [1, Inf)
Joe-Gumbel (BB6) [1 ,Inf) [1, Inf)
Joe-Clayton (BB7) [1, Inf) (0, Inf)
Joe-Frank (BB8) [1, Inf) (0, 1]

References

Aas, K., C. Czado, A. Frigessi, and H. Bakken (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics 44 (2), 182-198.

News

rvinecopulib 0.3.1.1.0 (April 19, 2019)

Release following the updates of vinecopulib to 0.3.1, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • import vinecopulib 0.3.1 (#171)

  • improve documentation (#168, #170)

  • warning message for wrong family in itau method (#169)

  • refactoring for enhanced extensibility of the class Vinecop (vinecopulib #407)

  • simplify algorithms by reversing definition of natural order (vinecopulib #387)

  • improve selection of truncation level (vinecopulib #373)

  • add truncate methods for TriangularArray, RVineStructure and Vinecop (vinecopulib #372)

BUG FIXES

  • don't strip debug symbols unconditionally on linux (#174)

rvinecopulib 0.3.0.1.1 (August 22, 2018)

BUG FIXES

  • fix non-portable use of log() in C++ code (#147).

  • remove parallelized unit test to avoid segfault on Solaris (#147).

rvinecopulib 0.3.0.1.0 (August 9, 2018)

Release following the updates of vinecopulib to 0.3.0, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • new generic truncate_model() to truncated vine structures and models (#144).

  • new functions rosenblatt() and inverse_rosenblatt() for computing the (inverse) Rosenblatt transformation (#142).

  • faster algorithms for nonparametric copulas based on bilinear interpolation.

  • refactor vine structures and related algorithms with triangular arrays to improve efficiency of truncated models (#136).

  • new classes rvine_structure and rvine_matrix for storing the vine structure including as_- and is.-generics (#136).

  • allow for generating quasi-random numbers (#126).

  • improved parallelization: faster of fitting vine copula models and parallelized versions of many algorithms including pdf, cdf and simulation (#339, #363).

  • allow weights for observations (#118).

  • faster compilation using only a single wrapper file (#124).

  • improved print and summary generics (#131).

BUG FIXES

  • fix cdf of StudentBicop

  • improved numerical stability.

  • fix gcc-8 warning.

  • fix missing variable names for class vine.

rvinecopulib 0.2.8.1.0 (May 8, 2018)

Release following the updates of vinecopulib to 0.2.8, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • new vine_dist and vine classes for data with non-uniform margins (#97).

  • new function truncate_model() for vinecop_dist and vine_dist objects (#95, #97).

  • new convenience functions get_pair_copula(), get_parameters(), get_ktau(), get_family() for bicop_dist, vinecop_dist and vine_dist objects (#95, #107, #109).

  • new convenience functions get_matrix(), get_all_pair_copulas(), get_all_parameters(), get_all_ktaus(), get_all_families() for vinecop_dist and vine_dist objects (#95, #107, #109).

  • new (dim) and improved (print, summary and logLik) generic methods for vinecop_dist and vine_dist objects (#104, #109, #110).

  • new function pseudo_obs to compute pseudo-observations (#108).

  • improved documentation (#98, #100).

  • improved sanity checks and error messages (#99, #102).

BUG FIXES

  • make mcor correction less agressive (#103).

  • fix truncation of pdf values (#103).

  • use increased search interval for parameter estimation when initial fit is unreasonable (#103).

  • ensure that boundaries are respected for Joe's hinv methods (#103).

  • improve numerical stability by more restrictive parameter bounds for Joe and BB7 copulas (#103).

rvinecopulib 0.2.7.1.0 (March 1, 2018)

Release following the updates of vinecopulib to 0.2.7, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • new criterion for tree selection "mcor".

BUG FIXES

  • fix bandwidth scaling for family "tll".

rvinecopulib 0.2.6.1.1 (February 24, 2018)

Patch of rvinecopulib 0.2.6.1.0.

BUG FIXES

  • corrected documentation items.

rvinecopulib 0.2.6.1.0 (February 23, 2018)

Release following the updates of vinecopulib to 0.2.6, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • add checks for data in (0, 1).

  • improved bandwidth selection for method "tll" by scaling with maximum-correlation coefficient.

  • add mBICV criterion to select the truncation level and threshold along with new function mBICV().

BUG FIXES

  • fix calculation of Hoeffding's D.

rvinecopulib 0.2.5.1.0 (January 14, 2017)

Release following the updates of vinecopulib to 0.2.4 and 0.2.5, see https://github.com/vinecopulib/vinecopulib/releases. The most relevant changes are summarized below.

NEW FEATURES

  • faster simulation and pdf functions for truncated vines.

  • speed up vine copula algorithms by pre-computing information related to the vine structure.

  • the selected threshold parameter can be returned from an vinecop object.

BUG FIXES

  • make bb8 lower bound ensure feasible computations in par_to_tau().

  • default initialize Rcout (#277).

  • fix storage order of pair copulas when structure is fixed.

  • fixed selection algorithm for threshold and truncation level.

rvinecopulib 0.2.3.1.0 (November 18, 2017)

Release following the update of vinecopulib to 0.2.3, see https://github.com/vinecopulib/vinecopulib/releases/tag/v0.2.3. The most relevant changes are summarized below.

NEW FEATURES

  • faster implementation of Archimedean pdfs.

BUG FIXES

  • add safeguards for bicop()/vinecop() called with insufficient data.

  • fix segfault issue in completing a truncated vine fit.

  • make par_method = "itau" respect the parameter bounds.

rvinecopulib 0.2.2.1.0 (November 9, 2017)

Release following the updates of vinecopulib to 0.2.1 and 0.2.2, see https://github.com/vinecopulib/vinecopulib/releases/tag/v0.2.1 and https://github.com/vinecopulib/vinecopulib/releases/tag/v0.2.2. The most relevant changes are summarized below.

NEW FEATURES

  • faster vine copula estimation and selection by parallelizing further sub-routines.

  • enhanced cross-platform compatibility.

  • increased precision of maximum-likelihood estimators.

  • allow "loglik" as selection criterion.

BUG FIXES

  • fixed itau estimation method for Frank copulas (only allowed for positive parameters).

  • make interpolation grid symmetric around (0.5, 0.5) again (for "tll" estimator).

rvinecopulib 0.2.0.1.0 (October 30, 2017)

Release following the update of vinecopulib to 0.2.0, see https://github.com/vinecopulib/vinecopulib/releases/tag/v0.2.0. The most relevant changes are summarized below.

PACKAGING/DEPENDECY

  • the C++ core of the library (besides wrappers) is now header only, so other R packages can access its functionality easily via LinkingTo.

  • removed dependency on NLopt.

NEW FEATURES

  • NA handling.

  • parallelized selection/estimation of (pair-) copulas, see the cores argument in bicop() and vinecop().

  • efficient storage and fitting of truncated vines.

  • Brent line search for (profile-) maximum-likelihood estimation of one-parameter families.

  • more restrictive parameter bounds for Archimedean families, ensuring their numerical stability.

BUG FIXES

  • error thrown whenever vinecop() or bicop() are called with data sets containing a single row.

  • made order of rvinecop(..., U) consistent for d = 2 and d > 2.

  • fixed bug in interpolation of kernel estimators near upper right corner.

  • interpolation grid is now symmetric around (0.5, 0.5).

  • stabilized quadratic tll estimator near zero.

  • stabilized Archimedean pdfs.

rvinecopulib 0.1.0.1.1 (September 1, 2017)

BUG FIXES

  • Improve portability when using mathematical functions

rvinecopulib 0.1.0.1.0 (August 29, 2017)

Initial release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("rvinecopulib")

0.5.2.1.0 by Thomas Nagler, 2 months ago

Report a bug at https://github.com/vinecopulib/rvinecopulib/issues

Browse source code at https://github.com/cran/rvinecopulib

Authors: Thomas Nagler [aut, cre] , Thibault Vatter [aut]

Documentation:   PDF Manual  

GPL-3 | file LICENSE license

Imports assertthat, graphics, grDevices, kde1d, lattice, Rcpp, stats, utils

Suggests igraph, ggplot2, ggraph, testthat

Linking to BH, Rcpp, RcppEigen, RcppThread, wdm, kde1d

System requirements: C++11

Imported by covsim, simIReff, vinereg.

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug