nvmix: copula – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

copula

Functionalities for Normal Variance Mixture Copulas

Description

Evaluate the density / distribution function of normal variance mixture copulas (including Student t and normal copula) and generate vectors of random variates from normal variance mixture copulas.

Usage

dnvmixcopula(u, qmix, scale = diag(d), factor = NULL, control = list(),
             verbose = FALSE, log = FALSE, ...)
pnvmixcopula(upper, lower = matrix(0, nrow = n, ncol = d), qmix, scale = diag(d), 
             control = list(), verbose = FALSE, ...)
rnvmixcopula(n, qmix, scale = diag(2), factor = NULL,
             method = c("PRNG", "sobol", "ghalton"), skip = 0,
             control = list(), verbose = FALSE, ...)
          
dStudentcopula(u, df, scale = diag(d), factor = NULL, log = FALSE, verbose = TRUE)
pStudentcopula(upper, lower = matrix(0, nrow = n, ncol = d), df, scale = diag(d), 
               control = list(), verbose = TRUE)
rStudentcopula(n, df, scale = diag(2), method = c("PRNG", "sobol", "ghalton"), 
               skip = 0)
            
pgStudentcopula(upper, lower = matrix(0, nrow = n, ncol = d), groupings = 1:d,
                df, scale = diag(d), control = list(), verbose = TRUE)
dgStudentcopula(u, groupings = 1:d, df, scale = diag(d), factor = NULL, 
                factor.inv = NULL, control = list(), verbose = TRUE, log = FALSE)        
rgStudentcopula(n, groupings = 1:d, df, scale = diag(2), factor = NULL, 
                method = c("PRNG", "sobol", "ghalton"), skip = 0)
                                                                                        
fitgStudentcopula(x, u, df.init = NULL, scale = NULL, groupings = rep(1, d), 
                  df.bounds = c(0.5, 30), control = list(), verbose = TRUE)

Arguments

`u`	(n, d)-`matrix` of evaluation points or data; Have to be in (0,1).
`upper, lower`	(n, d)-`matrix` of upper/lower evaluation limits. Have to be in (0,1).
`n`	sample size n (positive integer).
`qmix`	specification of the mixing variable W; see `pnvmix()` for the ungrouped and `pgnvmix()` for the grouped case.
`groupings`	see `pgnvmix()`.
`df`	positive degress of freedom; can also be `Inf` in which case the copula is interpreted as the Gaussian copula.
`scale`	scale matrix (a covariance matrix entering the distribution as a parameter) of dimension (d, d) (defaults to d = 2); this equals the covariance matrix of a random vector following the specified normal variance mixture distribution divided by the expecation of the mixing variable W if and only if the former exists. Note that `scale` must be positive definite; sampling from singular ungrouped normal variance mixtures can be achieved by providing `factor`.
`factor`	(d, k)-`matrix` such that `factor %% t(factor)` equals `scale`; the non-square case k != d* can be used to sample from singular normal variance mixtures. For `dnvmixcopula()`, this has to be a square matrix. Note that this notation coincides with McNeil et al. (2015, Chapter 6). If not provided, `factor` is internally determined via `chol()` (and multiplied from the right to an (n, k)-matrix of independent standard normals to obtain a sample from a multivariate normal with zero mean vector and covariance matrix `scale`).
`factor.inv`	inverse of `factor`; if not provided, computed via `solve(factor)`.
`method`	see `rnvmix()`.
`skip`	see `rnvmix()`.
`df.init`	`NULL` or vector with initial estimates for `df`; can contain NAs.
`df.bounds`	2-`vector` with the lower/upper bounds on the degree-of-freedom parameter for the fitting.
`x`	(n, d)-`matrix` data matrix of which the underlying copula is to be estimated. See also details below.
`control`	`list` specifying algorithm specific parameters; see `get_set_param()`.
`verbose`	`logical` indicating whether a warning is given if the required precision `abstol` has not been reached.
`log`	`logical` indicating whether the logarithmic density is to be computed.
`...`	additional arguments (for example, parameters) passed to the underlying mixing distribution when `rmix` or `qmix` is a `character` string or `function`.

Details

Functionalities for normal variance mixture copulas provided here essentially call pnvmix(), dnvmix() and rnvmix() as well as qnvmix(), see their documentations for more details.

We remark that computing normal variance mixtures is a challenging task; evaluating normal variance mixture copulas additionally requires the approximation of a univariate quantile function so that for large dimensions and sample sizes, these procedures can be fairly slow. As there are approximations on many levels, reported error estimates for the copula versions of pnvmix() and dnvmix() can be flawed.

The functions [d/p/r]Studentcopula() are user-friendly wrappers for [d/p/r]nvmixcopula(, qmix = "inverse.gamma"), designed for the imporant case of a t copula with degrees-of-freedom df.

The function fitgStudentcopula() can be used to estimate the matrix scale and the degrees-of-freedom for grouped t-copulas. The matrix scale, if not provided, is estimated non-parametrically. Initial values for the degrees-of-freedom are estimated for each group separately (by fitting the corresponding marginal t copula). Using these initial values, the joint likelihood over all (length(unique(groupings))-many) degrees-of-freedom parameters is optimized via optim(). For small dimensions, the results are satisfactory but the optimization becomes extremely challenging when the dimension is large, so care should be taking when interpreting the results.

Value

The values returned by dnvmixcopula(), rnvmixcopula() and pnvmixcopula() are similar to the ones returned by their non-copula alternatives dnvmix(), rnvmix() and pnvmix().

The function fitgStudentcopula() returns an S3 object of class "fitgStudentcopula", basically a list which contains, among others, the components

df: Estimated degrees-of-freedom for each group.
scale: Estimated or provided scale matrix.
max.ll: Estimated log-likelihood at reported estimates.
df.init: Initial estimate for the degrees-of-freedom.

The methods print() and summary() are defined for the class "fitgStudentcopula".

Author(s)

Erik Hintz, Marius Hofert and Christiane Lemieux

References

Hintz, E., Hofert, M. and Lemieux, C. (2020), Normal variance mixtures: Distribution, density and parameter estimation. https://arxiv.org/abs/1911.03017.

McNeil, A. J., Frey, R. and Embrechts, P. (2015). Quantitative Risk Management: Concepts, Techniques, Tools. Princeton University Press.

Luo, X. and Shevchenko, P. (2010). The t copula with multiple parameters of degrees of freedom: bivariate characteristics and application to risk management. Quantitative Finance 10(9), 1039-1054.

Daul, S., De Giorgi, E. G., Lindskog, F. and McNeil, A (2003). The grouped t copula with an application to credit risk. Available at SSRN 1358956.

Examples

## Generate a random correlation matrix in d dimensions
d <- 2 # dimension
set.seed(42) # for reproducibility
rho <- runif(1, min = -1, max = 1)
P <- matrix(rho, nrow = d, ncol = d) # build the correlation matrix P
diag(P) <- 1
## Generate two random evaluation points:
u <- matrix(runif(2*d), ncol = d)
## We illustrate using a t-copula
df = 2.1
## Define quantile function which is inverse-gamma here:
qmix. <- function(u) 1/qgamma(1-u, shape = df/2, rate = df/2)


### Example for dnvmixcopula() ####################################################

## If qmix = "inverse.gamma", dnvmix() calls qt and dt:
d1 <- dnvmixcopula(u, qmix = "inverse.gamma", scale = P, df = df)
## Same can be obtained using 'dStudentcopula()'
d2 <- dStudentcopula(u, scale = P, df = df)
stopifnot(all.equal(d1, d2))
## Use qmix. to force the algorithm to use a rqmc procedure:
d3 <- dnvmixcopula(u, qmix = qmix., scale = P)
stopifnot(all.equal(d1, d3, tol = 1e-3, check.attributes = FALSE))


### Example for pnvmixcopula() ####################################################

## Same logic as above:
p1 <- pnvmixcopula(u, qmix = "inverse.gamma", scale = P, df = df)
p2 <- pnvmixcopula(u, qmix = qmix., scale = P)
stopifnot(all.equal(p1, p2, tol = 1e-3, check.attributes = FALSE))


### Examples for rnvmixcopula() ###################################################

## Draw random variates and compare
n <- 60
set.seed(1)
X  <- rnvmixcopula(n, qmix = "inverse.gamma", df = df, scale = P) # with scale
set.seed(1)
X. <- rnvmixcopula(n, qmix = "inverse.gamma", df = df, factor = t(chol(P))) # with factor
stopifnot(all.equal(X, X.))


### Example for the grouped case ##################################################

d <- 4 # dimension
set.seed(42) # for reproducibility
P <- matrix(runif(1, min = -1, max = 1), nrow = d, ncol = d) # build the correlation matrix P
diag(P) <- 1
groupings <- c(1, 1, 2, 2) # two groups of size two each 
df <- c(1, 4) # dof for each of the two groups
U <- rgStudentcopula(n, groupings = groupings, df = df, scale = P)
(fit <- fitgStudentcopula(u = U, groupings = groupings, verbose = FALSE))

nvmix

Multivariate Normal Variance Mixtures

v0.0-5

GPL (>= 3) | file LICENCE

Authors

Marius Hofert [aut, cre], Erik Hintz [aut], Christiane Lemieux [aut]

Initial release