nvmix (version 0.0-3)

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

dnvmixcop(u, qmix, scale = diag(d), factor = NULL, control = list(),
          verbose = FALSE, log = FALSE, ...)
pnvmixcop(u, qmix, scale = diag(d), control = list(),
          verbose = FALSE, ...)
rnvmixcop(n, qmix, scale = diag(2), factor = NULL,
          method = c("PRNG", "sobol", "ghalton"), skip = 0,
          control = list(), verbose = FALSE, ...)

Arguments

u

\((n, d)\)-matrix of evaluation points. Have to be in \((0,1)\).

n

sample size \(n\) (positive integer).

qmix

specification of the mixing variable \(W\); see pnvmix() for details and examples.

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 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 \neq d\) can be used to sample from singular normal variance mixtures. For dnvmixcop(), 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).

method

character string indicating the method to be used to obtain the sample. Available are:

"PRNG":

pseudo-random numbers,

"sobol":

Sobol' sequence,

"ghalton":

generalized Halton sequence.

If method = "PRNG", either qmix or rmix can be provided. If both are provided, rmix is used and qmix ignored. For the other two methods, sampling is done via inversion, hence qmix has to be provided and rmix is ignored.

skip

integer specifying the number of points to be skipped when method = "sobol", see also example below.

control

list specifying algorithm specific parameters; see details below.

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.

Value

The values returned by dnvmixcop(), rnvmixcop() and pnvmixcop() are similar to the ones returned by their non-copula alternatives dnvmix(), rnvmix() and pnvmix().

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.

References

Hintz, E., Hofert, M. and Lemieux, C. (2019), 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.

See Also

dnvmix(), pnvmix(), qnvmix(), rnvmix()

Examples

# NOT RUN {
## 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 dnvmixcop() ####################################################

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


### Example for pnvmixcop() ####################################################

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


### Examples for rnvmixcop() ###################################################

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