ROCsurface {ClusROC}R Documentation

Plot an estimated covariate-specific ROC surface for clustered data.

Description

ROCsurface estimates and makes a 3D plot of a covariate-specific ROC surface for a continuous diagnostic test, in a clustered design, with three ordinal groups.

Usage

ROCsurface(
  out_lme2,
  newdata,
  step.tcf = 0.01,
  main = NULL,
  file.name = NULL,
  ellips = FALSE,
  thresholds = NULL,
  ci.level = ifelse(ellips, 0.95, NULL)
)

Arguments

out_lme2

an object of class "lme2", a result of lme2 call.

newdata

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

step.tcf

number: increment to be used in the grid for p1 = tcf1 and p3 = tcf3.

main

the main title for plot.

file.name

File name to create on disk.

ellips

a logical value. If set to TRUE, the function adds an ellipsoidal confidence region for TCFs (True Class Fractions), at a specified pair of values for the thresholds, to the plot of estimated covariate-specific ROC surface.

thresholds

a specified pair of thresholds, used to construct the ellipsoidal confidence region for TCFs.

ci.level

a confidence level to be used for constructing the ellipsoidal confidence region; default is 0.95.

Details

This function implements a method in To et al. (2022) for estimating covariate-specific ROC surface of a continuous diagnostic test in a clustered design, with three ordinal groups. The estimator is based on the results from lme2 with 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 ROC surface at the values of covariates is not estimated.

The ellipsoidal confidence region for TCFs at a given pair of thresholds, if required, is constructed by using normal approximation and is plotted in the ROC surface space. The confidence level (default) is 0.95. Note that, if the Box-Cox transformation is applied for the linear mixed-effect model, the pair of thresholds must be input in the original scale. If the constructed confidence region for TCFs is outside the unit cube, a probit transformation will be automatically applied to obtain an appropriate confidence region, which is inside the unit cube (see Bantis et. al., 2017).

Value

ROCsurface returns a 3D rgl plot of the estimated covariate-specific ROC surface.

References

Bantis, L. E., Nakas, C. T., Reiser, B., Myall, D., and Dalrymple-Alford, J. C. (2017). “Construction of joint confidence regions for the optimal true class fractions of Receiver Operating Characteristic (ROC) surfaces and manifolds”. Statistical methods in medical research, 26, 3, 1429-1442.

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, DOI: 10.1177/09622802221089029.

Examples


data(data_3class)
## One covariate
out1 <- lme2(fixed.formula = Y ~ X1, name.class = "D", name.clust = "id_Clus",
             data = data_3class)

### plot only covariate-specific ROC surface
ROCsurface(out_lme2 = out1, newdata = data.frame(X1 = 1))

### plot covariate-specific ROC surface and a 95% ellipsoidal confidence region for TCFs
ROCsurface(out_lme2 = out1, newdata = data.frame(X1 = 1), ellips = TRUE,
           thresholds = c(0.9, 3.95))

## Two covariates
out2 <- lme2(fixed.formula = Y ~ X1 + X2, name.class = "D", name.clust = "id_Clus",
             data = data_3class)

### plot only covariate-specific ROC surface
ROCsurface(out_lme2 = out2, newdata = data.frame(X1 = 1, X2 = 1))

### plot covariate-specific ROC surface and a 95% ellipsoidal confidence region for TCFs
ROCsurface(out_lme2 = out2, newdata = data.frame(X1 = 1, X2 = 1), ellips = TRUE,
           thresholds = c(0.9, 3.95))



[Package ClusROC version 1.0.1 Index]