lcc (version 1.0.2)

lcc: Longitudinal Concordance Correlation (LCC) estimated by fixed effects aqnd variance components of 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(dataset, resp, subject, method, time, interaction, qf,
    qr, covar, pdmat, var.class, weights.form, time_lcc, ci,
    percentileMet, alpha, nboot, show.warnings, components,
    REML, lme.control)

Arguments

dataset

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

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 ~ time + time^2 + ... + time^q|subject).

covar

character vector. Name of the covariates to be included in the model as fixed effects. Default to NULL, never include.

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.

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

summary of the fitted and sampled values, and the concordance correlation coefficient between them as goodness of fit (gof)

dataset

the input dataset.

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<U+2013>254, 2018.

See Also

summary.lcc, lccPlot, lmeControl

Examples

# NOT RUN {
data(hue)
## Second degree polynomial model with random intercept, slope and
## quadratic term
fm1<-lcc(dataset = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2)
summary(fm1)
summary(fm1, type="model")
lccPlot(fm1)

## Estimating longitudinal Pearson correlation and longitudinal
#accuracy
fm2<-lcc(dataset = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2,
         components = TRUE)
summary(fm2)
lccPlot(fm2)

# }
# NOT RUN {
## A grid of points as the Time variable for prediction
fm3<-lcc(dataset = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2,
         components = TRUE, time_lcc = list(from = min(hue$Time),
         to = max(hue$Time), n=40))
summary(fm3)
lccPlot(fm3)
# }
# NOT RUN {
## Including an exponential variance function using time as a
#covariate.
fm4<-lcc(dataset = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2,
         components = TRUE, time_lcc = list(from = min(hue$Time),
         to = max(hue$Time), n=40), var.class=varExp,
         weights.form="time")
summary(fm4)
lccPlot(fm4)

# }
# NOT RUN {
## Non-parametric confidence interval with 500 bootstrap samples
fm5<-lcc(dataset = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2,
         ci = TRUE, nboot = 500)
summary(fm5)
lccPlot(fm5)
# }
# NOT RUN {
## Considering three methods of color evaluation
# }
# NOT RUN {
data(simulated_hue)
attach(simulated_hue)
fm6<-lcc(dataset = 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)
detach(simulated_hue)
# }
# NOT RUN {
## Including an additional covariate in the linear predictor
## (randomized block design)
# }
# NOT RUN {
data(simulated_hue_block)
attach(simulated_hue_block)
fm7<-lcc(dataset = 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)
detach(simulated_hue_block)
# }
# NOT RUN {
# }