clus_lme {ClusROC}

Linear Mixed-Effects Models for a continuous diagnostic test or a biomarker (or a classifier).

Description

clus_lme fits the cluster-effect model for a continuous diagnostic test in a three-class setting as described in Xiong et al. (2018) and To et al. (2022).

Usage

clus_lme(
  fixed_formula,
  name_class,
  name_clust,
  data = sys.frame(sys.parent()),
  subset,
  na_action = na.fail,
  levl_class = NULL,
  ap_var = TRUE,
  boxcox = FALSE,
  interval_lambda = c(-2, 2),
  trace = TRUE,
  ...
)

Arguments

fixed_formula

a two-sided linear formula object, describing the fixed-effects part of the model for three classes, with the response on the left of ~ operator and the terms, separated by + operators, on the right. For example, Y ~ X1 + X2, Y ~ X1 + X2 + X1:X2 or log(Y) ~ X1 + X2 + I(X1^2).

name_class

name of variable indicating three classes (or three groups) in the data.

name_clust

name of variable indicating clusters in the data.

data

a data frame containing the variables in the model.

subset

an optional expression indicating the subset of the rows of data that should be used in the fit. This can be a logical vector, or a numeric vector indicating which observation numbers are to be included, or a character vector of the row names to be included. All observations are included by default.

na_action

a function that indicates what should happen when the data contain NAs. The default action (na.fail) causes clus_lme to print an error message and terminate if there are any incomplete observations.

levl_class

a vector (of strings) containing the ordered name chosen for the disease classes. The ordering is intended to be “increasing” with respect to the disease severity. If levl_class = NULL (default), the elements of the vector will be automatically determined from data, by considering the order of the means of the test values for each disease class (diagnostic group).

ap_var

a logical value. Default = TRUE. If set to TRUE, the estimated covariance matrix for all estimated parameters in the model will be obtained (by using the sandwich formula).

boxcox

a logical value. Default = FALSE. If set to TRUE, a Box-Cox transformation will be applied to the model.

interval_lambda

a vector containing the end-points of the interval for searching the Box-Cox parameter, lambda. Default = (-2, 2).

trace

a logical value. Default = TRUE. If set to TRUE, the information about the check for the monotonic ordering of test values will be provided.

...

additional arguments for lme, such as control, contrasts.

Details

This function fits a linear mixed-effect model for a continuous diagnostic test in a three-class setting in order to account for the cluster and covariates effects on the test result. See Xiong et al. (2018) and To et al. (2022) for more details.

• Estimation is done by using lme with the restricted maximum log-likelihood (REML) method.

• Box-Cox transformation for the model can be used when the distributions of test results are skewed (Gurka et al. 2006). The estimation procedure is described in To et al. (2022). The Box-Cox parameter \lambda is estimated by a grid search on the interval (-2, 2), as discussed in Gurka and Edwards (2011).

• The estimated variance-covariance matrix for the estimated parameters are obtained by sandwich formula (see, Liang and Zeger, 1986; Kauermann and Carroll, 2001; Mancl and DeRouen, 2001) as discussed in To et al. (2022).

Value

clus_lme returns an object of class "clus_lme" class, i.e., a list containing at least the following components:

call

the matched call.

est_para

a vector containing the estimated parameters.

se_para

a vector containing the standard errors.

vcov_sand

the estimated covariance matrix for all estimated parameters.

residual

a list of residuals.

fitted

a list of fitted values.

randf

a vector of estimated random effects for each cluster level.

n_coef

total number of coefficients included in the model.

n_p

total numbers of regressors in the model.

icc

an estimate of intra-class correlation - ICC

terms

the terms object used.

boxcox

logical value indicating whether the Box-Cox transformation was applied or not.

data

data frame is used to fitting model.

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

References

Gurka, M. J., Edwards, L. J. , Muller, K. E., and Kupper, L. L. (2006) “Extending the Box-Cox transformation to the linear mixed model”. Journal of the Royal Statistical Society: Series A (Statistics in Society), 169, 2, 273-288.

Gurka, M. J. and Edwards, L. J. (2011) “Estimating variance components and random effects using the box-cox transformation in the linear mixed model”. Communications in Statistics - Theory and Methods, 40, 3, 515-531.

Kauermann, G. and Carroll, R. J. (2001) “A note on the efficiency of sandwich covariance matrix estimation”. Journal of the American Statistical Association, 96, 456, 1387-1396.

Liang, K. Y. and Zeger, S. L. (1986) “Longitudinal data analysis using generalized linear models”. Biometrika, 73, 1, 13-22.

Mancl, L. A. and DeRouen, T. A. (2001) “A covariance estimator for GEE with improved small-sample properties”. Biometrics, 57, 1, 126-134.

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.

Xiong, C., Luo, J., Chen L., Gao, F., Liu, J., Wang, G., Bateman, R. and Morris, J. C. (2018) “Estimating diagnostic accuracy for clustered ordinal diagnostic groups in the three-class case – Application to the early diagnosis of Alzheimer disease”. Statistical Methods in Medical Research, 27, 3, 701-714.

Examples

## Example 1:
data(data_3class)
head(data_3class)
## A model with two covariate
out1 <- clus_lme(fixed_formula = Y ~ X1 + X2, name_class = "D",
                 name_clust = "id_Clus", data = data_3class)
print(out1)
plot(out1)


## Example 2: Box-Cox transformation
data(data_3class_bcx)
out2 <- clus_lme(fixed_formula = Y ~ X, name_class = "D",
                 name_clust = "id_Clus", data = data_3class_bcx,
                 boxcox = TRUE)
print(out2)
plot(out2)