sens.control: Returns Control Parameters To Find Maximum of The Sensitivity...

Description Usage Arguments Details Note Examples

View source: R/1-UserCommonFunctions.R

Description

It returns some arguments of the nloptr function including the list of control parameters. This function is used to find the maximum of the sensitivity (derivative) function over the design space in order to calculate the efficiency lower bound (ELB).

Usage

1
2
3
4
5
6
sens.control(
  x0 = NULL,
  optslist = list(stopval = -Inf, algorithm = "NLOPT_GN_DIRECT_L", xtol_rel = 1e-08,
    ftol_rel = 1e-08, maxeval = 1000),
  ...
)

Arguments

x0

Vector of starting values for maximizing the sensitivity (derivative) function over the design space x. It will be passed to the optimization function nloptr.

optslist

A list. It will be passed to the argument opts of the function nloptr to find the maximum of the sensitivity function over the design space. See 'Details'.

...

Further arguments will be passed to nl.opts from package nloptr.

Details

ELB is a measure of proximity of a design to the optimal design without knowing the latter. Given a design, let ε be the global maximum of the sensitivity (derivative) function with respect the vector of the model predictors x over the design space. ELB is given by

ELB = p/(p + ε),

where p is the number of model parameters. Obviously, calculating ELB requires finding ε and therefore, a maximization problem to be solved. The function nloptr is used here to solve this maximization problem. The arguments x0 and optslist will be passed to this function as follows:

Argument x0 provides the user initial values for this maximization problem and will be passed to the argument with the same name in the function nloptr.

Argument optslist will be passed to the argument opts of the function nloptr. optslist is a list and the most important components are listed as follows:

stopval

Stop minimization when an objective value <= stopval is found. Setting stopval to -Inf disables this stopping criterion (default).

algorithm

Defaults to NLOPT_GN_DIRECT_L. DIRECT-L is a deterministic-search algorithm based on systematic division of the search domain into smaller and smaller hyperrectangles.

xtol_rel

Stop when an optimization step (or an estimate of the optimum) changes every parameter by less than xtol_rel multiplied by the absolute value of the parameter. Criterion is disabled if xtol_rel is non-positive.

ftol_rel

Stop when an optimization step (or an estimate of the optimum) changes the objective function value by less than ftol_rel multiplied by the absolute value of the function value. Criterion is disabled if ftol_rel is non-positive.

maxeval

Stop when the number of function evaluations exceeds maxeval. Criterion is disabled if maxeval is non-positive.

For more details, see ?nloptr::nloptr.print.options.

Note

ELB must be 0 <=ELB <= 1. When the computed ELB is larger than one (equivalently ε is negative), it may be a signal that the obtained ε is not the global maximum. To overcome this issue, please increase the value of the parameter maxeval to allow the optimization algorithm to find the global maximum of the sensitivity (derivative) function over the design space.

Examples

1
2
sens.control()
sens.control(optslist = list(maxeval = 1000))

ICAOD documentation built on Oct. 23, 2020, 6:40 p.m.

Related to sens.control in ICAOD...