ClusROC (version 1.0.3)

clus_opt_thres3: Estimation of the covariate-specific optimal pair of thresholds for clustered data.

Description

clus_opt_thres3 estimates covariate-specific optimal pair of thresholds of a continuous diagnostic test in a clustered design, with three classes of diseases.

Usage

clus_opt_thres3(
  method = c("GYI", "CtP", "MV"),
  out_clus_lme,
  newdata,
  ap_var = TRUE,
  control = list()
)

Value

clus_opt_thres3 returns an object of "clus_opt_thres3" class, which is a list containing at least the following components:

call

the matched call.

method

the methods used to obtain the estimated optimal pair of threholds.

thres3

a vector or matrix containing the estimated optimal thresholds.

thres3_se

a vector or matrix containing the estimated standard errors.

vcov_thres3

a matrix or list of matrices containing the estimated variance-covariance matrices.

tcfs

a vector or matrix containing the estimated TCFs at the optimal thresholds.

mess_order

a diagnostic message from checking the monontone ordering.

newdata

value(s) of covariate(s).

n_p

total number of regressors in the model.

Generic functions such as print and plot are also used to show the results.

Arguments

method

the method to be used. See 'Details'.

out_clus_lme

an object of class "clus_lme", i.e., a result of clus_lme call.

newdata

a data frame (containing specific value(s) of covariate(s)) in which to look for variables with which to estimate covariate-specific optimal pair of thresholds. In absence of covariate, no values have to be specified.

ap_var

logical value. If set to TRUE, the variance-covariance matrix of (estimated) covariate-specific optimal thresholds is estimated.

control

a list of control parameters. See 'Details'.

Details

This function implements estimation methods discussed in To et al. (2022) for covariate-specific optimal pair of thresholds in a clustered design with three ordinal groups. The estimators are based on the results from clus_lme function, which fits the linear mixed-effect model by using REML approach.

Before performing estimation, a check for the monotone ordering assumption is performed. This means that, for the fixed values of covariates, three predicted mean values for test results in three diagnostic groups are compared. If the assumption is not meet, the covariate-specific optimal pair of thresholds at the values of covariates are not estimated.

The estimation procedure uses three criteria. Method "GYI" is Generalized Youden Index, which maximizes the sum of three covariate-specific True Class Fractions - TCFs. Method "CtP" is based on Closest to Pefection approach. By using this method, the optimal pair of thresholds is obtained by minimizing the distance, in the unit cube, between a generic point on the covariate-specific ROC surface and the top corner (1, 1, 1). Method "MV" is based on Maximum Volume approach, which searches for thresholds that maximize the volume of a box under the covariate-specific ROC surface. The user can select more than one method. This function allows to estimate covariate-specific optimal pair of thresholds at multiple points for covariates.

The asymptotic variance-covariance matrix of the (estimated) covariate-specific optimal thresholds is estimated by using the Delta method under the normal assumption. If the Box-Cox transformation is applied to the linear mixed-effect model, a nonparametric bootstrap procedure for clustered data will be used to obtain the estimated asymptotic covariance matrix (see To et al. 2022, for more details).

The control argument is a list that can supply any of the following components:

method_optim

Optimization method to be used. There are three options: "L-BFGS-B", "BFGS" and "Nelder-Mead". Default is "L-BFGS-B".

start

Starting values in the optimization procedure. If it is NULL, a starting point will be automatically obtained.

maxit

The maximum number of iterations. Default is 200.

lower, upper

Possible bounds on the threshold range, for the optimization based on "L-BFGS-B" method. Defaults are -Inf and Inf.

n_boot

Number of bootstrap replicates for estimating the covariance matrix (when Box-Cox transformation is applied). Default is 250.

parallel

A logical value. If set to TRUE, a parallel computing is employed in the bootstrap resampling process.

ncpus

Number of processes to be used in parallel computing. Default is 2.

References

To, D-K., Adimari, G., Chiogna, M. and Risso, D. (2022) ``Receiver operating characteristic estimation and threshold selection criteria in three-class classification problems for clustered data''. Statistical Methods in Medical Research, 7, 31, 1325-1341.

Examples

data(data_3class)
## One covariate
out1 <- clus_lme(fixed_formula = Y ~ X1, name_class = "D",
                 name_clust = "id_Clus", data = data_3class)

### Estimate covariate-specific optimal thresholds at multiple values of one covariate,
### with 3 methods
out_thres_1 <- clus_opt_thres3(method = c("GYI", "MV", "CtP"),
                               out_clus_lme = out1,
                               newdata = data.frame(X1 = 1), ap_var = TRUE)
print(out_thres_1)
plot(out_thres_1)

## Two covariates
out2 <- clus_lme(fixed_formula = Y ~ X1 + X2, name_class = "D",
                 name_clust = "id_Clus", data = data_3class)

### Estimate covariate-specific optimal thresholds at one point, with 3 methods
out_thres_2 <- clus_opt_thres3(method = c("GYI", "MV", "CtP"),
                               out_clus_lme = out2,
                               newdata = data.frame(X1 = 1, X2 = 0),
                               ap_var = TRUE)
print(out_thres_2)
plot(out_thres_2)

### Estimate covariate-specific optimal thresholds at three points, with 3 methods
out_thres_3 <- clus_opt_thres3(method = c("GYI", "MV", "CtP"),
                               out_clus_lme = out2,
                               newdata = data.frame(X1 = c(-0.5, 0.5, 0.5),
                                                    X2 = c(0, 0, 1)),
                               ap_var = TRUE)
print(out_thres_3)
plot(out_thres_3, colors = c("forestgreen", "blue"))