% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/icc.R
\name{icc}
\alias{icc}
\alias{print.icc}
\alias{summary.icc}
\alias{print.summary.icc}
\alias{print.icc_overall}
\alias{summary.icc_overall}
\alias{print.summary.icc_overall}
\title{Intraclass Correlation for Wide Data}
\usage{
icc(
  data,
  model = c("oneway", "twoway_random", "twoway_mixed"),
  type = c("consistency", "agreement"),
  unit = c("single", "average"),
  scope = c("pairwise", "overall"),
  na_method = c("error", "pairwise", "complete"),
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE,
  ...
)

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

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

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

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

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

\method{print}{summary.icc_overall}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)
}
\arguments{
\item{data}{A numeric matrix or data frame with at least two numeric columns.}

\item{model}{Character scalar selecting the classical ICC model.
\code{"oneway"} uses the one-way random-effects formulation,
\code{"twoway_random"} uses the two-way random-effects formulation, and
\code{"twoway_mixed"} uses the two-way mixed-effects formulation.}

\item{type}{Character scalar selecting the reliability target.
\code{"consistency"} does not penalize systematic column mean differences in
the same way as absolute agreement, whereas \code{"agreement"} targets absolute
agreement and therefore incorporates those differences.}

\item{unit}{Character scalar selecting whether the coefficient refers to a
single measurement (\code{"single"}) or to the mean of multiple measurements
(\code{"average"}). For \code{scope = "pairwise"}, the average-measure coefficient
always uses \code{k = 2}. For \code{scope = "overall"}, it uses the full number of
analysed columns.}

\item{scope}{Character scalar selecting the analysis target.
\code{"pairwise"} returns the symmetric matrix of two-column ICCs.
\code{"overall"} returns the six-row overall ANOVA table for the full set of
columns. Choose \code{"pairwise"} when the question is about specific column
pairs; choose \code{"overall"} when the question is about the full set of
columns analysed jointly.}

\item{na_method}{Character scalar controlling missing-data handling.
\code{"error"} rejects missing, \code{NaN}, and infinite values before
estimation. \code{"pairwise"} uses pair-specific complete cases for
\code{scope = "pairwise"} and complete rows across all analysed columns
for \code{scope = "overall"}. \code{"complete"} performs listwise
deletion once across all analysed columns before ICC estimation.}

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

\item{conf_level}{Confidence level for the interval output. Ignored when
\code{ci = FALSE}.}

\item{n_threads}{Integer number of OpenMP threads.}

\item{verbose}{Logical; if \code{TRUE}, report how many threads are requested.}

\item{...}{Passed to the underlying print helper.}

\item{x}{An intraclass-correlation object returned by \code{icc()}, or a summary
object returned by \code{summary()} for that fit.}

\item{digits}{Integer; number of digits to print.}

\item{ci_digits}{Integer; number of digits for CI 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; \code{NULL} derives
this from console width.}

\item{width}{Optional display width; defaults to \code{getOption("width")}.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{object}{An intraclass-correlation object returned by \code{icc()}.}
}
\value{
For \code{scope = "pairwise"}, if \code{ci = FALSE}, a symmetric matrix of class
\code{icc}. If \code{ci = TRUE}, a list with elements \code{est}, \code{lwr.ci}, and \code{upr.ci}
and class \code{c("icc", "icc_ci")}.

For \code{scope = "overall"}, a list of class \code{c("icc_overall", "icc")} with a
coefficient table, ANOVA table, and mean-square metadata. The coefficient
table always includes the standard six overall coefficients. Confidence
interval columns are attached when \code{ci = TRUE}.

All outputs carry attributes describing the selected model, type, unit, and
method.
}
\description{
Computes intraclass correlation coefficients for the numeric columns of a
matrix or data frame using the classical ANOVA mean-square formulas. The
output can be either a pairwise matrix across columns or an overall
all-column coefficient table.
}
\details{
Each column is treated as a measurement channel, method, or rater and each
row is treated as a subject.

The function supports two distinct analysis targets.
\itemize{
\item \code{scope = "pairwise"} answers: "how reliable is each specific column pair?"
Each estimate is based on exactly two columns and the output is a symmetric
matrix.
\item \code{scope = "overall"} answers: "how reliable is the full set of columns when
analysed jointly?" The output is the standard six-form overall ANOVA table
(\code{ICC1}, \code{ICC2}, \code{ICC3}, \code{ICC1k}, \code{ICC2k}, \code{ICC3k}).
}

These two scopes do not target the same quantity. The overall coefficients
are computed from the full multi-column ANOVA decomposition and are not
obtained by averaging or otherwise aggregating the pairwise matrix.

The three main choice arguments determine the classical ICC form.
\itemize{
\item \code{model} controls the rater structure:
\itemize{
\item \code{"oneway"} uses the one-way random-effects formulation.
\item \code{"twoway_random"} uses the two-way random-effects formulation.
\item \code{"twoway_mixed"} uses the two-way mixed-effects formulation.
}
\item \code{type} controls whether systematic column mean differences are penalized:
\itemize{
\item \code{"consistency"} targets consistency across columns.
\item \code{"agreement"} targets absolute agreement across columns.
}
\item \code{unit} controls whether reliability refers to one measurement or to the
average of multiple measurements:
\itemize{
\item \code{"single"} returns the single-measure coefficient.
\item \code{"average"} returns the average-measure coefficient.
}
}

The supported mappings are:
\itemize{
\item \verb{model = "oneway", type = "consistency", unit = "single"} gives \code{ICC1}.
\item \verb{model = "oneway", type = "consistency", unit = "average"} gives \code{ICC1k}.
\item \verb{model = "twoway_random", type = "agreement", unit = "single"} gives \code{ICC2}.
\item \verb{model = "twoway_random", type = "agreement", unit = "average"} gives \code{ICC2k}.
\item \verb{model = "twoway_random", type = "consistency", unit = "single"} gives \code{ICC3}.
\item \verb{model = "twoway_random", type = "consistency", unit = "average"} gives \code{ICC3k}.
\item \verb{model = "twoway_mixed", type = "agreement", unit = "single"} gives the
mixed-effects absolute-agreement analogue with the same classical point
formula as \code{ICC2}.
\item \verb{model = "twoway_mixed", type = "agreement", unit = "average"} gives the
corresponding average-measure analogue.
\item \verb{model = "twoway_mixed", type = "consistency", unit = "single"} gives \code{ICC3}.
\item \verb{model = "twoway_mixed", type = "consistency", unit = "average"} gives \code{ICC3k}.
}

The combination \verb{model = "oneway", type = "agreement"} is not defined here
and returns an error.

For \code{scope = "pairwise"}, the point estimates are computed in \verb{C++} directly
from the two-column ANOVA mean squares for each complete pair. For
\code{unit = "average"}, the implementation uses \code{k = 2} because each estimate is
based on exactly two columns.

For \code{scope = "overall"}, the point estimates are computed jointly from the
full wide matrix using the classical ANOVA decomposition over all columns.
Here the average-measure coefficients use \code{k = ncol(data)} after any row
filtering required by \code{na_method}.

Missing-data handling depends on \code{scope}:
\itemize{
\item with \code{na_method = "error"}, missing values are rejected before estimation;
\item with \code{na_method = "pairwise"} and \code{scope = "pairwise"}, each pair uses its
own complete-case overlap;
\item with \code{na_method = "pairwise"} and \code{scope = "overall"}, rows are restricted
to complete cases across all columns because the overall ANOVA requires a
common wide matrix.
}

When \code{ci = TRUE}, confidence intervals are obtained from the classical
F-based ANOVA formulas corresponding to the selected coefficient. For
\code{scope = "pairwise"}, non-estimable off-diagonal pairs return \code{NA}. For
\code{scope = "overall"}, the coefficient table includes interval columns for all
six standard rows.
}
\examples{
set.seed(123)
n <- 40
subj <- rnorm(n, sd = 1)
dat <- data.frame(
  m1 = subj + rnorm(n, sd = 0.3),
  m2 = 0.2 + subj + rnorm(n, sd = 0.4),
  m3 = -0.1 + subj + rnorm(n, sd = 0.5)
)

fit_icc <- icc(dat,
  model = "twoway_random",
  type = "agreement",
  unit = "single",
  scope = "pairwise"
)
print(fit_icc)
summary(fit_icc)
estimate(fit_icc)
tidy(fit_icc)

fit_icc_overall <- icc(dat, scope = "overall", ci = TRUE)
print(fit_icc_overall)
summary(fit_icc_overall)
confint(fit_icc_overall)

}
\references{
Shrout PE, Fleiss JL (1979). Intraclass correlations: uses in assessing
rater reliability. Psychological Bulletin, 86(2), 420-428.

McGraw KO, Wong SP (1996). Forming inferences about some intraclass
correlation coefficients. Psychological Methods, 1(1), 30-46.
}
\seealso{
\code{\link[=ccc]{ccc()}}, \code{\link[=ccc_rm_reml]{ccc_rm_reml()}}, \code{\link[=ba]{ba()}}, \code{\link[=ba_rm]{ba_rm()}}, \code{\link[=rmcorr]{rmcorr()}}
}
