lcc: Longitudinal Concordance Correlation (LCC) Estimated by Fixed...

In lcc: Longitudinal Concordance Correlation

Longitudinal Concordance Correlation (LCC) Estimated by Fixed Effects and Variance Components using a Polynomial Mixed-Effects Regression Model

Description

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.

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)

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 ≥ 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.

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 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.

Author(s)

Thiago de Paula Oliveira, [e-mail], Rafael de Andrade Moral, John Hinde

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

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

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

lcc documentation built on Aug. 25, 2022, 5:08 p.m.