copula {nvmix}R Documentation

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 via a quantile function; see McNeil et al. (2015, Chapter 6). This argument is required for method = "sobol" and method = "ghalton". Supported are the following types of specification (see also the examples below):

character:

character string specifying a supported distribution; currently available are "constant" (in which case W = 1 and thus a sample from the multivariate normal distribution with mean vector loc and covariance matrix scale results) and "inverse.gamma" (in which case W is inverse gamma distributed with shape and rate parameters df/2 and thus the multivariate Student t distribution with df degrees of freedom (required to be provided via the ellipsis argument) results).

list:

list of length at least one, where the first component is a character string specifying the base name of a distribution which can be sampled via prefix "q"; an example is "exp" for which "qexp" exists for sampling. If the list is of length larger than one, the remaining elements contain additional parameters of the distribution; for "exp", for example, this can be the parameter rate.

function:

function interpreted as the quantile function of the mixing variable W; internally, sampling is then done with the inversion method by applying the provided function to U(0,1) random variates.

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 != 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.

Details

... to come ...

Value

... to come ...

Author(s)

Erik Hintz, Marius Hofert and Christiane Lemieux

References

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

See Also

dnvmix(), pnvmix(), qnvmix()

Examples

set.seed(42) # for reproducibility 

## Generate a random correlation matrix in d dimensions
d <- 2 # dimension
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 = 5e-4, 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 = 5e-4, 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) # providing scale
set.seed(1)
X. <- rnvmixcop(n, qmix = "inverse.gamma", df = df, factor = t(chol(P))) # providing the factor
stopifnot(all.equal(X, X.))

[Package nvmix version 0.0-2 Index]