# Longitudinal concordance correlation (LCC) from polynomial mixed effects regression models using fixed effects and variance components The `lcc` function computes fitted values and non-parametric bootstrap confidence intervals for the longitudinal concordance correlation (LCC), longitudinal Pearson correlation (LPC), and longitudinal accuracy (LA). These statistics are estimated from a polynomial mixed-effects model with flexible variance-covariance structures for random effects and variance functions that can model heteroscedastic within-subject errors, with or without 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`: logical. Indicates whether to estimate the interaction between `method` and `time`. If `TRUE` (the default), both main effects and their interaction are estimated. If `FALSE`, only the main effects of time and method are estimated. - `qf`: integer. Degree of the polynomial time trend, usually 1, 2, or 3 (degree 0 is not allowed). Default is `qf = 1`. - `qr`: integer. Degree of the random-effects polynomial in time used to model 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 the 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. Names of covariates to be included in the model as fixed effects. Defaults to `NULL`, meaning that no additional covariates are included. - `gs`: character string. Name of the level of `method` that represents the gold-standard. Defaults to the first level of `method`. - `pdmat`: standard classes of positive-definite matrix structures defined in `pdClasses`. The available positive-definite matrix structures in `lcc` are `pdSymm` (the default), `pdLogChol`, `pdDiag`, `pdIdent`, `pdCompSymm`, and `pdNatural`. - `var.class`: standard classes of variance functions used to model the variance structure of within-subject errors using covariates; see `varClasses`. Defaults to `NULL`, which corresponds to homoscedastic within-subject errors. Available standard classes include: - **`varIdent`:**: allows different variances according to the levels of a stratification variable. - **`varExp`:**: exponential function of the variance covariate; see `varExp`. - `weights.form`: character string. A one-sided formula specifying a variance covariate and, optionally, a grouping factor for the variance parameters in `var.class`. If `var.class = varIdent`, the options `"method"` (form `~ 1 | method`) or `"time.ident"` (form `~ 1 | time`) must be used in `weights.form`. If `var.class = varExp`, the options `"time"` (form `~ time`) or `"both"` (form `~ time | method`) must be used in `weights.form`. - `time_lcc`: list or `NULL`. Regular sequence for the time variable, merged with specific or experimental time values used for LCC, LPC, and LA predictions. Defaults to `NULL`. The list may contain the following components: - **`time`:**: a vector of specific or experimental time values. The experimental time values are used by default. - **`from`:**: the starting (minimum) value of the time variable. - **`to`:**: the end (maximum) value of the time variable. - **`n`:**: integer specifying the desired length of the sequence. Values of `n` between 30 and 50 are usually adequate. - `ci`: logical. If `TRUE`, non-parametric bootstrap confidence intervals are calculated for the LCC, LPC, and LA statistics and printed in the output. Default is `FALSE`. - `percentileMet`: logical. Method used to calculate the non-parametric bootstrap intervals. If `FALSE` (the default), the normal approximation method is used. If `TRUE`, the percentile method is used instead. - `alpha`: significance level. Default is `0.05`. - `nboot`: integer. Number of bootstrap samples. Default is `5000`. - `show.warnings`: logical. Controls the display of convergence warnings in the bootstrap samples. If `TRUE`, the indices of bootstrap samples with convergence errors are shown. If `FALSE` (the default), only the total number of convergence errors is reported. - `components`: logical. If `TRUE`, estimates and confidence intervals for LPC and LA are printed in the output. If `FALSE` (the default), only estimates and confidence intervals for the LCC statistic are provided. - `REML`: logical. If `TRUE` (the default), the model is fit by maximising the restricted log-likelihood. If `FALSE`, the full log-likelihood is maximised. - `lme.control`: list. Control values for the estimation algorithm, replacing the defaults of `lmeControl` in the `nlme` package. Defaults to `NULL`. The returned list is passed as the `control` argument to `lme`. - `numCore`: integer. Number of cores used in parallel during bootstrap 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 LCC, or for LCC, LPC, and LA if `components = TRUE`; the concordance correlation coefficient (CCC) between methods at each sampled value of `time`, and the CCC between mixed-effects model predictions and observed data as a goodness-of-fit measure (gof). - **data**: the input data set. ## 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() ## Not run: ## 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() ## End(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") ## Not run: ## 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") ## End(Not run) ## Considering three methods of colour evaluation ## Not run: 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) ## End(Not run) ## Including an additional covariate in the linear predictor ## (randomised block design) ## Not run: 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) ## End(Not run) ## Testing the interaction effect between time and method fm8 <- update(fm1, interaction = FALSE) anova(fm1, fm8) ## Not run: ## Using parallel computing with 3 cores, and 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 the same model with the same 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 that 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(1), 255–268, 1989. Oliveira, T. P.; Hinde, J.; Zocchi, S. S. Longitudinal concordance correlation function based on variance components: an application in fruit colour analysis. **Journal of Agricultural, Biological, and Environmental Statistics**, 23(2), 233–254, 2018. Oliveira, T. P.; Moral, R. A.; Zocchi, S. S.; Demetrio, C. G. B.; Hinde, J. lcc: an R package to estimate the concordance correlation, Pearson correlation, and accuracy over time. **PeerJ**, 8:e9850, 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