% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-hierarchical-audit.R
\name{compute_facet_icc}
\alias{compute_facet_icc}
\title{Compute intra-class correlations for each facet}
\usage{
compute_facet_icc(
  data,
  facets,
  score,
  person = NULL,
  reml = TRUE,
  ci_method = c("none", "profile", "boot"),
  ci_level = 0.95,
  ci_boot_reps = 1000L,
  ci_boot_seed = NULL,
  ci_boot_parallel = c("no", "multicore", "snow"),
  ci_boot_ncpus = 1L
)
}
\arguments{
\item{data}{Data frame in long format.}

\item{facets}{Character vector of facet column names.}

\item{score}{Name of the score column.}

\item{person}{Optional person column. If supplied it is added as a
separate random intercept so Person-level variance is partitioned
out.}

\item{reml}{Logical; whether to fit with REML. Default \code{TRUE}.}

\item{ci_method}{Confidence-interval method for the ICC column.
One of \code{"none"} (default, point estimate only), \code{"profile"}
(a \strong{first-order approximation}: marginal likelihood-profile
bounds for each variance-component SD via
\code{\link[lme4:confint.merMod]{lme4::confint.merMod()}} with \code{method = "profile"}, squared to
variances, then plugged into the ICC ratio while holding the
other components at their point estimate; fast and deterministic,
the default recommendation for reporting), or \code{"boot"}
(parametric bootstrap via \code{\link[lme4:bootMer]{lme4::bootMer()}}; slower but robust
to non-normal ICC sampling distributions because each bootstrap
replicate resamples the full variance decomposition jointly).}

\item{ci_level}{Confidence level when \code{ci_method != "none"}; default
\code{0.95}. Koo & Li (2016) recommend banding the CI rather than the
point estimate when classifying reliability as Poor / Moderate /
Good / Excellent.}

\item{ci_boot_reps}{Number of bootstrap replicates used when
\code{ci_method = "boot"}. Default \code{1000}.}

\item{ci_boot_seed}{Optional integer seed for the bootstrap path
(\code{NULL} leaves the RNG state untouched).}

\item{ci_boot_parallel}{Parallelisation strategy for the
parametric-bootstrap CI path, passed through to
\code{\link[lme4:bootMer]{lme4::bootMer()}}: \code{"no"} (default), \code{"multicore"} (POSIX
\code{mclapply}), or \code{"snow"} (PSOCK cluster). \code{"multicore"} does
nothing on Windows and falls back to serial; in that case use
\code{"snow"} with \code{\link[parallel:makeCluster]{parallel::makeCluster()}} in scope.}

\item{ci_boot_ncpus}{Number of CPUs to use for the parallel
bootstrap path (ignored when \code{ci_boot_parallel = "no"}). The
per-replicate progress bar is suppressed under parallel
execution because worker processes cannot push updates to the
parent's cli console.}
}
\value{
A data.frame of class \code{mfrm_facet_icc} with one row per
variance component (including a \code{"Residual"} row) and columns:
\itemize{
\item \code{Facet}: the grouping factor name (or \code{"Residual"}).
\item \code{Variance}: REML variance estimate.
\item \code{ICC}: variance share (\code{Variance / sum(Variance)}), in \verb{[0, 1]}.
\item \code{Interpretation}: band label according to the facet's scale.
\item \code{InterpretationScale}: \code{"Koo-Li reliability"} for the person
facet, \code{"Variance share"} for others.
\item \code{ICC_CI_Lower} / \code{ICC_CI_Upper} / \code{ICC_CI_Level} / \code{ICC_CI_Method}:
CI bounds, level, and method (populated when \code{ci_method != "none"};
\code{NA_real_} otherwise).
\item \code{ICC_CI_NReps}: bootstrap replicate count when
\code{ci_method = "boot"} (absent otherwise).
}
}
\description{
Fits a random-effects variance-components model
\code{Score ~ 1 + (1 | Person) + (1 | Facet1) + (1 | Facet2) + ...}
using \code{lme4::lmer} (in \code{Suggests}) and returns the proportion of
observed score variance attributable to each facet. This is a
descriptive summary complementary to the Rasch-metric rater
separation/reliability reported elsewhere.
}
\section{Interpreting output}{

The \code{Interpretation} column uses \strong{two scales} so the same numeric
ICC reads correctly for each facet role:
\itemize{
\item For the \code{person} facet, higher ICC = better. Koo & Li (2016, p. 161)
bands are applied: \verb{< 0.5} Poor, \verb{[0.5, 0.75]} Moderate,
\verb{(0.75, 0.9]} Good, \verb{> 0.9} Excellent. The strict \code{>} boundary at
0.9 follows Koo & Li's wording "values greater than 0.90 indicate
excellent reliability" (so an ICC of exactly 0.9 reads as Good).
\item For non-person facets (Rater, Criterion, Task, Region, ...) the
same numeric value is a \strong{variance share}: how much of the total
observed score variance sits at that facet. The bands used here
are different (\verb{Trivial share} < 0.05, \verb{Small share} < 0.15,
\verb{Moderate share} < 0.30, \verb{Large share} >= 0.30), and a large
rater share is generally \emph{bad} news (raters disagree about
averages), not good news.
}

The \code{InterpretationScale} column explicitly records which scale
applies to each row, so downstream reporting does not confuse the
two. FACETS (Linacre, 2026) reports rater separation/reliability on
the Rasch metric instead of an ICC; mfrmr surfaces both, with the
Rasch-metric version in \code{diagnostics$reliability} and this
variance-share view here.

Note: Koo & Li (2016) recommend applying the reliability bands to
the \strong{95\% confidence interval} of the ICC rather than to the point
estimate alone. Set \code{ci_method = "profile"} (default \code{"none"}) to
obtain likelihood-profile CI bounds alongside the point estimate,
or \code{ci_method = "boot"} for a parametric bootstrap with
\code{ci_boot_reps} replicates. The returned data frame gains
\code{ICC_CI_Lower} / \code{ICC_CI_Upper} columns so downstream reporting can
apply the band to the CI rather than the point estimate. The
\code{Interpretation} column still uses the point estimate so
callers who want CI-aware banding can implement it externally from
the supplied bounds.
}

\section{Typical workflow}{

\enumerate{
\item Fit the MFRM model with \code{fit_mfrm()} for the Rasch-metric
separation/reliability.
\item Call \code{compute_facet_icc(data, facets, score, person)} to get the
complementary variance-share summary.
\item Feed into \code{\link[=compute_facet_design_effect]{compute_facet_design_effect()}} to convert ICCs and
average cluster sizes into Kish (1965) design effects.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
if (requireNamespace("lme4", quietly = TRUE)) {
  icc <- compute_facet_icc(toy, facets = c("Rater", "Criterion"),
                           score = "Score", person = "Person")
  print(icc)
  # Look for:
  # - Person ICC reads as Koo & Li (2016) reliability: < 0.5 poor,
  #   0.5-0.75 moderate, 0.75-0.9 good, > 0.9 excellent.
  # - Rater / Criterion ICC reads as variance share, NOT reliability;
  #   here SMALL values are desirable (raters / items agree), and
  #   shares > 0.10 hint at meaningful systematic facet differences.
  # - `Interpretation` summarises the variance-share band the helper
  #   has assigned to each row.
}
}
}
\references{
Koo, T. K., & Li, M. Y. (2016). A guideline of selecting and
reporting intraclass correlation coefficients for reliability
research. \emph{Journal of Chiropractic Medicine, 15}(2), 155-163.

Bates, D., Maechler, M., Bolker, B., & Walker, S. (2015). Fitting
linear mixed-effects models using lme4. \emph{Journal of Statistical
Software, 67}(1), 1-48.
}
\seealso{
\code{\link[=compute_facet_design_effect]{compute_facet_design_effect()}},
\code{\link[=analyze_hierarchical_structure]{analyze_hierarchical_structure()}}, \code{\link[=detect_facet_nesting]{detect_facet_nesting()}},
\code{\link[=facet_small_sample_review]{facet_small_sample_review()}}.
}
\concept{ICC}
\concept{confidence intervals}
\concept{hierarchical structure}
