% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ccc_glmm.R
\name{ccc_glmm}
\alias{ccc_glmm}
\title{Poisson GLMM concordance correlation for count agreement}
\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
)
}
\arguments{
\item{data}{A data frame containing the measurements.}

\item{response}{Character. Name of the non-negative integer-like count column.}

\item{subject}{Character. Name of the subject identifier column.}

\item{method}{Character. Name of the method/observer column.}

\item{replicate}{Optional character. Name of the replicate column. If
\code{NULL}, one replicate per subject-method cell is assumed.}

\item{family}{Character. Currently only \code{"poisson"} is implemented.}

\item{link}{Character. Currently only \code{"log"} is implemented.}

\item{overdispersion}{Character. \code{"none"} fixes \eqn{\phi = 1};
\code{"pearson"} estimates \eqn{\phi} from post-fit Pearson residuals.}

\item{include_subject_method}{Logical. If \code{TRUE}, include an additional
subject-by-method random intercept variance component.}

\item{ci}{Logical. If \code{TRUE}, compute delta-method confidence intervals
for the total, inter-method, and intra-method CCC estimates.}

\item{conf_level}{Confidence level for delta-method confidence intervals.}

\item{max_iter}{Positive integer. Maximum optimiser iterations.}

\item{tol}{Positive numeric convergence tolerance.}

\item{n_threads}{Integer \eqn{\geq 1}. Number of OpenMP threads to make
available to compiled code.}

\item{verbose}{Logical. If \code{TRUE}, emit progress messages.}
}
\value{
A symmetric numeric matrix of class \code{c("ccc_glmm", "ccc")} containing
\code{rho_ccc}. Additional pairwise matrices are stored as attributes:
\itemize{
\item \code{rho_ccc_inter}: agreement for replicated method averages.
\item \code{rho_ccc_intra_method1}, \code{rho_ccc_intra_method2}:
method-specific repeatability coefficients.
\item \code{sigma2_subject}, \code{sigma2_method},
\code{sigma2_subject_method}: fitted variance/disagreement components.
\item \code{phi}, \code{mu}, \code{precision}, \code{accuracy}: fitted
count-scale diagnostics used in the CCC decomposition.
\item \code{beta0}, \code{beta_method}, \code{nll}, \code{logLik},
\code{convergence_code}: fitting diagnostics.
\item \code{n_obs}, \code{n_subjects}, \code{m_reps}: design diagnostics.
\item when \code{ci = TRUE}, standard error and confidence-limit matrices
for \code{rho_ccc}, \code{rho_ccc_inter},
\code{rho_ccc_intra_method1}, and \code{rho_ccc_intra_method2}.
}
}
\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.
}
\details{
The fitted model for a pair of methods is
\deqn{
Y_{ijl} \mid \alpha_i, \gamma_{ij}
  \sim \mathrm{Poisson}(\mu_{ijl}),
\qquad
\log(\mu_{ijl}) = \eta_j + \alpha_i + \gamma_{ij},
}
where \eqn{i} indexes subjects, \eqn{j} indexes methods, and \eqn{l}
indexes replicate readings. The subject effect \eqn{\alpha_i} captures
between-subject heterogeneity. When \code{include_subject_method = TRUE},
\eqn{\gamma_{ij}} captures subject-specific method departures; otherwise it
is fixed at zero. The fixed method difference contributes to disagreement
through \code{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, \code{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.

\code{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 \eqn{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.

\code{rho_ccc_intra_method1} and \code{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.

\code{precision} isolates the share of non-systematic variation attributable
to subject ranking/heterogeneity, while \code{accuracy} is the ratio
\code{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.

\code{overdispersion = "none"} fixes \eqn{\phi = 1}, the Poisson model.
\code{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.
\subsection{Confidence intervals}{

When \code{ci = TRUE}, large-sample confidence intervals are computed for
\code{rho_ccc}, \code{rho_ccc_inter}, \code{rho_ccc_intra_method1}, and
\code{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:
\deqn{
\mathrm{Var}\{g(\hat\theta)\}
  \approx
  \nabla g(\hat\theta)^\top
  \mathrm{Var}(\hat\theta)
  \nabla g(\hat\theta),
}
where \eqn{g(\theta)} is the relevant CCC function. Gradients are evaluated
numerically by central finite differences. The reported point estimates are
not replaced by \eqn{g(\hat\theta)}; they remain the values from the standard
point-estimate path.

Intervals are formed on a Fisher-Z transformed CCC scale,
\eqn{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 \eqn{[0, 1]}.

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

This function currently implements the Poisson-log count-data case. The
\code{family} and \code{link} arguments are present for API stability and
future extensions, but only \code{family = "poisson"} and
\code{link = "log"} are currently supported. The returned estimates are
variance-component CCCs constrained to \eqn{[0, 1]}; they are not Lin's raw
moment CCC and should not be expected to produce negative values.
}
}
\examples{
# 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)

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