ccc_glmm: Poisson GLMM concordance correlation for count agreement

Description

Computes pairwise generalized concordance correlation coefficients (CCC) for count outcomes measured repeatedly by two or more methods, observers, or devices. The current implementation fits Poisson-log generalized linear mixed models and reports total, inter-method, and intra-method agreement summaries from the fitted mean and variance components.

Usage

ccc_glmm(
  data,
  response,
  subject,
  method,
  replicate = NULL,
  family = "poisson",
  link = "log",
  overdispersion = c("none", "pearson"),
  include_subject_method = FALSE,
  ci = FALSE,
  conf_level = 0.95,
  max_iter = 1000,
  tol = 1e-08,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE
)

Value

A symmetric numeric matrix of class c("ccc_glmm", "ccc") containing rho_ccc. Additional pairwise matrices are stored as attributes:

rho_ccc_inter: agreement for replicated method averages.
rho_ccc_intra_method1, rho_ccc_intra_method2: method-specific repeatability coefficients.
sigma2_subject, sigma2_method, sigma2_subject_method: fitted variance/disagreement components.
phi, mu, precision, accuracy: fitted count-scale diagnostics used in the CCC decomposition.
beta0, beta_method, nll, logLik, convergence_code: fitting diagnostics.
n_obs, n_subjects, m_reps: design diagnostics.
when ci = TRUE, standard error and confidence-limit matrices for rho_ccc, rho_ccc_inter, rho_ccc_intra_method1, and rho_ccc_intra_method2.

Arguments

data: A data frame containing the measurements.
response: Character. Name of the non-negative integer-like count column.
subject: Character. Name of the subject identifier column.
method: Character. Name of the method/observer column.
replicate: Optional character. Name of the replicate column. If NULL, one replicate per subject-method cell is assumed.
family: Character. Currently only "poisson" is implemented.
link: Character. Currently only "log" is implemented.
overdispersion: Character. "none" fixes $\phi = 1$; "pearson" estimates $\phi$ from post-fit Pearson residuals.
include_subject_method: Logical. If TRUE, include an additional subject-by-method random intercept variance component.
ci: Logical. If TRUE, compute delta-method confidence intervals for the total, inter-method, and intra-method CCC estimates.
conf_level: Confidence level for delta-method confidence intervals.
max_iter: Positive integer. Maximum optimiser iterations.
tol: Positive numeric convergence tolerance.
n_threads: Integer $\geq 1$. Number of OpenMP threads to make available to compiled code.
verbose: Logical. If TRUE, emit progress messages.

Details

The fitted model for a pair of methods is $$ Y_{ijl} \mid \alpha_i, \gamma_{ij} \sim \mathrm{Poisson}(\mu_{ijl}), \qquad \log(\mu_{ijl}) = \eta_j + \alpha_i + \gamma_{ij}, $$ where $i$ indexes subjects, $j$ indexes methods, and $l$ indexes replicate readings. The subject effect $\alpha_i$ captures between-subject heterogeneity. When include_subject_method = TRUE, $\gamma_{ij}$ captures subject-specific method departures; otherwise it is fixed at zero. The fixed method difference contributes to disagreement through sigma2_method.

The model is fitted by marginal maximum likelihood using Gauss-Hermite quadrature. The random-intercept model uses 40 quadrature points. The subject-by-method model uses tensor-product quadrature with fewer points per dimension because it integrates over a three-dimensional subject block. The reported CCC quantities are then computed from the fitted Poisson-log mean and variance components.

The main matrix value, rho_ccc, is the total agreement coefficient. Use it as the primary overall count-agreement summary when each individual reading is the unit of inference. It penalizes lack of between-subject signal, systematic method bias, subject-by-method disagreement, and Poisson residual variation.

rho_ccc_inter is the inter-method agreement coefficient for averages over replicated readings. It is useful when decisions are based on the mean of $m$ replicate readings per subject-method cell. Replication reduces only the residual count variation term; it does not dilute systematic method disagreement or between-subject variation.

rho_ccc_intra_method1 and rho_ccc_intra_method2 are method-specific repeatability coefficients. Use them to diagnose whether one method is internally more repeatable than the other on the count scale. These are not direct method-comparison coefficients; they describe within-method reproducibility after accounting for the fitted mean and random effects.

precision isolates the share of non-systematic variation attributable to subject ranking/heterogeneity, while accuracy is the ratio rho_ccc / precision. Low accuracy with reasonable precision indicates that disagreement is driven mainly by method bias or extra method-specific variation rather than poor subject discrimination.

overdispersion = "none" fixes $\phi = 1$, the Poisson model. overdispersion = "pearson" replaces the residual term by a Pearson dispersion estimate. Use the Pearson adjustment as a sensitivity analysis when counts appear more variable than the Poisson model allows; it should generally reduce CCC when extra-Poisson variation is present.

Confidence intervals

When ci = TRUE, large-sample confidence intervals are computed for rho_ccc, rho_ccc_inter, rho_ccc_intra_method1, and rho_ccc_intra_method2. The implementation uses a delta-method standard error based on the fitted GLMM parameter vector and the inverse Hessian of the marginal negative log-likelihood: $$ \mathrm{Var}\{g(\hat\theta)\} \approx \nabla g(\hat\theta)^\top \mathrm{Var}(\hat\theta) \nabla g(\hat\theta), $$ where $g(\theta)$ is the relevant CCC function. Gradients are evaluated numerically by central finite differences. The reported point estimates are not replaced by $g(\hat\theta)$; they remain the values from the standard point-estimate path.

Intervals are formed on a Fisher-Z transformed CCC scale, $z = 0.5\log\{(1+\rho)/(1-\rho)\}$, and then back-transformed to the CCC scale. This is the same broad strategy used elsewhere for CCC-style intervals because it is usually more stable than a raw Wald interval near the boundaries. CI limits are not forcibly truncated to $[0, 1]$.

For overdispersion = "pearson", $\phi$ is a post-fit Pearson dispersion estimate rather than a likelihood parameter. Delta-method confidence intervals therefore treat $\phi$ as fixed and a warning is issued.

This function currently implements the Poisson-log count-data case. The family and link arguments are present for API stability and future extensions, but only family = "poisson" and link = "log" are currently supported. The returned estimates are variance-component CCCs constrained to $[0, 1]$; they are not Lin's raw moment CCC and should not be expected to produce negative values.

References

Carrasco JL (2010). A generalized concordance correlation coefficient based on the variance components generalized linear mixed models for overdispersed count data. Biometrics.

Examples

Run this code

# Example 1: overall agreement for two Poisson count methods.
# Here the methods have similar means, so rho_ccc is mainly driven by
# between-subject count heterogeneity versus Poisson residual noise.
set.seed(1)
df1 <- expand.grid(
  subject = factor(seq_len(12)),
  method = factor(c("A", "B")),
  replicate = factor(seq_len(2))
)
subject_eff <- rnorm(12, 0, 0.5)
df1$eta <- 1.1 + subject_eff[as.integer(df1$subject)]
df1$y <- rpois(nrow(df1), exp(df1$eta))
# \donttest{
fit1 <- ccc_glmm(df1, "y", "subject", "method", replicate = "replicate",
ci = TRUE)
fit1
summary(fit1)
estimate(fit1)
tidy(fit1)
ci(fit1)
confint(fit1)
# }

# Example 2: method bias lowers total agreement.
# This tests whether a systematic method shift is reflected in rho_ccc
# and the accuracy component.
set.seed(2)
df2 <- expand.grid(
  subject = factor(seq_len(12)),
  method = factor(c("A", "B")),
  replicate = factor(seq_len(2))
)
subject_eff <- rnorm(12, 0, 0.6)
df2$eta <- 1.0 + subject_eff[as.integer(df2$subject)] +
  ifelse(df2$method == "B", 0.6, 0)
df2$y <- rpois(nrow(df2), exp(df2$eta))
fit2 <- ccc_glmm(df2, "y", "subject", "method", replicate = "replicate")
summary(fit2)

# Example 3: subject-by-method variation.
# This tests whether individual subjects respond differently by method.
# The subject-method component is useful when disagreement is not explained
# by a single fixed method bias.
set.seed(3)
df3 <- expand.grid(
  subject = factor(seq_len(10)),
  method = factor(c("A", "B")),
  replicate = factor(seq_len(2))
)
subject_eff <- rnorm(10, 0, 0.4)
subject_method_eff <- matrix(rnorm(20, 0, 0.25), nrow = 10)
method_id <- as.integer(df3$method)
df3$eta <- 1.1 + subject_eff[as.integer(df3$subject)] +
  subject_method_eff[cbind(as.integer(df3$subject), method_id)]
df3$y <- rpois(nrow(df3), exp(df3$eta))
# \donttest{
fit3 <- ccc_glmm(
  df3, "y", "subject", "method",
  replicate = "replicate",
  include_subject_method = TRUE
)
attr(fit3, "sigma2_subject_method")
# }

# Example 4: four methods.
# This tests pairwise agreement across several count methods and helps
# identify which method pairs have the strongest total CCC.
set.seed(4)
df4 <- expand.grid(
  subject = factor(seq_len(10)),
  method = factor(c("A", "B", "C", "D")),
  replicate = factor(seq_len(2))
)
subject_eff <- rnorm(10, 0, 0.5)
method_bias <- c(A = 0, B = 0.1, C = 0.4, D = -0.2)
df4$eta <- 1.0 + subject_eff[as.integer(df4$subject)] +
  method_bias[as.character(df4$method)]
df4$y <- rpois(nrow(df4), exp(df4$eta))
fit4 <- ccc_glmm(df4, "y", "subject", "method", replicate = "replicate")
fit4
summary(fit4, n = 3)

Run the code above in your browser using DataLab