icc: Intraclass Correlation for Wide Data

In matrixCorr: Collection of Correlation and Association Estimators

Intraclass Correlation for Wide Data

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.

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"),
  ci = FALSE,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE,
  ...
)

## S3 method for class 'icc'
print(
  x,
  digits = 4,
  ci_digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'icc'
summary(
  object,
  digits = 4,
  ci_digits = 2,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'summary.icc'
print(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'icc_overall'
print(
  x,
  digits = 4,
  ci_digits = 4,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'icc_overall'
summary(
  object,
  digits = 4,
  ci_digits = 2,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'summary.icc_overall'
print(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

Arguments

data	A numeric matrix or data frame with at least two numeric columns.
model	Character scalar selecting the classical ICC model. "oneway" uses the one-way random-effects formulation, "twoway_random" uses the two-way random-effects formulation, and "twoway_mixed" uses the two-way mixed-effects formulation.
type	Character scalar selecting the reliability target. "consistency" does not penalize systematic column mean differences in the same way as absolute agreement, whereas "agreement" targets absolute agreement and therefore incorporates those differences.
unit	Character scalar selecting whether the coefficient refers to a single measurement ("single") or to the mean of multiple measurements ("average"). For scope = "pairwise", the average-measure coefficient always uses k = 2. For scope = "overall", it uses the full number of analysed columns.
scope	Character scalar selecting the analysis target. "pairwise" returns the symmetric matrix of two-column ICCs. "overall" returns the six-row overall ANOVA table for the full set of columns. Choose "pairwise" when the question is about specific column pairs; choose "overall" when the question is about the full set of columns analysed jointly.
na_method	Character scalar controlling missing-data handling. "error" rejects missing, NaN, and infinite values before estimation. "pairwise" uses pair-specific complete cases for scope = "pairwise" and complete rows across all analysed columns for scope = "overall".
ci	Logical; if TRUE, return confidence intervals.
conf_level	Confidence level for the interval output. Ignored when ci = FALSE.
n_threads	Integer number of OpenMP threads.
verbose	Logical; if TRUE, report how many threads are requested.
...	Passed to the underlying print helper.
x	An intraclass-correlation object returned by icc(), or a summary object returned by summary() for that fit.
digits	Integer; number of digits to print.
ci_digits	Integer; number of digits for CI bounds.
n	Optional row threshold for compact preview output.
topn	Optional number of leading/trailing rows to show when truncated.
max_vars	Optional maximum number of visible columns; NULL derives this from console width.
width	Optional display width; defaults to getOption("width").
show_ci	One of "yes" or "no".
object	An intraclass-correlation object returned by icc().

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.

• 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.

• scope = "overall" answers: "how reliable is the full set of columns when analysed jointly?" The output is the standard six-form overall ANOVA table (ICC1, ICC2, ICC3, ICC1k, ICC2k, 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.

• model controls the rater structure:

  • "oneway" uses the one-way random-effects formulation.

  • "twoway_random" uses the two-way random-effects formulation.

  • "twoway_mixed" uses the two-way mixed-effects formulation.

• type controls whether systematic column mean differences are penalized:

  • "consistency" targets consistency across columns.

  • "agreement" targets absolute agreement across columns.

• unit controls whether reliability refers to one measurement or to the average of multiple measurements:

  • "single" returns the single-measure coefficient.

  • "average" returns the average-measure coefficient.

The supported mappings are:

• ⁠model = "oneway", type = "consistency", unit = "single"⁠ gives ICC1.

• ⁠model = "oneway", type = "consistency", unit = "average"⁠ gives ICC1k.

• ⁠model = "twoway_random", type = "agreement", unit = "single"⁠ gives ICC2.

• ⁠model = "twoway_random", type = "agreement", unit = "average"⁠ gives ICC2k.

• ⁠model = "twoway_random", type = "consistency", unit = "single"⁠ gives ICC3.

• ⁠model = "twoway_random", type = "consistency", unit = "average"⁠ gives ICC3k.

• ⁠model = "twoway_mixed", type = "agreement", unit = "single"⁠ gives the mixed-effects absolute-agreement analogue with the same classical point formula as ICC2.

• ⁠model = "twoway_mixed", type = "agreement", unit = "average"⁠ gives the corresponding average-measure analogue.

• ⁠model = "twoway_mixed", type = "consistency", unit = "single"⁠ gives ICC3.

• ⁠model = "twoway_mixed", type = "consistency", unit = "average"⁠ gives ICC3k.

The combination ⁠model = "oneway", type = "agreement"⁠ is not defined here and returns an error.

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

For 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 k = ncol(data) after any row filtering required by na_method.

Missing-data handling depends on scope:

• with na_method = "error", missing values are rejected before estimation;

• with na_method = "pairwise" and scope = "pairwise", each pair uses its own complete-case overlap;

• with na_method = "pairwise" and scope = "overall", rows are restricted to complete cases across all columns because the overall ANOVA requires a common wide matrix.

When ci = TRUE, confidence intervals are obtained from the classical F-based ANOVA formulas corresponding to the selected coefficient. For scope = "pairwise", non-estimable off-diagonal pairs return NA. For scope = "overall", the coefficient table includes interval columns for all six standard rows.

Value

For scope = "pairwise", if ci = FALSE, a symmetric matrix of class icc. If ci = TRUE, a list with elements est, lwr.ci, and upr.ci and class c("icc", "icc_ci").

For scope = "overall", a list of class 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 ci = TRUE.

All outputs carry attributes describing the selected model, type, unit, and method.

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.

See Also

ccc(), ccc_rm_reml(), ba(), ba_rm(), rmcorr()

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)

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

matrixCorr documentation built on April 18, 2026, 5:06 p.m.