Type: Package
Title: Advanced Analysis of Longitudinal Data Using the Concordance Correlation Coefficient
Version: 3.2.2
Date: 2025-11-23
Description: Methods for assessing agreement between repeated measurements obtained by two or more methods using the longitudinal concordance correlation coefficient (LCC). Polynomial mixed-effects models (via 'nlme') describe how concordance, Pearson correlation and accuracy evolve over time. Functions are provided for model fitting, diagnostic plots, extraction of summaries, and non-parametric bootstrap confidence intervals (including parallel computation), following Oliveira et al. (2018) <doi:10.1007/s13253-018-0321-1>.
Depends: R (≥ 3.2.3), nlme (≥ 3.1-124), ggplot2 (≥ 2.2.1)
Imports: hnp, parallel, doSNOW, doRNG, foreach
Suggests: roxygen2 (≥ 3.0.0), covr, testthat, MASS
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
Repository: CRAN
LazyData: true
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2025-11-23 11:31:23 UTC; ThiagoOliveira
Author: Thiago de Paula Oliveira ORCID iD [aut, cre], Rafael de Andrade Moral ORCID iD [aut], Silvio Sandoval Zocchi ORCID iD [ctb], Clarice Garcia Borges Demetrio ORCID iD [ctb], John Hinde ORCID iD [aut]
Maintainer: Thiago de Paula Oliveira <thiago.paula.oliveira@alumni.usp.br>
Date/Publication: 2025-11-23 13:30:11 UTC

Internal helper to compute LA list for one diffbeta

Description

Internal helper to compute LA list for one diffbeta

Usage

.compute_LA(pre, diffbeta)

Internal helper to compute LCC list for one diffbeta

Description

Internal helper to compute LCC list for one diffbeta

Usage

.compute_LCC(pre, diffbeta)

Internal helper to compute LPC list (does not depend on diffbeta)

Description

Internal helper to compute LPC list (does not depend on diffbeta)

Usage

.compute_LPC(pre)

Internal base theme used by all ggplot-based summaries

Description

Internal base theme used by all ggplot-based summaries

Usage

.lcc_default_theme()

Internal helper to precompute longitudinal quantities

Description

Precomputes quantities (polynomial bases, tGt, deltas, etc.) that are shared across LCC, LPC and LA for a given model and time grid.

Usage

.precompute_longitudinal(model, tk, q_f, q_r, basis = NULL)

Akaike and Bayesian Information Criteria for an lcc Object

Description

Calculates the Akaike Information Criterion (AIC) or the Bayesian Information Criterion (BIC) for a fitted longitudinal concordance correlation model represented by an lcc object.

Calculates the Bayesian Information Criterion (BIC) for a fitted longitudinal concordance correlation model represented by an lcc object. BIC is used for model selection, with lower values indicating a better model.

Usage

## S3 method for class 'lcc'
AIC(object, ..., k = 2)

## S3 method for class 'lcc'
BIC(object, ...)

Arguments

object

An object of class lcc, representing a fitted longitudinal concordance correlation function.

...

Optional arguments passed to the underlying BIC function from the stats package.

k

Numeric value used as a penalty coefficient for the number of parameters in the fitted model; the default k = 2 corresponds to the classical AIC.

Details

The function computes AIC or BIC values as a measure of the relative quality of statistical models for a given set of data. Lower AIC or BIC values indicate a better model fit with fewer parameters. For more information, refer to the methods for AIC objects.

The function computes BIC as a measure of the trade-off between model fit and complexity. It is particularly useful for comparing models with different numbers of parameters. For more information, refer to the documentation for BIC.

See Also

lcc, summary.lcc, coef.lcc, vcov.lcc

lcc, summary.lcc, coef.lcc, vcov.lcc, AIC.lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
AIC(fm1)

## End(Not run)

## Not run: 
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)))
AIC(fm6)
BIC(fm6)

## End(Not run)

Internal Function to Compute the Sampled Concordance Correlation Values.

Description

This function computes the sampled concordance correlation coefficient (CCC) between two numeric vectors. It is used internally for statistical analysis.

Usage

CCC(Y1, Y2)

Arguments

Y1

A numeric vector.

Y2

A numeric vector, typically paired with Y1.

Value

The concordance correlation coefficient between Y1 and Y2.

Examples

# Example usage:
# CCC(c(1, 2, 3), c(3, 2, 1))

Internal Function to Estimate the Sampled Concordance Correlation Coefficient.

Description

This function is internally called to estimate the sampled concordance correlation coefficient.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Estimate Sampled Pearson Correlation

Description

Internally called function to estimate the sampled Pearson correlation.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Compare Likelihoods of Fitted Models from an lcc Object

Description

Compares the fit of different longitudinal concordance correlation models (lcc objects). When comparing multiple models, the function returns a data frame with degrees of freedom, log-likelihood, AIC, and BIC for each model. For a single model, it returns F-values and P-values for fixed terms in the model.

Usage

## S3 method for class 'lcc'
anova(object, ..., test = TRUE, type = c("sequential", "marginal"), 
  adjustSigma = TRUE, verbose = FALSE)

Arguments

object

An object inheriting from class lcc or lme.

...

Other optional fitted model objects inheriting from classes "lcc" or "lme".

test

Logical; if TRUE, performs likelihood ratio tests to compare models. Defaults to TRUE.

type

Character string specifying the type of sum of squares for F-tests. Options are "sequential" or "marginal". Defaults to "sequential".

adjustSigma

Logical; if TRUE, adjusts the residual standard error for maximum likelihood estimation. Defaults to TRUE.

verbose

Logical; if TRUE, prints additional model details. Defaults to FALSE.

Details

This function is an adaptation from anova.lme. It assesses whether the addition of terms significantly improves model fit.

See Also

lcc, summary.lcc

Examples

## Not run: 
fm1.aov <- lcc(data = hue, subject = "Fruit", resp = "H_mean", method = "Method", 
               time = "Time", qf = 2, qr = 1)
fm2.aov <- update(fm1.aov, qr = 2)
anova(fm1.aov, fm2.aov)

## End(Not run)

## Not run: 
fm3.aov <- update(fm2.aov, REML = FALSE)
fm4.aov <- update(fm2.aov, REML = FALSE, qf = 3)
anova(fm3.aov, fm4.aov)

## End(Not run)

## Not run: 
fm5.aov <- update(fm2.aov, var.class = varExp, weights.form = "time")
anova(fm1.aov, fm2.aov, fm5.aov)

## End(Not run)

Internal functions to estimate fixed effects and variance components.

Description

This is an internally called functions used to estimate fixed effects and variance components for each bootstrap sample.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Internal Function to Prepare the ciCompute Function.

Description

This is an internally called function used to prepare the ciCompute function.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Internal Function to Compute the Non-Parametric Bootstrap Interval.

Description

This is an internally called function used to compute the non-parametric bootstrap interval.

Details

returns a matrix or list of matrix containing the non-parametric bootstrap interval.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Extract Model Coefficients

Description

The fixed effects estimated and corresponding random effects estimates are obtained at subject levels less or equal to i. The resulting estimates are returned as a data frame, with rows corresponding to subject levels and columns to coefficients.

Usage

## S3 method for class 'lcc'
coef(object, ...)

Arguments

object

an object inheriting from class lcc, representing a fitted longitudinal concordance correlation function.

...

optional arguments passed to the coef.lme function.

Details

See methods for nlme objects to get more details.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

lcc, summary.lcc, lccPlot, vcov.lcc

Examples


## Not run: 
fm1<-lcc(data = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2)
coef(fm1)

## End(Not run)

Internal Function to Prepare the Dataset for lcc Objects

Description

This is an internally called function used to prepare the dataset for lcc objects

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Extract Fitted Values from an lcc Object

Description

Extracts and prints the fitted values from an object of class lcc, as returned by modeling functions. The function allows selection of different types of fitted values based on longitudinal data analysis.

Usage

## S3 method for class 'lcc'
fitted(object, type = "lcc", digits = NULL, ...)

Arguments

object

An object of class lcc, representing a fitted longitudinal concordance correlation model.

type

The type of fitted values to extract: "lcc" for longitudinal concordance correlation, "lpc" for longitudinal Pearson correlation, or "la" for longitudinal accuracy. Defaults to "lcc".

digits

Minimum number of significant digits to be printed. Default is NULL, which uses the default precision.

...

Additional arguments (currently not used).

Value

The function prints the fitted values and returns them as a data frame.

See Also

lcc, summary.lcc, lccPlot

Examples

data(hue)
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2,
           components = TRUE)
fitted(fm1)
fitted(fm1, type = "lpc")
fitted(fm1, type = "la")

Internal Function to Build Fitted Values for lcc Objects

Description

This is an internally called function used to build fitted values.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Format Columns for Print

Description

This internal helper function is used to format the columns of a data frame for printing, specifically for use within the 'print.anova.lcc' function. It applies special formatting rules based on the column name, such as rounding and special handling of small p-values.

Usage

formatColumn(column, colName)

Arguments

column

A vector representing a column from a data frame.

colName

A string indicating the name of the column, which determines the formatting rules to be applied.

Details

The function specifically handles the following columns: - "p-value": Rounds the values to four decimal places, and represents values less than 0.0001 as "<.0001". - "AIC", "BIC", "logLik", "L.Ratio": Applies 'zapsmall' for formatting. Other columns are returned without changes.

Value

A vector with the same length as 'column', where each element has been formatted according to the column-specific rules.

Examples

data <- data.frame(
  pvalue = c(0.00005, 0.0234, 0.5),
  AIC = c(123.4567, 234.5678, 345.6789)
)
data$pvalue <- formatColumn(data$pvalue, "p-value")
data$AIC <- formatColumn(data$AIC, "AIC")

Internal Function to Extract Variance Components Estimates.

Description

This is an internally called function used to extract variance components estimate of \Sigma matrix based on specified structure.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br and Rafael de Andrade Moral, rafael_moral@yahoo.com.br

Extract Variance Components from a Fitted lcc Model

Description

Retrieves the variance-covariance matrix of the specified component from a fitted lcc model object. The function can extract different types of variance-covariance matrices based on the specified component type.

Usage

## S3 method for class 'lcc'
getVarCov(obj, type = "random.effects", ...)

Arguments

obj

An object of class lcc, representing a fitted longitudinal concordance correlation model.

type

Specifies the type of variance-covariance matrix to extract. Options are "random.effects" for random-effects variance-covariance, "conditional" for conditional variance-covariance of the responses, and "marginal" for marginal variance-covariance of the responses. Default is "random.effects".

...

Optional arguments passed to the underlying getVarCov function from the nlme package.

Details

This function is useful for detailed inspection of the variance components in different aspects of the model. For more information on the types of variance-covariance matrices and their interpretations, refer to the documentation of the nlme package.

See Also

lcc, summary.lcc, coef.lcc, vcov.lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
getVarCov(fm1)

## End(Not run)

Hue color data

Description

An observational study conducted at the Vegetable Production Department at "Luiz de Queiroz" College of Agriculture/University of São Paulo in 2010/2011 to evaluate the peel color of 20 papaya fruits cv. Sunrise Solo over time. The color hue was measured on the equatorial region of each fruit using four points observed by the colorimeter and 1,000 points observed by the scanner. Thus, the circular mean hue was calculated for each fruit by each device at time t. The aim of the agreement study was to assess how well the colorimeter agreed with the scanner over time.

Usage

data(hue)

Format

A data frame with 554 observations on the mean hue variable. The format is:

H_mean numeric; mean hue of papaya's peel
Method a factor with levels Colorimeter, Scanner
Time integer; time in days
Fruit a factor with 20 levels; from 1 to 20
where each level is represented by one fruit.

Source

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.; Zocchi S.S.; Jacomino, A.P. Measuring color hue in 'Sunrise Solo' papaya using a flatbed scanner. Rev. Bras. Frutic., v. 39, n. 2, e-911, 2017.

References

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.

See Also

lcc.

Examples

data(hue)
summary(hue)
str(hue)
## Second degree polynomial model with random intercept, slope and
## quadratic term including an exponential variance function using
## time as covariate.
model<-lcc(data = 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(model, type="model")
summary(model, type="lcc")
## for discussion on the analysis of complete data set,
## see Oliveira et al. (2018)

Internal Function to Prepare lccModel Function

Description

This is an internally called function used to verify the specification of variance-covariance matrices and likelihood based method.

Value

No return value, called for side effects

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Reports whether x is a lcc object

Description

Reports whether x is a lcc object

Usage

is.lcc(x)

Arguments

x

An object to test

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Internal Function to Estimate the Longitudinal Accuracy (Bias Corrector)

Description

Thin wrapper around .precompute_longitudinal() and .compute_LA().

Usage

laBuilder(G, diffbeta, tk, q_r, q_f, g, sig2_epsilon, delta, deltal, model)

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)

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.

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.

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

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

Internal Function to Estimate the Longitudinal Concordance Correlation

Description

Thin wrapper around .precompute_longitudinal() and .compute_LCC().

Usage

lccBuilder(G, diffbeta, tk, q_r, q_f, g, sig2_epsilon, delta, deltal, model)

Internal Function to Prepare lcc Objects

Description

This is an internally called function used to prepare lcc objects for calculate the longitudinal concordance correlation, longitudinal Pearson correlation, longitudinal bias corrector, and plotting

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br and Rafael de Andrade Moral, rafael_moral@yahoo.com.br

Internal function to fit a linear mixed-effects model

Description

Internal helper to fit a linear mixed-effects model, following the formulation described in Laird and Ware (1982). See lme for details.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

References

Laird, N. M.; Ware, J. H. (1982). Random-effects models for longitudinal data. Biometrics, 38, 963–974.

Pinheiro, J. C.; Bates, D. M. (1996). Unconstrained parametrizations for variance–covariance matrices. Statistics and Computing, 6, 289–296.

Pinheiro, J. C.; Bates, D. M. (2000). Mixed-effects models in S and S-PLUS. Springer.

Plot Fitted Curves from an lcc Object

Description

This function generates a plot of predictions versus the time covariate for an lcc object. Predicted values are connected by lines, while actual observations are denoted by circles. If components=TRUE was used in the lcc object, individual plots for each statistic (LCC, LPC, and LA) are produced on separate pages.

Usage

lccPlot(obj, type = "lcc", control = list(), ...)

Arguments

obj

An object inheriting from class "lcc", representing a fitted lcc model.

type

Character string specifying the type of plot to generate.

  • "lcc": Produces the LCC plot.

  • "lpc": Produces the LPC plot. Available only if components = TRUE.

  • "la": Produces the LA plot. Available only if components = TRUE.

control

A list of graphical control values or character strings returned by the plotControl function. Defaults to an empty list. The list can contain components like shape, colour, size, xlab, ylab, scale_y_continuous, and all.plot.

...

Additional arguments passed to the facet_wrap function.

Value

An object of class ggplot or viewport, depending on the all.plot setting in control.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

lcc, plotControl

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, components = TRUE)
lccPlot(fm1, type = "lcc")
lccPlot(fm1, type = "lpc")
lccPlot(fm1, type = "la")

# Using ggplot2 themes
lccPlot(fm1, type = "lpc") + theme_bw() + labs(x = "Time (Days)", y = "LPC Value")

# Generating and saving plots
## Not run: 
  ggsave("lccPlot.pdf", lccPlot(fm1, type = "lcc"))

## End(Not run)

Internal Function to Summarize Fitted and Sampled Values for lcc Objects

Description

Internally called function for summarizing fitted and sampled values, and the concordance correlation coefficient between them for lcc objects.

Details

Returns a summary of fitted and sampled values and their concordance correlation.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Internal Functions to Compute the Non-Parametric Confidence Intervals for LCC.

Description

This is an internally called functions used to compute the non-parametric confidence intervals for LCC.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Extract Log-Likelihood of an lcc Object

Description

If REML=TRUE, the default, returns the restricted log-likelihood value of the linear mixed-effects model; else the log-likelihood value

Usage

## S3 method for class 'lcc'
logLik(object, ..., REML)

Arguments

object

an object inheriting from class lcc, representing a fitted longitudinal concordance correlation function.

...

further arguments passed to logLik.

REML

an optional logical value. If TRUE the restricted log-likelihood is returned, else, if FALSE, the log-likelihood is returned.

Details

See methods for nlme objects to get more details.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

lcc, summary.lcc

Examples


## Not run: 
fm1<-lcc(data = hue, subject = "Fruit", resp = "H_mean",
         method = "Method", time = "Time", qf = 2, qr = 2)
logLik(fm1)

## End(Not run)

Internal Function to Estimate the Longitudinal Pearson Correlation

Description

Thin wrapper around .precompute_longitudinal() and .compute_LPC().

Usage

lpcBuilder(G, tk, q_r, q_f, g, sig2_epsilon, delta, deltal, model)

Diagnostic Plots for an lcc Object

Description

Generates a series of diagnostic plots for evaluating the fit of a linear mixed-effects model represented by an lcc object. This function provides six types of plots, including residual plots, fitted value comparisons, and normal Q-Q plots. Users can select specific plots or display all by default.

Usage

## S3 method for class 'lcc'
plot(x, which = c(1L:6L),
     caption = list("Residuals vs Fitted",
                    "Residuals vs Time",
                    "Residuals by Subject",
                    "Observed values vs Fitted values",
                    "Normal Q-Q Plot (Conditional residuals)",
                    "Normal Q-Q Plot (Random effects)"),
     sub.caption = NULL, main = NULL,
     panel = if(add.smooth) panel.smooth else points,
     add.smooth = TRUE, ask = TRUE,
     id.n = 3, labels.id = names(residuals(x)),
     label.pos = c(4, 2), cex.id = 0.75, cex.caption = 1,
     cex.oma.man = 1.25, ...)

Arguments

x

An object of class lcc, representing a fitted longitudinal concordance correlation function.

which

A numeric vector specifying which plots to display. The valid range is c(1L:6L), corresponding to the plot types.

caption

Captions for the plots, provided as a vector or list of valid graphics annotations. Default captions are provided for each plot.

sub.caption

A common sub-title for all plots; defaults to NULL.

main

The main title for the plots, displayed above the captions.

panel

Panel function to be used for adding points to the plots. Defaults to panel.smooth if add.smooth is TRUE, otherwise points.

add.smooth

Logical; indicates whether a smoother should be added to most plots. Defaults to TRUE.

ask

Logical; if TRUE, prompts the user before displaying each plot in a multi-plot layout. Defaults to TRUE.

id.n

Number of extreme points to label in the first three plots.

labels.id

Labels for the extreme points, defaulting to observation numbers if NULL.

label.pos

Positioning of labels in the left and right halves of the graph, applicable for plots 1-3.

cex.id

Magnification factor for point labels.

cex.caption

Size of the plot captions.

cex.oma.man

Size of the overall margin annotation (applies only if sub.caption is above the figures in multi-plot layouts).

...

Additional graphical parameters passed to par.

Details

The Q-Q plots use normalized residuals. Standardized residuals are pre-multiplied by the inverse square-root factor of the estimated error correlation matrix, while random effects are adjusted using the estimated variances from matrix G. Simulation envelopes in Q-Q plots are generated using the hnp package.

The function is partly adapted from plot.lm.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

lccPlot, lcc, mtext, text, plotmath

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
plot(fm1)

## End(Not run)

Internal Function to Produces a Longitudinal Accuracy Plot.

Description

Produces a longitudinal accuracy plot from fitted and sampled values with optional non-parametric confidence intervals.

Details

Returns an initial plot for the longitudinal accuracy correlation.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Generate a Longitudinal Concordance Correlation Plot

Description

Produces a longitudinal concordance correlation plot from fitted and sampled values with optional non-parametric confidence intervals.

Usage

plotBuilder_lcc(rho, ENV.LCC, tk.plot, CCC, tk.plot2, ldb, model, ci, arg, ...)

Arguments

rho

Vector of LCC values.

ENV.LCC

Environment matrix for LCC values, used for confidence intervals.

tk.plot

Time points for LCC values.

CCC

Matrix or list of CCC values.

tk.plot2

Time points for CCC values.

ldb

Number of levels in the data.

model

The model object from which data was extracted.

ci

Logical, indicating if confidence intervals should be included.

arg

List of graphical arguments.

...

Additional arguments for ggplot.

Internal Function to Produce a Longitudinal Pearson Correlation Plot

Description

Produces a longitudinal Pearson correlation plot from fitted and sampled values, with optional non-parametric confidence intervals.

Details

Returns an initial plot for the longitudinal Pearson correlation.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Control Settings for lcc Plots

Description

This function customizes the graphical control settings for plots of the lcc class. It allows for the adjustment of various aspects such as shape, color, and size of plot elements, as well as axis labels. The function returns a list containing all these settings, which can be used in plotting functions for lcc objects.

Usage

plotControl(
  plot = TRUE,
  shape = 16,
  colour = "#1B4F72",
  size = 0.7,
  ci_fill = NULL,
  ci_alpha = NULL,
  point_alpha = NULL,
  xlab = "Time",
  ylab = "LCC"
)

Arguments

plot

Logical flag to include an initial plot. If set to TRUE, a ggplot object with an initial plot for lcc class is returned. Defaults to TRUE.

shape

Numeric value specifying the shape of points in the plot. Acceptable values are from 0 to 25, and 32 to 127. See aes for details on setting shape. Default is 1.

colour

String specifying the color of lines in the plot. Default color is "black".

size

Numeric value specifying the size of lines in the plot, given in millimeters. See aes for details on setting size. Default is 0.5.

xlab

Title for the x-axis, defaulting to "Time".

ylab

Title for the y-axis, defaulting to "LCC".

Value

A list with the specified graphical parameters.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Internal Function to Prepare the plotBuilder_la Function

Description

This function is internally called to prepare the plotBuilder_la function.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Prepare Plot for LPC Function

Description

Internally called function to prepare data for the 'plotBuilder_lpc' function.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

Print the Anova of an lcc Object

Description

Method print for the anova.lcc.

Usage

## S3 method for class 'anova.lcc'
print(x, verbose, ...)

Arguments

x

an object inheriting from class anova.lcc, representing a fitted longitudinal concordance correlation function.

verbose

an optional logical value used to control the amount of printed output. If TRUE, the calling sequences for each fitted model object are printed with the rest of the output, being omitted if verbose = FALSE. Defaults to FALSE.

...

further arguments passed to print.

Details

Modified from anova.lme. For more details see methods for nlme.

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

summary.lcc, lccPlot, lcc

Examples


## Not run: 
## 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(anova(fm1))

## End(Not run)

Print Method for lcc Objects

Description

Prints detailed information about the fitted longitudinal concordance correlation model contained in an lcc object.

Usage

## S3 method for class 'lcc'
print(x, digits = NULL, ...)

Arguments

x

An object of class lcc, representing a fitted longitudinal concordance correlation model.

digits

Minimum number of significant digits to be printed in values. Default is NULL, which uses the default precision.

...

Further arguments passed to print.

Value

The function is used for its side effect of printing and returns the input lcc object invisibly.

See Also

lcc, summary.lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
          method = "Method", time = "Time", qf = 2, qr = 2)
print(fm1)

## End(Not run)

Print Summary of an lcc Object

Description

Provides a detailed summary of a fitted longitudinal concordance correlation model, including AIC, BIC, log-likelihood, and other relevant statistics. The function supports detailed output for different types of model fits.

Usage

## S3 method for class 'summary.lcc'
print(x, verbose = FALSE, digits = NULL, ...)

Arguments

x

An object of class summary.lcc, representing a summarized longitudinal concordance correlation function.

verbose

Logical value to control the amount of printed output for model details. Defaults to FALSE.

digits

Specifies the minimum number of significant digits to be printed in values. Default is NULL.

...

Further arguments passed to print.

See Also

summary.lcc, lccPlot, lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
print(summary(fm1, type = "model"))

## End(Not run)

Extract Random Effects from an lcc Model

Description

Extracts the estimated random effects from a fitted longitudinal concordance correlation model represented by an lcc object. The function returns a data frame with rows corresponding to different groups at a specified level and columns representing the random effects.

Usage

## S3 method for class 'lcc'
ranef(object, ...)

Arguments

object

An object inheriting from class lcc, representing a fitted longitudinal concordance correlation function.

...

Optional arguments passed to the ranef.lme function from the nlme package.

Details

This function is useful for examining the random effects associated with groups or subjects in the model. For a detailed explanation of these effects, see the documentation for nlme objects.

See Also

lcc, coef.lcc,

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
ranef(fm1)

## End(Not run)

Internal Function to Prepare lccModel Function

Description

This is an internally called function used to verify the specification of variance-covariance matrices and likelihood based method.

Author(s)

Code by Don MacQueen

Extract Residuals from a Fitted lcc Model

Description

Extracts residuals from the fitted longitudinal concordance correlation model represented by an lcc object. Different types of residuals can be obtained based on the specified type.

Usage

## S3 method for class 'lcc'
residuals(object, type = "response", ...)

Arguments

object

An object of class lcc, representing a fitted longitudinal concordance correlation function.

type

A character string specifying the type of residuals to extract. Options are "response" for residuals obtained by subtracting the fitted values from the response (default), "pearson" for "response" residuals divided by the estimated within-group standard error, and "normalized" for normalized residuals. Partial matching is used, so only the first character of the type is necessary.

...

Optional arguments passed to the residuals.lme function from the nlme package.

Details

The function provides a convenient way to examine the differences between observed and predicted values in the model. Understanding these residuals can be crucial for model diagnostics and validation. For more information, refer to the methods for nlme objects.

See Also

lcc, summary.lcc, coef.lcc, vcov.lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
residuals(fm1)

## End(Not run)

Hue color simulated data

Description

Simulated hue data set based on papaya's maturation over time considering three methods of measurement.

Usage

data(simulated_hue)

Format

A simulated data frame with 6,000 observations on the mean hue variable. The format is:

Hue numeric; mean hue of papaya's peel
Method a factor with levels labelled from Method 1 to Method 3
Time integer; time in days from 0 to 19
Fruit a factor with 100 levels labelled from 1 to 100
where each level is represented by one fruit.

Details

A total of 100 fruits were observed over 20 days by three methods to evaluate the mean hue of fruit's peel. The aim of the agreement study was to assess how well the methods 2, and 3 agreed with method 1 over time.

See Also

lcc.

Examples

data(simulated_hue)
summary(simulated_hue)
str(simulated_hue)

Hue color simulated data in a randomized block design

Description

Simulated hue data set based on papaya's maturation over time considering four methods of measurement in a randomized block design.

Usage

data(simulated_hue_block)

Format

A simulated data frame with 24,000 observations on the mean hue variable. The format is:

Hue numeric; mean hue of papaya's peel
Block factor with levels labelled from 1 to 3
Method a factor with levels labelled from Method 1, to Method 4
Time integer; time in days from 0 to 19
Fruit a factor with 300 levels labelled from 1 to 300
where each level is represented by one fruit.

Details

A total of 100 fruits by block were observed over 20 days by four methods to evaluate the mean hue of fruit's peel. We considered three blocks in this simulation. The aim of the agreement study was to assess how well the methods 2, 3, and 4 agreed with method 1 over time.

See Also

lcc.

Examples

data(simulated_hue_block)
summary(simulated_hue_block)
str(simulated_hue_block)

Summarize an lcc Object

Description

Additional information about the fit of longitudinal concordance correlation, longitudinal Pearson correlation, and longitudinal accuracy represented by an object of class lcc. The returned object has a print method.

Usage

## S3 method for class 'lcc'
summary(object, type, adjustSigma, verbose, ...)

Arguments

object

an object inheriting from class lcc, representing a fitted longitudinal concordance correlation function.

type

an optional character string specifying the type of output to be returned. If type="model", prints the summary of the polynomial mixed-effects regression model. If type="lcc", prints the summary of the fitted and sampled values for LCC, LPC, and LA as well as the concordance correlation coefficient between fitted values from the model and observed values as goodness of fit (gof) measurement. Defaults to type="model".

adjustSigma

an optional logical value used when type = model. If TRUE and the estimation method used to obtain object was maximum likelihood, the residual standard error is multiplied by sqrt(nobs/(nobs - npar)). See summary.lme for more information. Default is TRUE.

verbose

an optional logical value used to control the amount of output in the print.summary.lme method when type = model is used. Defaults to FALSE.

...

not used.

Value

an object inheriting from class summary.lcc including:

fitted

the fitted values extracted from the lcc object.

gof

the goodness of fit (gof) measurement is calculated using the concordance correlation coefficient between fitted and observed values. Value of 1 denote perfect concordance.

AIC

the Akaike Information Criterion corresponding to object.

BIC

the Bayesian Information Criterion corresponding to object.

logLik

If REML=FALSE, returns the log-likelihood value of the linear mixed-effects model; otherwise, the restricted log-likelihood is returned

Author(s)

Thiago de Paula Oliveira, thiago.paula.oliveira@alumni.usp.br

See Also

AIC, BIC, print.summary.lcc, lcc

Examples


## 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)
summary(fm1, type="model")
summary(fm1, type="lcc")

Regular Sequence Generator for Time Variable

Description

Generates a regular sequence for the time variable, including the unique values from the input time vector. This function is used internally to construct LCC, LPC, and LA curves and their simultaneous confidence intervals.

Usage

time_lcc(time, from, to, n)

Arguments

time

A numeric vector of unique time values.

from

The starting (minimum) value for the time sequence.

to

The ending (maximum) value for the time sequence.

n

Desired length of the sequence (integer). Typically, a value between 30 and 50 is adequate.

Value

A numeric vector containing a regular sequence of time values, including the unique values from the input time vector.

Examples

data(hue)
attach(hue)
time_lcc(time = Time, from = min(Time), to = max(Time), n = 30)
detach(hue)

Extract Variance-Covariance Matrix of the Fixed Effects for an lcc Object

Description

Extracts the variance-covariance matrix of the fixed effects from a fitted lcc model object. This function provides insights into the variability and covariance structure of the fixed effects in the model.

Usage

## S3 method for class 'lcc'
vcov(object, ...)

Arguments

object

An object of class lcc, representing a fitted longitudinal concordance correlation model.

...

Optional arguments passed to the vcov.lme function from the nlme package.

Details

The function specifically retrieves the variance-covariance matrix associated with the fixed effects of the lcc object, which is useful for understanding the relationship between these effects. For more details on variance-covariance matrices, refer to the methods for nlme objects.

See Also

summary.lcc, lccPlot, lcc, coef.lcc

Examples

## Not run: 
fm1 <- lcc(data = hue, subject = "Fruit", resp = "H_mean",
           method = "Method", time = "Time", qf = 2, qr = 2)
vcov(fm1)

## End(Not run)