lcc (version 3.2.2)

lcc: Longitudinal concordance correlation (LCC) from polynomial mixed effects regression models using fixed effects and variance components

Description

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.

Usage

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)

Value

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.

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.

Author

Thiago de Paula Oliveira, , Rafael de Andrade Moral, John Hinde

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

Examples

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()

if (FALSE) {
## 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()
}

## 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")

if (FALSE) {
## 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 colour evaluation
if (FALSE) {
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
## (randomised block design)
if (FALSE) {
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 the interaction effect between time and method
fm8 <- update(fm1, interaction = FALSE)
anova(fm1, fm8)

if (FALSE) {
## 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)
}