thres3 {ThresholdROC}

Threshold point estimation and confidence intervals (three-state setting)

Description

This function calculates the threshold estimates and their corresponding confidence intervals in a three-state setting.

Usage

thres3(k1, k2, k3, rho,
  costs = matrix(c(0, 1, 1, rho[1]/rho[2], 0, rho[3]/rho[2], 1, 1, 0),
  3, 3, byrow = TRUE), dist1 = "norm", dist2 = "norm",
  dist3 = "norm", start = NULL, ci = TRUE, ci.method = c("param", "boot"),
  B = 1000, alpha = 0.05, na.rm = FALSE)

Arguments

k1

vector containing the first sample values.

k2

vector containing the second sample values.

k3

vector containing the third sample values.

rho

3-dimensional vector of prevalences.

costs

cost matrix. Costs should be entered as a 3x3 matrix, where the first row corresponds to the costs associated with the classification of subjects in state 1 (C11, C12 and C13), second row corresponds to the costs associated with the classification of subjects in state 2 (C21, C22 and C23) and the third row corresponds to the costs associated with classification of subjects in state 3 (C31, C32, C33), where Cij is the cost of classifying an individual of class i as class j. Default cost values are a combination of costs that leads to the same thresholds as the Youden index method (see References for details).

dist1

distribution to be assumed for the first population. Default, "norm". See Details.

dist2

distribution to be assumed for the second population. Default, "norm". See Details.

dist3

distribution to be assumed for the third population. Default, "norm". See Details.

start

when the three distributions dist1, dist2 and dist3 are "norm", a 2-dimensional vector containing starting values for the thresholds. The authors recommend to use the mean of the distribution with lower values and the mean of the distribution with higher values. If any distribution is not "norm", this parameter is ignored. See Details.

ci

should a confidence interval be calculated? Default, TRUE. The user can set it to FALSE to supress the calculation of any confidence interval (in that case, arguments ci.method, B and alpha are ignored).

ci.method

method to be used for the confidence intervals calculation. The user can specify just the initial letters. Default, "param". See Details.

B

number of bootstrap resamples when ci.method = "boot". Otherwise, ignored. Default, 1000.

alpha

significance level for the confidence interval. Default, 0.05.

na.rm

a logical value indicating whether NA values in k1, k2 and k3 should be stripped before the computation proceeds. Default, FALSE.

Details

Parameters dist1, dist2 and dist3 can be chosen between the following 2-parameter distributions: "beta", "cauchy", "chisq" (chi-squared), "gamma", "lnorm" (lognormal), "logis" (logistic), "norm" (normal) and "weibull".

For parameter ci.method the user can choose between "param" (parametric confidence intervals are calculated when assuming a trinormal underlying model) and "boot" (the confidence intervals are calculated by bootstrap).

When at least one of the distributions is not "norm", the function internally uses the thresTH3() function, which requires two intervals in which the two thresholds are expected to be found. These intervals are determined by the default values of thresTH3(). When all the distributions are "norm", the function uses the nlm() function, which requires two starting values (passed through the argument start).

Value

An object of class thres3, which is a list with two components:

T

a list of at least ten components:

thres1 first threshold estimate.

thres2 second threshold estimate.

prev prevalences provided by the user.

costs cost matrix provided by the user.

k1 vector containing the first sample values provided by the user.

k2 vector containing the second sample values provided by the user.

k3 vector containing the third sample values provided by the user.

dist1 distribution assumed for the first population.

dist2 distribution assumed for the second population.

dist3 distribution assumed for the third population.

When not all distributions are normal, T also contains:

pars1 a numeric vector containing the estimation of the parameters of dist1.

pars2 a numeric vector containing the estimation of the parameters of dist2.

pars3 a numeric vector containing the estimation of the parameters of dist3.

CI

When ci.method = "param", a list of six components:

lower1 the lower limit of the confidence interval for the first threshold.

upper1 the upper limit of the confidence interval for the first threshold.

lower2 the lower limit of the confidence interval for the second threshold.

upper2 the upper limit of the confidence interval for the second threshold.

alpha significance level provided by the user.

ci.method method used for the confidence intervals calculation.

When ci.method = "boot", a list of eleven components:

low.norm1 the lower limit of the bootstrap confidence interval for the first threshold based on the normal distribution.

up.norm1 the upper limit of the bootstrap confidence interval for the first threshold based on the normal distribution.

low.norm2 the lower limit of the bootstrap confidence interval for the second threshold based on the normal distribution.

up.norm2 the upper limit of the bootstrap confidence interval for the second threshold based on the normal distribution.

low.perc1 the lower limit of the bootstrap confidence interval for the first threshold based on percentiles.

up.perc1 the upper limit of the bootstrap confidence interval for the first threshold based on percentiles.

low.perc2 the lower limit of the bootstrap confidence interval for the second threshold based on percentiles.

up.perc2 the upper limit of the bootstrap confidence interval for the second threshold based on percentiles.

alpha significance level.

B number of bootstrap resamples.

ci.method method used for the confidence intervals calculation.

When ci = FALSE, NULL.

Note

It is assumed that k1 is the sample with lower values and k3 is the one taking higher values. If that is not the case, k1, k2 and k3 (and the corresponding parameters) are re-ordered as needed.

References

Efron B, Tibshirani RJ. (1993). An introduction to the bootstrap, Chapman & Hall.

Skaltsa K, Jover L, Fuster D, Carrasco JL. (2012). Optimum threshold estimation based on cost function in a multistate diagnostic setting. Statistics in Medicine, 31:1098-1109.

See Also

thresTH3, plot.thres3, lines.thres3

Examples

set.seed(1234)
n <- 100
k1 <- rlnorm(n)
k2 <- rnorm(n, 3, 1)
k3 <- rnorm(n, 5, 1)
rho <- c(1/3, 1/3, 1/3)

# assuming trinormality
start <- c(mean(k1), mean(k3))
thres3(k1, k2, k3, rho, dist1="norm", dist2="norm", dist3="norm", start=start, ci.method="param") 

# not assuming trinormality
thres3(k1, k2, k3, rho, B=1000, ci.method="boot", dist1="lnorm", dist2="norm", dist3="norm")

# supress confidence intervals calculation
thres3(k1, k2, k3, rho, ci=FALSE, dist1="lnorm", dist2="norm", dist3="norm")