Kernel Smoothing for Bivariate Copula Densities

Provides fast implementations of kernel smoothing techniques for bivariate copula densities, in particular density estimation and resampling, see Nagler (2018) .


Build status Linux Build status Windows codecov.io CRAN version CRAN downloads License: GPL v3

This package provides fast implementations of kernel estimators for the copula density. Due to its several plotting options it is particularly useful for the exploratory analysis of dependence structures. It can be further used for flexible nonparametric estimation of copula densities and resampling.

For detailed documentation, see the package vignette and the API documentation.

Table of contents


How to install

You can install:

  • the stable release on CRAN:

    install.packages("kdecopula")
  • the latest development version:

    devtools::install_github("tnagler/kdecopula")

Functions

The package provides the following functions:

  • kdecop: Kernel estimation of a copula density. By default, estimation method and bandwidth are selected automatically. Returns an object of class kdecopula.

  • dkdecop: Evaluates the density of a kdecopula object.

  • pkdecop: Evaluates the distribution function of a kdecopula object.

  • rkdecop: Simulates synthetic data from a kdecopula object.

  • Methods for class kdecopula:

    • plot, contour: Surface and contour plots of the density estimate.

    • print, summary: Displays further information about the density estimate.

    • logLik, AIC, BIC: Extracts fit statistics.

See the package documentation for more details on arguments and options.


kdecopula in action

Below, we demonstrate the main capabilities of the kdecopula package. All user-level functions will be introduced with small examples.

Let's consider some variables of the Wiscon diagnostic breast cancer data included in this package. The data are transformed to pseudo-observations of the copula by the empirical probability integral/rank transform:

library(kdecopula)
data(wdbc)  # load data
u <- apply(wdbc[, c(2, 8)], 2, rank) / (nrow(wdbc) + 1)  # empirical PIT
plot(u)  # scatter plot

We see that the data are slightly asymmetric w.r.t. both diagonals. Common parametric copula models are usually not flexible enough to reflect this. Let's see how a kernel estimator does.

We start by estimating the copula density with the kdecop function. There is a number of options for the smoothing parameterization, estimation method and evaluation grid, but it is only required to provide a data-matrix.

kde.fit <- kdecop(u)  # kernel estimation (bandwidth selected automatically)
summary(kde.fit)
#> Kernel copula density estimate (tau = 0.47)
#> ------------------------------
#> Variables:    mean radius -- mean concavity 
#> Observations: 569 
#> Method:       Transformation local likelihood, log-quadratic (nearest-neighbor, 'TLL2nn') 
#> Bandwidth:    alpha = 0.3519647
#>               B = matrix(c(0.71, 0.7, -0.7, 0.71), 2, 2)
#> ---
#> logLik: 201.22    AIC: -367.97    cAIC: -366.83    BIC: -293.11 
#> Effective number of parameters: 17.23

The output of the function kdecop is an object of class kdecopula that contains all information collected during the estimation process and summary statistics such as AIC or the effective number of parameters/degrees of freedom. These can also be accessed directly, e.g.

logLik(kde.fit)
#> 'log Lik.' 201.2196 (df=17.23373)
AIC(kde.fit)
#> [1] -367.9718

Plotting bivariate copula densities

The most interesting part for most people is probably to make exploratory plots. The class kdecopula has its own generic for plotting. In general, there are two possible types of plots: contour and surface (or perspective) plots. Additionally, the margins argument allows to choose between plots of the original copula density and a meta-copula density with standard normal margins (default for type = contour).

plot(kde.fit)

contour(kde.fit)

contour(kde.fit, margins = "unif")

You can also pass further arguments to the ... argument to refine the aesthetics. The arguments are forwaded to lattice::wireframe or graphics::contour, respectively.

plot(kde.fit, 
     zlim = c(0, 10),  # z-axis limits
     screen = list(x = -75, z = 45),  # rotate screen
     xlab = list(rot = 25),  # labels can be rotated as well
     ylab = list(label = "other label", rot = -25))  

contour(kde.fit, col = terrain.colors(30), levels = seq(0, 0.3, by = 0.01))

Working with a kdecopula object

The density and cdf can be computed easily:

dkdecop(c(0.1, 0.2), kde.fit)  # estimated copula density
#> [1] 1.691764
pkdecop(cbind(c(0.1, 0.9), c(0.1, 0.9)), kde.fit) # corresponding copula cdf
#> [1] 0.0327257 0.8505370

Furthermore, we can simulate synthetic data from the estimated density:

unew <- rkdecop(655, kde.fit)
plot(unew)

We see that the asymmetries observed in the data are adequately reflected by the estimated model.

References

Gijbels, I. and Mielniczuk, J. (1990). Estimating the density of a copula function. Communications in Statistics - Theory and Methods, 19(2):445-464.

Charpentier, A., Fermanian, J.-D., and Scaillet, O. (2006). The estimation of copulas: Theory and practice. In Rank, J., editor, Copulas: From theory to application in finance. Risk Books.

Geenens, G., Charpentier, A., and Paindaveine, D. (2014). Probit transformation for nonparametric kernel estimation of the copula density. arXiv:1404.4414 (stat.ME).

Nagler, T. (2014). Kernel Methods for Vine Copula Estimation. Master's Thesis, Technische Universität München

Wen, K. and Wu, X. (2015). Transformation-Kernel Estimation of the Copula Density, Working paper, preprint

News

kdecopula 0.9.2

NEW FEATURES

  • faster computations for method = "bern" due to removal of the quadratic programming step for rescaling to uniform margins.

kdecopula 0.9.1

BUG FIXES

  • fix bug in interpolation near boundaries (interpolated in wrong cell, see #2, #3).

kdecopula 0.9.0

NEW FEATURES

  • user visible functions for bandwidth selection (bw_xxx()) with documentation.

  • predict(), fitted(), and simulate() generics.

  • make TLL2nn the default method.

  • new function dep_measures() for calculating dependence measures.

kdecopula 0.8.1

NEW FEATURES

  • stabilized bandwidth matrix transformation.

  • faster builds (removed unnecessarily included headers).

  • updated documentation.

kdecopula 0.8.0

NEW FEATURES

  • Improved bandwidth selection heuristic for methods TLL1/TLL2.

  • The Bernstein copula density estimator is documented and comes with an automated smoothing parameter selection routine.

  • All bandwidth selection methods now have a manual page (see ?kdecop for links).

  • Updated vignette.

BUG FIXES

  • fixed inconsistencies in bandwidth specification. The interpretation of the bandwidth matrix is now the same for TLL and T methods.

kdecopula 0.7.0

DEPENDS

  • Added quadprog to imports.

NEW FEATURES

  • Methods TLL1 and TLL2 now use fixed bandwidths; nearest neighbor methods are implemented as TLL1nn and TLL2n.

  • Improved bandwidth selection for methods TLL1nn and TLL2nn.

  • Improved memory allocation.

  • Hidden (and undocumented) method bern for the Bernstein copula density.

BUG FIXES

  • Bandwidth selection for methods TTxx are now safe even when correlation is high and sample size small.

kdecopula 0.6.0

DEPENDS

  • Package no longer imports packages cubature and VineCopula.

BUG FIXES

  • improved algorithms for numerical inversion

NEW FEATURES

  • new function hkdecop to evaluate conditional distributions ("h-functions").

  • extended plotting functionality (exponential margins).

  • faster calculations of bandwidths for methods "MR" and "beta" due to precalculated integral values.

OTHER

  • updated vignette.

kdecopula 0.5.0

BUG FIXES

  • fix scaling for method = "MR" when not renormalized.

NEW FEATURES

  • package now has a vignette.

kdecopula 0.4.1

BUG FIXES

  • rkdecop now properly working with quasi-random numbers.

  • improved efficiency of C++ code.

kdecopula 0.4.0

NEW FEATURES

  • New estimation method: tapered transformation estimator (methods "TTPI" and "TTCV"). Thanks to Kuangyu Wen for sharing code!

kdecopula 0.3.0

NEW FEATURES

  • New methods for class kdecopula: logLik, AIC, BIC

  • Full summary (logLik, AIC, BIC, effp) even when info = FALSE.

BUG FIXES

  • Fixed typo in install instructions.

  • Fixed bug in summary (method = "T").

  • Improve formatting in summary.

kdecopula 0.2.0

NEW FEATURES

  • New methods for class kdecopula: print, summary, contour.

  • kdecop: Default for info argument is now TRUE.

  • Updated documentation.

BUG FIXES

  • kdecop: fix error when requesting info about fit.

kdecopula 0.1.0

DEPENDS

  • Package now imports the qrng pacakge.

NEW FEATURES

  • rkdecop: add quasi-random number option based on package qrng.

kdecopula 0.0.4

BUG FIXES

  • dkdecop: set cutoff for stable option in to 50

  • Fix memory read errors.

kdecopula 0.0.3

BUG FIXES

  • Dixed some memory issues in C++ code.

  • Adjust imports for R-3.3.0.

kdecopula 0.0.2

BUG FIXES

  • Fixed issues with non-portable C++ code (problems occured on solaris).

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("kdecopula")

0.9.2 by Thomas Nagler, 9 months ago


https://github.com/tnagler/kdecopula


Report a bug at https://github.com/tnagler/kdecopula/issues


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


Authors: Thomas Nagler [aut, cre] , Kuangyu Wen [ctb]


Documentation:   PDF Manual  


GPL-3 license


Imports lattice, locfit, qrng, Rcpp, graphics, grDevices, stats, utils, quadprog

Suggests R.rsp, VineCopula, testthat

Linking to Rcpp, RcppArmadillo


Imported by VineCopula, kdevine.


See at CRAN