qnvmix {nvmix}R Documentation

Quantile Function of a univariate Normal Variance Mixture Distribution

Description

Evaluating multivariate normal variance mixture distribution functions (including normal and Student t for non-integer degrees of freedom).

Usage

qnvmix(u, qmix, control = list(),
       verbose = TRUE, q.only = FALSE, stored.values = NULL, ...)

Arguments

u

vector of probabilities .

qmix

specification of the mixing variable W; see McNeil et al. (2015). Supported are the following types of specification (see also the examples below):

character:

a character string specifying a supported distribution; currently available are "constant" (in which case W = 1 and thus qnorm is called) and "inverse.gamma" (in which case W is an inverse gamma distribution with shape and rate parameters df/2 and qt(..., df = df) is called; note that df needs to be provided via the ellipsis argument then; see the examples below).

list:

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

function:

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

control

list specifying algorithm specific parameters; see details below.

verbose

logical, if TRUE a warning is printed if one of the 'abstol' is not reached.

q.only

logical. If TRUE, only the quantiles are returned; if FALSE, see Section 'value' below.

stored.values

matrix with 3 columns of the form [x, F(x), logf(x)] where F and logf are the df and log-density of the distribution specified in 'qmix'. If provided it will be used to determine starting values for the internal newton proceudure. Only very basic checking is done.

...

additional arguments containing parameters of mixing distributions when mix is a character string.

Details

This function uses a Newton procedure to estimate the quantile of the specified univariate normal variance mixture distribution. Internally, a randomized quasi-Monte Carlo (RQMC) approach is used to estimate the distribution and (log)density function; the method is similar to the one in pnvmix and dnvmix. The result depends slightly on .random.seed.

Internally, symmetry is used for u ≤ 0.5. Function values (i.e. cdf and log-density values) are stored and reused to get good starting values. These values are returned if q.only = FALSE and can be re-used by passing it to qnvmix via the argument stored.values; this can significantly reduce run-time.

Accuracy and run-time depend on both the magnitude of u and on how heavy the tail of the underlying distributions is. Numerical instabilities can occur for values of u close to 0 or 1, especially when the tail of the distribution is heavy.

If q.only = TRUE the log-density values of the underlying distribution evaluated at the estimated quantiles are returned as well: This can be useful for copula density evaluations where both quantities are needed.

method

character string indicating the method to be used to compute the integral. Available are:

"sobol":

Sobol' sequence (default).

"ghalton":

generalized Halton sequence.

"PRNG":

plain Monte Carlo based on a pseudo-random number generator.

abstol.cdf

abstol to estimate the df F(x) internally. See also ?pnvmix.

abstol.logdensity

abstol to estimate the log-density logf(x) internally. See also ?dnvmix.

abstol.newton

Convergence criterion for the internal Newton method.

max.iter.newton

Maximum number of iterations for the internal Newton method for *each* entry of u

max.iter.rqmc

numeric, providing the maximum number of iterations allowed in the RQMC approach; the default is 15.

CI.factor

multiplier of the Monte Carlo confidence interval bounds. The algorithm runs until CI.factor times the estimated standard error is less than abstol. If CI.factor = 3.3 (the default), one can expect the actual absolute error to be less than abstol in 99.9% of the cases.

n0

Size of initial point-set used to internally approximate the df.

B

number of randomizations for obtaining an error estimate in the randomized quasi-Monte Carlo (RQMC) approach; the default is 8.

Care should be taken when changing the algorithm-specific parameters, notably method, precond, fun.eval[2] and B. Error estimates will not be reliable for too small B and the performance of the algorithm depends heavily on the (quasi-)Monte Carlo point-set used.

Value

If q.only = TRUE a vector of the same length as u with entries q_i where q_i satisfies q_i = inf_x { F(x) ≥ u_i} where F(x) the univariate df of the normal variance mixture specified via qmix;

if q.only = FALSE a list of four:

$q:

Vector of quantiles

$log.density:

Vector log-density values at q

$computed.values:

matrix with 3 columns [x, F(x), logf(x)]; see details above

$newton.iterations:

Vector giving the number of Newton iterations needed for u[i]

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(), rnvmix(), pnvmix()

Examples

### Examples for qnvmix() ####################################################

## Evaluation points
u <- seq(from = 0.05, to = 0.95, by = 0.1)
set.seed(271) # for reproducibility

## Evaluate the t_{1.4} quantile function
df = 1.4
qmix. <- function(u) 1/qgamma(u, shape = df/2, rate = df/2)
## If qmix = "inverse.gamma", qt() is being called 
qt1  <- qnvmix(u, qmix = "inverse.gamma", df = df)
## Estimate quantiles (without using qt())
qt1. <- qnvmix(u, qmix = qmix.)
stopifnot(all.equal(qt1$q, qt1.$q, tolerance = 5e-4))
## Look at absolute error:
abs.error <- abs(qt1$q - qt1.$q)
plot(u, abs.error, type = "l", xlab = "u", ylab = "qt(u)")
## Now do this again but provide qt1.$stored.values, in which case at most
## one Newton iteration will be needed:
qt2 <- qnvmix(u, qmix = qmix., stored.values = qt1.$computed.values)
stopifnot(max(qt2$newton.iterations) <= 1)


## Evaluate quantile function where W~Exp(2)
rate = 2
qexp <- qnvmix(u, qmix = list("exp", rate = rate))
## Check: F( F^{-1}(u)) = u 
stopifnot(all.equal(pnvmix(as.matrix(qexp$q), qmix = list("exp", rate = rate)), u, 
                    tolerance = 5e-4, check.attributes = FALSE))

[Package nvmix version 0.0-2 Index]