nlopt.ui: Function for the determination of the population thresholds...

In UncertainInterval: Uncertain Interval Methods for Three-Way Cut-Point Determination in Test Results

Description

Function for the determination of the population thresholds an uncertain and inconclusive interval for bi-normal distributed test scores.

Usage

nlopt.ui(
  UI.Se = 0.55,
  UI.Sp = 0.55,
  mu0 = 0,
  sd0 = 1,
  mu1 = 1,
  sd1 = 1,
  intersection = NULL,
  start = NULL,
  print.level = 0
)

Arguments

UI.Se	(default = .55). Desired sensitivity of the test scores within the uncertain interval. A value <= .5 is not allowed.
UI.Sp	(default = .55). Desired specificity of the test scores within the uncertain interval. A value <= .5 is not allowed.
mu0	Population value or estimate of the mean of the test scores of the persons without the targeted condition (controls).
sd0	Population value or estimate of the standard deviation of the test scores of the persons without the targeted condition (controls).
mu1	Population value or estimate of the mean of the test scores of the persons with the targeted condition (patients).
sd1	Population value or estimate of the standard deviation of the test scores of the persons with the targeted condition (patients).
intersection	Default NULL. If not null, the supplied value is used as the estimate of the intersection of the two bi-normal distributions. Otherwise, it is calculated.
start	Default NULL. If not null, the first two values of the supplied vector are used as the starting values for the nloptr optimization function.
print.level	Default is 0. The option print.level controls how much output is shown during the optimization process. Possible values: 0) (default) no output; 1) show iteration number and value of objective function; 2) 1 + show value of (in)equalities; 3) 2 + show value of controls.

Details

The function can be used to determinate the uncertain interval of two bi-normal distributions. The Uncertain Interval is defined as an interval below and above the intersection of the two distributions, with a sensitivity and specificity below a desired value (default .55).

Only a single intersection is assumed (or a second intersection where the overlap is negligible).

From version 0.7 onwards, mu0 can be larger than mu1. In earlier versions correct (but negative) results could be obtained only when -mu0 and -mu1 were used.

The function uses an optimization algorithm from the nlopt library (https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/): the sequential quadratic programming (SQP) algorithm for nonlinear constrained gradient-based optimization (supporting both inequality and equality constraints), based on the implementation by Dieter Kraft (1988; 1944).

Value

List of values:

$status:

Integer value with the status of the optimization (0 is success).

$message:

More informative message with the status of the optimization

$results:

Vector with the following values:

• exp.UI.Sp: The population value of the specificity in the Uncertain Interval, given mu0, sd0, mu1 and sd1. This value should be very near the supplied value of Sp.

• exp.UI.Se: The population value of the sensitivity in the Uncertain Interval, given mu0, sd0, mu1 and sd1. This value should be very near the supplied value of UI.Se.

• mu0: The value that has been supplied for mu0.

• sd0: The value that has been supplied for sd0.

• mu1: The value that has been supplied for mu1.

• sd1: The value that has been supplied for sd1.

$solution:

Vector with the following values:

• L: The population value of the lower threshold of the Uncertain Interval.

• U: The population value of the upper threshold of the Uncertain Interval.

References

Dieter Kraft, "A software package for sequential quadratic programming", Technical Report DFVLR-FB 88-28, Institut für Dynamik der Flugsysteme, Oberpfaffenhofen, July 1988.

Dieter Kraft, "Algorithm 733: TOMP–Fortran modules for optimal control calculations," ACM Transactions on Mathematical Software, vol. 20, no. 3, pp. 262-281 (1994).

Examples

# A simple test model:
nlopt.ui()
# Using another bi-normal distribution:
nlopt.ui(mu0=0, sd0=1, mu1=1.6, sd1=2)
nlopt.ui(mu0=0, sd0=1, mu1=1.6, sd1=2)
nlopt.ui(mu0=-1.6, sd0=2, mu1=0, sd1=1)
# The example below (with mu0 > mu1) works correctly from version 0.7 onward
nlopt.ui(mu0=1.6, sd0=2, mu1=0, sd1=1)

UncertainInterval documentation built on March 3, 2021, 1:10 a.m.