% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cia_repeated.R
\name{cia_rm}
\alias{cia_rm}
\alias{summary.cia_rm}
\alias{print.cia_rm}
\alias{print.summary.cia_rm}
\alias{plot.cia_rm}
\title{Repeated-Measures Coefficient of Individual Agreement}
\usage{
cia_rm(
  data,
  response,
  subject,
  method = NULL,
  time = NULL,
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  estimator = c("vc_constrained", "mom_unconstrained"),
  inference = c("delta", "bootstrap", "none"),
  verbose = FALSE,
  digits = 4,
  use_message = TRUE,
  homogeneous = FALSE,
  B = 1000L,
  seed = NULL,
  ...
)

\method{summary}{cia_rm}(
  object,
  digits = 4,
  ci_digits = 3,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{print}{cia_rm}(
  x,
  digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{print}{summary.cia_rm}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{cia_rm}(
  x,
  title = NULL,
  facet_by_pair = FALSE,
  facet_scales = c("fixed", "free_y"),
  show_ci = NULL,
  show_common = TRUE,
  point_size = 2.2,
  line_size = 0.7,
  ci_alpha = 0.16,
  ci_linewidth = 0.45,
  ...
)
}
\arguments{
\item{data}{A data frame in long format.}

\item{response}{Character scalar naming the numeric response column.}

\item{subject}{Character scalar naming the subject identifier column.}

\item{method}{Character scalar naming the method column. Required.}

\item{time}{Character scalar naming the repeated condition column. Required.}

\item{ci}{Logical; if \code{TRUE}, attach confidence intervals.}

\item{conf_level}{Confidence level for intervals when \code{ci = TRUE}.}

\item{n_threads}{Positive integer thread hint passed to the C++ backend.}

\item{estimator}{One of \code{"vc_constrained"} or \code{"mom_unconstrained"}.
\code{"vc_constrained"} is the default bounded variance-component estimator. It
constrains the estimated subject-method variance component to be
non-negative before converting it back to CIA. \code{"mom_unconstrained"} is
the raw method-of-moments CIA ratio and may exceed 1.}

\item{inference}{One of \code{"delta"}, \code{"bootstrap"}, or \code{"none"}. The delta
method is the default when \code{ci = TRUE}.}

\item{verbose}{Logical; if \code{TRUE}, emit progress messages for CI work.}

\item{digits}{Integer print precision carried on the returned object.}

\item{use_message}{Logical; if \code{TRUE}, use package messaging helpers when
\code{verbose = TRUE}.}

\item{homogeneous}{Logical; if \code{TRUE}, also compute the pooled/common CIA
from the reduced model without method-time interaction.}

\item{B}{Number of subject-bootstrap resamples when \code{ci = TRUE}.}

\item{seed}{Optional positive integer seed for reproducible bootstrap
resampling.}

\item{...}{Additional arguments passed to \code{ggplot2::theme()}.}

\item{object}{A \code{cia_rm} object.}

\item{ci_digits}{Integer; number of digits for confidence interval bounds.}

\item{n}{Optional row threshold for compact preview output.}

\item{topn}{Optional number of leading/trailing rows to show when truncated.}

\item{max_vars}{Optional maximum number of visible columns.}

\item{width}{Optional display width.}

\item{show_ci}{Logical; if \code{TRUE} and confidence intervals are present, show
them on the plot. By default this is inferred from the object class.}

\item{x}{A \code{summary.cia_rm} object.}

\item{title}{Optional plot title.}

\item{facet_by_pair}{Logical; if \code{TRUE}, draw one panel per method pair.}

\item{facet_scales}{Passed to \code{ggplot2::facet_wrap(scales = ...)} when
\code{facet_by_pair = TRUE}. One of \code{"fixed"} or \code{"free_y"}.}

\item{show_common}{Logical; if \code{TRUE} and common estimates are available,
draw dashed horizontal reference lines for the pooled/common CIA.}

\item{point_size}{Numeric point size passed to \code{ggplot2::geom_point()}.}

\item{line_size}{Numeric line width passed to \code{ggplot2::geom_line()}.}

\item{ci_alpha}{Numeric alpha used for confidence ribbons in continuous
plots.}

\item{ci_linewidth}{Numeric line width used for confidence-interval
error bars in categorical plots.}
}
\value{
If \code{ci = FALSE}, the result is a list of class \code{c("cia_rm", "cia")}.
If \code{ci = TRUE}, the result is a list of class
\code{c("cia_rm", "cia_ci", "cia")}.

Main components:
\itemize{
\item \code{est}: condition-specific pairwise CIA estimates.
\item \code{common}: pairwise overall summary CIA estimates from the reduced
homogeneous model.
\item \code{condition}: the ordered condition/time labels used in the output.
\item \code{se}: standard errors for \code{est} when \code{ci = TRUE}.
\item \code{lwr.ci} and \code{upr.ci}: lower and upper confidence limits for \code{est}
when \code{ci = TRUE}.
\item \code{common.se}: standard errors for \code{common} when \code{ci = TRUE}.
\item \code{common.lwr.ci} and \code{common.upr.ci}: lower and upper confidence
limits for \code{common} when \code{ci = TRUE}.
}

When there are three or more methods, additional overall multi-method
components are returned:
\itemize{
\item \code{overall}: condition-specific overall CIA across all methods.
\item \code{overall.common}: the overall summary CIA across all methods when
\code{homogeneous = TRUE}.
\item \code{overall.se}: standard errors for \code{overall} when \code{ci = TRUE}.
\item \code{overall.lwr.ci} and \code{overall.upr.ci}: lower and upper confidence
limits for \code{overall} when \code{ci = TRUE}.
\item \code{overall.common.se}: standard errors for \code{overall.common} when
\code{ci = TRUE}.
\item \code{overall.common.lwr.ci} and \code{overall.common.upr.ci}: lower and upper
confidence limits for \code{overall.common} when \code{ci = TRUE}.
}

The object carries pairwise ANOVA diagnostics as attributes, including
\code{sigma2_error}, \code{sigma2_subject_method}, \code{repeatability},
\code{homogeneity_F}, \code{homogeneity_p}, \code{df_method_time}, \code{df_error},
\code{n_obs}, \code{n_subjects}, \code{n_methods}, \code{n_times}, \code{time_levels}, and
\code{method_levels}. Here \code{homogeneity_F} is the method-time interaction test
statistic for each method pair, and \code{homogeneity_p} is the corresponding
p-value for the null hypothesis of homogeneous agreement across conditions.
}
\description{
Computes pairwise repeated-measures coefficients of individual agreement
(CIA) from long-format matched repeated-measures data using the categorical
condition ANOVA formulation of Haber, Gao, and Barnhart (2010).
}
\details{
\code{cia_rm()} is for matched repeated measurements under conditions such as
raters, visits, laboratories, treatments, or time points. It is not a
technical-replicate estimator. If the same subject has true technical
replicates within each subject-method cell, use \code{\link[=cia]{cia()}} instead.

Let \code{Y_ijk} denote the measurement on subject \code{i}, with method \code{j}, under
condition \code{k}, and consider the model
\deqn{
Y_{ijk} = \mu + \alpha_i + \beta_j + \gamma_k +
(\alpha\beta)_{ij} + (\alpha\gamma)_{ik} + (\beta\gamma)_{jk} + e_{ijk}.
}
Here subject is random, method and time/condition are fixed,
subject-method and subject-time are random interactions, method-time is a
fixed interaction, and \code{e_ijk} is the residual.

For each method pair and condition \code{k}, the repeated-measures CIA is
\deqn{
\psi_k = \frac{2\sigma_e^2}{d_k^2 + 2\sigma_{\alpha\beta}^2 + 2\sigma_e^2},
}
where \code{d_k} is the condition-specific mean difference between the two
methods, \eqn{\sigma_{\alpha\beta}^2} is the subject-method variance
component, and \eqn{\sigma_e^2} is the residual variance component.

The function fits this estimator separately to every method pair. The
homogeneity of agreement across conditions is tested by the method-time
interaction:
\deqn{
F = \frac{MS_{\mathrm{method}\times\mathrm{time}}}{MS_{\mathrm{error}}}.
}
The returned \code{homogeneity_F} attribute stores this test statistic for each
method pair, and \code{homogeneity_p} stores the corresponding upper-tail
\code{F}-test p-value using degrees of freedom \code{df_method_time} and \code{df_error}.
Larger \code{homogeneity_F} values and smaller \code{homogeneity_p} values indicate
stronger evidence that agreement changes across conditions, meaning that the
condition-specific CIA curves should be interpreted directly rather than
relying on a single pooled/common coefficient. Conversely, a small
\code{homogeneity_F} and a non-small \code{homogeneity_p} indicate that the data do
not show strong evidence of method-by-condition heterogeneity, so a common
estimate may be a reasonable summary if it is scientifically meaningful.

When \code{homogeneous = TRUE}, the function also reports a common or pooled CIA
for each method pair from the reduced model that pools the method-time sum of
squares into the residual term. That common estimate is meaningful only when
agreement is reasonably homogeneous across conditions.

Confidence intervals can be computed by a delta-method normal approximation
or by a subject-level percentile bootstrap. The delta-method interval is the
default. For each method pair and condition \code{k}, let
\eqn{\hat\psi_k} be the ANOVA estimator, let \eqn{g_k} be its numerical
gradient with respect to the subject-level moment vector, and let
\eqn{\Sigma} be the empirical covariance matrix of that moment vector divided
by the number of subjects. The delta-method standard error is
\deqn{
\widehat{\mathrm{se}}(\hat\psi_k) =
\sqrt{\max\left(g_k^\top \Sigma g_k, 0\right)}.
}
The raw normal interval is
\deqn{
\hat\psi_k \pm z_{1-\alpha/2}\,\widehat{\mathrm{se}}(\hat\psi_k).
}
Under the bootstrap option, the interval is given by the empirical
percentile limits from subject-resampled estimates. The argument
\code{estimator} controls whether the reported result is the literal
method-of-moments ratio or a bounded variance-component variant. Under
\code{estimator = "vc_constrained"}, the estimated subject-method variance
component is constrained to be non-negative before converting it back to CIA,
and the reported interval limits are also truncated to the CIA parameter
space,
\deqn{
\mathrm{lwr} = \max(0, \mathrm{lwr}_{\mathrm{raw}}), \qquad
\mathrm{upr} = \min(1, \mathrm{upr}_{\mathrm{raw}}).
}
This keeps the reported interval inside the CIA parameter space \verb{[0, 1]}.
Use \code{estimator = "mom_unconstrained"} to inspect the literal raw
method-of-moments estimator and the corresponding unbounded interval on the
estimator scale.

The current implementation requires exactly one observation in every
subject-method-time cell. It therefore targets the balanced repeated-measures
ANOVA setting from the cited paper and returns an error otherwise.
}
\examples{
# Example 1
set.seed(1)
dat_rater <- expand.grid(
  id = factor(sprintf("s\%02d", 1:8)),
  method = factor(c("Device_A", "Device_B")),
  time = factor(c("Rater_1", "Rater_2", "Rater_3")),
  KEEP.OUT.ATTRS = FALSE
)
subj_eff <- rnorm(nlevels(dat_rater$id), sd = 1)[dat_rater$id]
method_shift <- c(Device_A = 0, Device_B = 0.25)[dat_rater$method]
rater_shift <- c(Rater_1 = 0, Rater_2 = 0.15, Rater_3 = -0.10)[dat_rater$time]
interaction_shift <- ifelse(
  dat_rater$method == "Device_B" & dat_rater$time == "Rater_3",
  0.12, 0
)
dat_rater$y <- subj_eff + method_shift + rater_shift +
  interaction_shift + rnorm(nrow(dat_rater), sd = 0.25)

fit_rater <- cia_rm(
  dat_rater,
  response = "y",
  subject = "id",
  method = "method",
  time = "time",
  homogeneous = TRUE
)
print(fit_rater)
summary(fit_rater)
estimate(fit_rater)
tidy(fit_rater)
plot(fit_rater)

# Example 2
set.seed(2)
dat_time <- expand.grid(
  id = factor(sprintf("s\%02d", 1:10)),
  method = factor(c("Assay_A", "Assay_B", "Assay_C", "Assay_D")),
  time = factor(
    c("baseline", "week2", "month1", "month2", "month3"),
    levels = c("baseline", "week2", "month1", "month2", "month3")
  ),
  KEEP.OUT.ATTRS = FALSE
)
subj_eff <- rnorm(nlevels(dat_time$id), sd = 0.9)[dat_time$id]
method_shift <- c(Assay_A = 0, Assay_B = 0.20, Assay_C = -0.10, Assay_D = 0.35)[dat_time$method]
time_shift <- c(
  baseline = 0, week2 = 0.10, month1 = 0.22, month2 = 0.32, month3 = 0.42
)[dat_time$time]
interaction_shift <- ifelse(dat_time$method == "Assay_B" & dat_time$time == "month3", 0.10, 0) +
  ifelse(dat_time$method == "Assay_D" & dat_time$time == "month2", -0.08, 0)
dat_time$y <- subj_eff + method_shift + time_shift +
  interaction_shift + rnorm(nrow(dat_time), sd = 0.30)

fit_time <- cia_rm(
  dat_time,
  response = "y",
  subject = "id",
  method = "method",
  time = "time",
  ci = TRUE
)
print(fit_time)
plot(fit_time)

# Example 3
set.seed(3)
dat_days <- expand.grid(
  id = factor(sprintf("s\%02d", 1:12)),
  method = factor(c("Sensor_A", "Sensor_B", "Sensor_C")),
  time = 1:15,
  KEEP.OUT.ATTRS = FALSE
)
subj_eff <- rnorm(nlevels(dat_days$id), sd = 0.8)[dat_days$id]
method_shift <- c(Sensor_A = 0, Sensor_B = 0.15, Sensor_C = -0.08)[dat_days$method]
day_trend <- 0.05 * dat_days$time
interaction_shift <- ifelse(dat_days$method == "Sensor_B", 0.01 * dat_days$time, 0) +
  ifelse(dat_days$method == "Sensor_C", -0.005 * dat_days$time, 0)
dat_days$y <- subj_eff + method_shift + day_trend +
  interaction_shift + rnorm(nrow(dat_days), sd = 0.22)

fit_days <- cia_rm(
  dat_days,
  response = "y",
  subject = "id",
  method = "method",
  time = "time",
  ci = TRUE
)
plot(fit_days, facet_by_pair = TRUE)

}
\references{
Haber M, Gao J, Barnhart HX. (2010). Evaluation of agreement between
measurement methods from data with matched repeated measurements via the
coefficient of individual agreement. \emph{Journal of Data Science}, 8,
457-469.

Barnhart HX, Kosinski AS, Haber M. (2007). Assessing individual agreement.
\emph{Journal of Biopharmaceutical Statistics}, 17(4), 697-719.
}
\seealso{
\code{\link[=ccc_rm_reml]{ccc_rm_reml()}}, \code{\link[=icc_rm_reml]{icc_rm_reml()}}, and \code{\link[=cia]{cia()}}.
}
\author{
Thiago de Paula Oliveira
}
