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

lcc {lcc}

R Documentation

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

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, thiago.paula.oliveira@alumni.usp.br, 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

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)

[Package lcc version 1.1.4 Index]