# Functionalities for Normal Variance Mixture Copulas 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. ```r 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), fit.method = c("joint-MLE", "groupewise-MLE"), control = list(), verbose = TRUE) fitStudentcopula(u, fit.method = c("Moment-MLE", "EM-MLE", "Full-MLE"), df.init = NULL, df.bounds = c(0.1, 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. - `fit.method`: `character` indicating which fitting method is to be used; see details below. - `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`. ## Returns 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"`. ## 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. ## Author(s) Erik Hintz, Marius Hofert and Christiane Lemieux ## References Hintz, E., Hofert, M. and Lemieux, C. (2020), Grouped Normal Variance Mixtures. **Risks** 8(4), 103. Hintz, E., Hofert, M. and Lemieux, C. (2021), Normal variance mixtures: Distribution, density and parameter estimation. **Computational Statistics and Data Analysis** 157C, 107175. Hintz, E., Hofert, M. and Lemieux, C. (2022), Multivariate Normal Variance Mixtures in : The Package nvmix. **Journal of Statistical Software**, tools:::Rd_expr_doi("10.18637/jss.v102.i02") . 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**. ## See Also `dnvmix()`, `pnvmix()`, `qnvmix()`, `rnvmix()` ## Examples ```r ## 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)) ```

copula function