Longitudinal Concordance Correlation (LCC) Estimated by Fixed Effects and Variance Components using a Polynomial Mixed-Effects Regression Model
The lcc function gives fitted values and non-parametric bootstrap confidence intervals for LCC, longitudinal Pearson correlation (LPC), and longitudinal accuracy (LA) statistics. These statistics can be estimated using different structures for the variance-covariance matrix for random effects and variance functions to model heteroscedasticity among the within-group errors using or not the time as a covariate.
lcc(data, resp, subject, method, time, interaction, qf, qr, covar, gs, pdmat, var.class, weights.form, time_lcc, ci, percentileMet, alpha, nboot, show.warnings, components, REML, lme.control, numCore)
data: an object of class data.frame.
resp: character string. Name of the response variable in the data set.
subject: character string. Name of the subject variable in the data set.
method: character string. Name of the method variable in the data set. The first level of method is used as the gold-standard method.
time: character string. Name of the time variable in the data set.
interaction: an option to estimate the interaction effect between method and time. If TRUE, the default, interaction effect is estimated. If FALSE only the main effects of time and method are estimated.
qf: an integer specifying the degree time polynomial trends, normally 1, 2 or 3. (Degree 0 is not allowed). Default is qf=1
qr: an integer specifying random effects terms to account for subject-to-subject variation. Note that qr=0 specifies a random intercept (form ~ 1|subject); qr=1 specifies random intercept and slope (form ~ time|subject). If qr=qf=q, with , random effects at subject level are added to all terms of the time polynomial regression (form ~ poly(time, q, raw = TRUE)|subject). Default is qr=0.
covar: character vector. Name of the covariates to be included in the model as fixed effects. Default to NULL, never include.
gs: character string. Name of method level which represents the gold-standard. Default is the first level of method.
pdmat: standard classes of positive-definite matrix structures defined in the pdClasses function. The different positive-definite matrices structures available in the lcc function are pdSymm, the default, pdLogChol, pdDiag, pdIdent, pdCompSymm, and pdNatural.
var.class: standard classes of variance functions to model the variance structure of within-group errors using covariates, see varClasses. Default to NULL, correspond to homoscedastic within-group errors. Available standard classes:
varIdent:: allows different variances according to the levels of the stratification variable.varExp:: exponential function of the variance covariate; see varExp.weights.form: character string. An one-sided formula specifying a variance covariate and, optionally, a grouping factor for the variance parameters in the var.class. If var.class=varIdent, the option method'', form `~1|method` or time.ident'', form ~1|time, must be used in the weights.form argument. If var.class=varExp, the option time'', form `~time`, or both'', form ~time|method, must be used in the weights.form argument.
time_lcc: regular sequence for time variable merged with specific or experimental time values used for LCC, LPC, and LA predictions. Default is NULL. The list may contain the following components:
time:: a vector of specific or experimental time values of given length. The experimental time values are used as default.from:: the starting (minimum) value of time variable.to:: the end (maximum) value of time variable.n:: an integer specifying the desired length of the sequence. Generally, n between 30 and 50 is adequate.ci: an optional non-parametric boostrap confidence interval calculated for the LCC, LPC and LA statistics. If TRUE
confidence intervals are calculated and printed in the output. Default is FALSE.
percentileMet: an optional method for calculating the non-parametric bootstrap intervals. If FALSE, the default, is the normal approximation method. If TRUE, the percentile method is used instead.
alpha: significance level. Default is 0.05.
nboot: an integer specifying the number of bootstrap samples. Default is 5,000.
show.warnings: an optional argument that shows the number of convergence errors in the bootstrap samples. If TRUE shows in which bootstrap sample the error occurred. If FALSE, the default, shows the total number of convergence errors.
components: an option to print LPC and LA statistics. If TRUE the estimates and confidence intervals for LPC and LA are printed in the output. If FALSE, the default, provides estimates and confidence interval only for the LCC statistic.
REML: if TRUE, the default, the model is fit by maximizing the restricted log-likelihood. If FALSE the log-likelihood is maximized.
lme.control: a list of control values for the estimation algorithm to replace the default values of the function lmeControl available in the nlme
package. Defaults to an empty list. The returned list is used as the control argument for the lme function.
numCore: number of cores used in parallel during bootstrapping computation. Default is 1.
an object of class lcc. The output is a list with the following components: - model: summary of the polynomial mixed-effects regression model. - Summary.lcc: fitted values for the LCC or LCC, LPC and LA (if components=TRUE); concordance correlation coefficient (CCC) between methods for each level of time as sampled values, and the CCC between mixed-effects model predicted values and observed values from data as goodness of fit (gof)
data(hue) ## Second degree polynomial model with random intercept, slope and ## quadratic term fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean", method = "Method", time = "Time", qf = 2, qr = 2) print(fm1) summary(fm1) summary(fm1, type="model") lccPlot(fm1) + ylim(0,1) + geom_hline(yintercept = 1, linetype = "dashed") + scale_x_continuous(breaks = seq(1,max(hue$Time),2)) ## Estimating longitudinal Pearson correlation and longitudinal ## accuracy fm2 <- update(fm1, components = TRUE) summary(fm2) lccPlot(fm2) + ylim(0,1) + geom_hline(yintercept = 1, linetype = "dashed") + scale_x_continuous(breaks = seq(1,max(hue$Time),2)) + theme_bw() ## A grid of points as the Time variable for prediction fm3 <- update(fm2, time_lcc = list(from = min(hue$Time), to = max(hue$Time), n=40)) summary(fm3) lccPlot(fm3) + ylim(0,1) + geom_hline(yintercept = 1, linetype = "dashed") + scale_x_continuous(breaks = seq(1,max(hue$Time),2)) + theme_bw() ## Not run: ## Including an exponential variance function using time as a ## covariate. fm4 <- update(fm2,time_lcc = list(from = min(hue$Time), to = max(hue$Time), n=30), var.class=varExp, weights.form="time") summary(fm4, type="model") fitted(fm4) fitted(fm4, type = "lpc") fitted(fm4, type = "la") lccPlot(fm4) + geom_hline(yintercept = 1, linetype = "dashed") lccPlot(fm4, type = "lpc") + geom_hline(yintercept = 1, linetype = "dashed") lccPlot(fm4, type = "la") + geom_hline(yintercept = 1, linetype = "dashed") ## Non-parametric confidence interval with 500 bootstrap samples fm5 <- update(fm1, ci = TRUE, nboot = 500) summary(fm5) lccPlot(fm5) + geom_hline(yintercept = 1, linetype = "dashed") ## Considering three methods of color evaluation data(simulated_hue) attach(simulated_hue) fm6 <- lcc(data = simulated_hue, subject = "Fruit", resp = "Hue", method = "Method", time = "Time", qf = 2, qr = 1, components = TRUE, time_lcc = list(n=50, from=min(Time), to=max(Time))) summary(fm6) lccPlot(fm6, scales = "free") lccPlot(fm6, type="lpc", scales = "free") lccPlot(fm6, type="la", scales = "free") detach(simulated_hue) ## Including an additional covariate in the linear predictor ## (randomized block design) data(simulated_hue_block) attach(simulated_hue_block) fm7 <- lcc(data = simulated_hue_block, subject = "Fruit", resp = "Hue", method = "Method",time = "Time", qf = 2, qr = 1, components = TRUE, covar = c("Block"), time_lcc = list(n=50, from=min(Time), to=max(Time))) summary(fm7) lccPlot(fm7, scales="free") detach(simulated_hue_block) ## Testing interaction effect between time and method fm8 <- update(fm1, interaction = FALSE) anova(fm1, fm8) ## Using parallel computing with 3 cores, and a set.seed(123) ## to verify model reproducibility. set.seed(123) fm9 <- lcc(data = hue, subject = "Fruit", resp = "H_mean", method = "Method", time = "Time", qf = 2, qr = 2, ci=TRUE, nboot = 30, numCore = 3) # Repeating same model with same set seed. set.seed(123) fm10 <- lcc(data = hue, subject = "Fruit", resp = "H_mean", method = "Method", time = "Time", qf = 2, qr = 2, ci=TRUE, nboot = 30, numCore = 3) ## Verifying if both fitted values and confidence intervals ## are identical identical(fm9$Summary.lcc$fitted,fm10$Summary.lcc$fitted) ## End(Not run)
Lin, L. A Concordance Correlation Coefficient to Evaluate Reproducibility. Biometrics, 45, n. 1, 255-268, 1989.
Oliveira, T.P.; Hinde, J.; Zocchi S.S. Longitudinal Concordance Correlation Function Based on Variance Components: An Application in Fruit Color Analysis. Journal of Agricultural, Biological, and Environmental Statistics, v. 23, n. 2, 233–254, 2018.
Oliveira, T.P.; Moral, R.A.; Zocchi, S.S.; Demetrio, C.G.B.; Hinde, J. lcc: an R packageto estimate the concordance correlation, Pearson correlation, and accuracy over time. PeerJ, 8:c9850, 2020. DOI:10.7717/peerj.9850
summary.lcc, fitted.lcc, print.lcc, lccPlot, plot.lcc, coef.lcc, ranef.lcc, vcov.lcc, getVarCov.lcc, residuals.lcc, AIC.lcc
Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br , Rafael de Andrade Moral, John Hinde
Useful links