get_set_param: Algorithm-specific Parameters
In nvmix: Multivariate Normal Variance Mixtures

get_set_param

R Documentation

Algorithm-specific Parameters

Description

Algorithm specific parameters for functionalities in the nvmix package, notably for fitnvmix(), dnvmix(), pnvmix(), qnvmix(), pgammamix(), dgammamix() and ES_nvmix() as well as the corresponding functions for grouped mixtures.

Usage

get_set_param(control = list())

Arguments

control

list specifying algorithm specific parameters to beset; see below under details.

Details

For most functions in the nvmix package, internally, an iterative randomized Quasi-Monte Carlo (RQMC) approach is used to estimate probabilities, weights and (log-)densities. There are various parameters of underlying methods than can be changed.

Algorithm specific parameters can be passed as a list via control. It can contain any of the following:

For all algorithms:

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.

increment

character string indicating how the sample size should be increased in each iteration. Available are:

"doubling":: next iteration has as many sample points as all the previous iterations combined,
"num.init":: all iterations use an additional fun.eval[1]-many points (default for most functions).

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 or reltol (whichever is provided). If CI.factor = 3.5 (the default), one can expect the actual absolute error to be less than abstol in 99.9% of the cases.

fun.eval

numeric(2) providing the size of the first point set to be used to estimate integrals (typically a power of 2) and the maximal number of function evaluations. fun.eval defaults to c(2^7, 1e12).

max.iter.rqmc

numeric, providing the maximum number of iterations allowed in the RQMC approach; the default is 15 if increment = "doubling" and 1250 otherwise.

B

number of randomizations for obtaining an error estimate in the RQMC approach; the default is 15.

For pnvmix() and pgnvmix():

pnvmix.abstol, pnvmix.reltol: non-negative numeric providing the relative/absolute precision required for the distribution function. Relative precision via pnvmix.reltol is only used when pnvmix.abstol = NA; in all other cases, absolute precision will be used. pnvmix.abstol defaults to 1e-3. If pnvmix.abstol = 0 and pnvmix.reltol = 0, the algorithm will typically run until the total number of function evaluations exceeds fun.eval[2] or until the total number of iterations exeeds max.iter.rqmc, whichever happens first. If n > 1 (so upper has more than one row), the algorithm runs until the precision requirement is reached for all n probability estimates.
mean.sqrt.mix: expectation of the square root \sqrt(W) of the mixing variable W. If NULL, it will be estimated via QMC; this is only needed for determining the reordering of the integration bounds, so a rather crude approximation is fine.
precond: logical indicating whether preconditioning is applied, that is, reordering of the integration variables. If TRUE, integration limits lower, upper as well as scale are internally re-ordered in a way such that the overall variance of the integrand is usually smaller than with the original ordering; this usually leads smaller run-times.
cholesky.tol: non-negative numeric providing lower threshold for non-zero elements in the computation of the cholesky factor: If calculated C(i,i)^2 < | cholesky.tol * Scale(i,i)|, the diagonal element (and all other elements in column i) of the cholesky factor C are set to zero, yielding a singular matrix. cholesky.tol defaults to 1e-9.

For dnvmix() and dgnvmix():

dnvmix.reltol, dnvmix.abstol: non-negative numeric providing the relative/absolute precision for the *log-* density required. Absolute precision via dnvmix.abstol is only used when dnvmix.reltol = NA; in all other cases, relative precision will be used. dnvmix.reltol defaults to 1e-2. If dnvmix.reltol=0 and dnvmix.abstol=0, the algorithm will typically run until the total number of function evaluations exceeds fun.eval[2] or until the total number of iterations exeeds max.iter.rqmc, whichever happens first. If n > 1 (so x has more than one row), the algorithm runs until the precision requirement is reached for all n log-density estimates.
dnvmix.doAdapt: logical indicating if an adaptive integration procedure shall be used that only samples in relevant subdomains of the mixing variable; defaults to TRUE.
dnvmix.max.iter.rqmc.pilot: numeric, providing the maximum number of unstratified, non-adaptive pilot runs the internal integration procedure performs. Defaults to 6.
dnvmix.tol.int.lower, dnvmix.order.lower: both numeric and nonnegative. RQMC integration is only performed where the integrand is > than the maximum of dnvmix.tol.int.lower and 10^{-c} g_{max}, where g_{max} is the theoretical maximum of the integrand and c is the specified dnvmix.order.lower. Default to 1e-100 and 5, respectively.
dnvmix.tol.bisec: numeric vector of length 3 specifying bisection tolerances in the adaptive RQMC algorithm. First/second/third element specify the tolerance on u, W and the log-integrand and default to 1e-6, 1e-1 and 1e-1, respectively.
dnvmix.max.iter.bisec: numeric, maximum number of iterations in the internal bisection procedure to find good cutting points allowed, defaults to 15.
dnvmix.tol.stratlength: numeric, nonnegative. If the stratum found by the adaptive integration method has length > dnvmix.tol.stratlength RQMC integration is used there; otherwise a crude approximation. Defaults to 1e-50.

For fitnvmix():

ECMEstep: logical, if TRUE (default), ECME iteration is performed; if FALSE, no ECME step is performed so that fitnvmix() performs between zero and two optimizations over nu, depending on laststep.do.nu and whether nu.init was provided.
ECMEstep.do.nu: logical, if TRUE (default), the likelihood is maximized over nu in each ECME iteration; if FALSE, this step is omitted.
laststep.do.nu: logical, if TRUE another last maximization of the likelihood over nu is performed using all observations after the ECME iterations. Only makes sense if either ECMEstep.do.nu=FALSE or if size.subsample is smaller than the number of observations. Defaults to FALSE.
resample: logical, if TRUE, a different subsample of x is taken in each optimization over nu in the ECME iterations. Only relevant when size.subsample is smaller than the number of observations. Defaults to FALSE.
ECME.miniter, ECME.maxiter: numeric positive, minimum and maximum number of ECME iterations. Default to 5 and 200, respectively.
max.iter.locscaleupdate: numeric positive. Maximum number of location-scale updates (while helding nu fixed) in each individual ECME iteration; defaults to 50.
weights.reltol: numeric non-negative. Relative tolerance to estimate internal weights used to update loc and scale estimates in the ECME iterations. Defaults to 1e-2.
weights.interpol.reltol: numeric non-negative. Some weights can be obtained by interpolating previously calculated weights; if the maximal relative interpolation error is smaller than weights.interpol.reltol, this is done. Defaults to 1e-2.
ECME.rel.conv.tol: numeric(3) vector specifying relative convergence tolerances for loc, scale and nu (in this order). Defaults to c(1e-2, 1e-2, 1e-3).
control.optim: list of control parameters passed to the underlying optim in the initial step as well as in the ECME iterations. See optim() for details; defaults to list(maxit=75).
control.optim.laststep: like control.optim; this list of control arguments is passed to optim in the last-step. Only relevant when laststep.do.nu = TRUE and defaults to list() (so no defaults of optim() changed).

For qnvmix():

max.iter.newton: numeric, maximum number of Newton iterations allowed to approximate the quantile; defaults to 45.
newton.conv.abstol: numeric, convergence tolerance for the Newton proceudre; convergence is detected once the difference of estimated quantiles in two successive iterations is smaller than newton.conv.abstol; defaults to 5e-4.
newton.df.reltol: numeric, relative error tolerance for estimating the univariate distribution function; defaults to 2.5e-4.
newton.logdens.abstol: numeric, absolute error tolerance for the internal estimation of the log-density needed for the update; defaults to 1e-2.
newton.df.max.iter.rqmc: numeric, maximum number of iterations to estimate the univariate distribution function required in the Newton update; defaults to 350. Note that internally used is increment = "doubling", no matter what.

For qqplot_maha():

qqplot.df.reltol: numeric, with the same meaning as newton.df.reltol for the function qnvmix(). Defaults to 5e-3.

For ES_nvmix():

riskmeasures.abstol, riskmeasures.reltol: numeric, absolute or relative error tolerance for estimating riskmeasures, notably for ES_nvmix(). By default, riskmeasures.reltol=5e-2 and riskmeasures.abstol=NA, so that a relative tolerance is used.

Care should be taken when changing algorithm specific parameters, notably tolerances, as the accuracy of the result is heavily influenced by those.

Value

get_set_param() returns a list with more than 30 elements specifying algorithm specific parameters for the functions fitnvmix(), dnvmix(), pnvmix(), qnvmix(), pgammamix(), dgammamix() and ES_nvmix(), as well as the corresponding functions for grouped mixtures such as pgnvmix() and dgnvmix(). Parameter values passed to get_set_param() via the control argument overwrite the defaults; for parameters not specified in the control argument, the default values are being returned.

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 R: The R Package nvmix. Journal of Statistical Software, \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v102.i02")}.