# 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. ```r 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) ``` ## Arguments - `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 $q \ge 1$, 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. ## Returns 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**: the input dataset. ## Examples ```r 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) ``` ## References 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 ## See Also `summary.lcc`, `fitted.lcc`, `print.lcc`, `lccPlot`, `plot.lcc`, `coef.lcc`, `ranef.lcc`, `vcov.lcc`, `getVarCov.lcc`, `residuals.lcc`, `AIC.lcc` ## Author(s) Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br , Rafael de Andrade Moral, John Hinde

lcc function