% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-hierarchical-audit.R
\name{analyze_hierarchical_structure}
\alias{analyze_hierarchical_structure}
\title{Analyze the hierarchical structure of a rating design}
\usage{
analyze_hierarchical_structure(
  data,
  facets = NULL,
  person = "Person",
  score = "Score",
  compute_icc = TRUE,
  ci_method = c("none", "profile", "boot"),
  ci_level = 0.95,
  ci_boot_reps = 1000L,
  ci_boot_seed = NULL,
  igraph_layout = TRUE,
  icc_ci_method = NULL,
  icc_ci_level = NULL,
  icc_ci_boot_reps = NULL,
  icc_ci_boot_seed = NULL
)
}
\arguments{
\item{data}{Data frame in long format, or an \code{mfrm_fit} (its
\code{prep$data} is used).}

\item{facets}{Character vector of facet column names. When \code{data} is
an \code{mfrm_fit}, defaults to \code{fit$prep$facet_names}.}

\item{person}{Person column name. Defaults to \code{"Person"}.}

\item{score}{Score column name. Defaults to \code{"Score"}.}

\item{compute_icc}{Logical; if \code{TRUE} and \code{lme4} is available, adds
ICC and design-effect tables.}

\item{ci_method}{ICC confidence-interval method passed through to
\code{\link[=compute_facet_icc]{compute_facet_icc()}}. One of \code{"none"} (default, point estimate
only), \code{"profile"}, or \code{"boot"}. Deprecated alias:
\code{icc_ci_method} (kept for backward compatibility, emits a
lifecycle warning).}

\item{ci_level}{Confidence level when \code{ci_method != "none"};
default \code{0.95}. Deprecated alias: \code{icc_ci_level}.}

\item{ci_boot_reps}{Number of bootstrap replicates when
\code{ci_method = "boot"}. Default \code{1000}. Deprecated alias:
\code{icc_ci_boot_reps}.}

\item{ci_boot_seed}{Optional RNG seed for reproducible bootstrap
CIs. Deprecated alias: \code{icc_ci_boot_seed}.}

\item{igraph_layout}{Logical; if \code{TRUE} and \code{igraph} is available,
adds a connectivity component summary using a bipartite graph over
person x facet levels.}

\item{icc_ci_method, icc_ci_level, icc_ci_boot_reps, icc_ci_boot_seed}{Deprecated spellings of the \verb{ci_*} arguments above, retained for
one release. Supplying a non-\code{NULL} value routes through
\code{\link[lifecycle:deprecate_warn]{lifecycle::deprecate_warn()}} and overrides the canonical
\verb{ci_*} argument.}
}
\value{
A list of class \code{mfrm_hierarchical_structure} with:
\itemize{
\item \code{nesting}: output of \code{\link[=detect_facet_nesting]{detect_facet_nesting()}}.
\item \code{crosstabs}: list of pairwise observation-count data.frames (long
format, suitable for heatmap plotting).
\item \code{icc}: output of \code{\link[=compute_facet_icc]{compute_facet_icc()}} when requested.
\item \code{design_effect}: output of \code{\link[=compute_facet_design_effect]{compute_facet_design_effect()}} when
requested.
\item \code{connectivity}: named list with bipartite-graph component summary
when \code{igraph} is available.
\item \code{summary}: one-row summary used by downstream reporting helpers.
\item \code{facets}: character vector of facet names that were reviewed
(echoed for downstream reporting helpers that need to label rows
by review scope).
}
}
\description{
One-stop review that combines the nesting, cross-tabulation, ICC, and
design-effect reports into a single object. Designed to be reused by
the publication-workflow surface: its summary feeds into
\code{reporting_checklist()}, and its tables are picked up by
\code{build_mfrm_manifest()} for reproducibility bundles.
}
\section{Interpreting output}{

\itemize{
\item \code{nesting}: a
\code{\link[=detect_facet_nesting]{detect_facet_nesting()}} object with every facet pair classified
as Crossed / Partially / Near-perfectly / Fully nested.
\item \code{crosstabs}: list of \verb{(LevelA, LevelB, N)} long-format tables,
one per facet pair. Plot via \code{plot(x, type = "crosstab", pair = "FacetA__FacetB")}.
\item \code{icc}: per-facet variance shares. See
\code{\link[=compute_facet_icc]{compute_facet_icc()}} for the two-scale interpretation.
\item \code{design_effect}: Kish (1965) \code{Deff} and \code{EffectiveN}.
\item \code{connectivity}: number of bipartite components linking
Person x facet levels. A single component is required for a
common measurement scale; multiple components indicate a
disconnected design.
}
}

\section{Typical workflow}{

\enumerate{
\item Optional: fit the MFRM with \code{fit_mfrm()}.
\item Call \code{analyze_hierarchical_structure(fit)} (or on the raw data).
\item Read \code{summary(x)} for the condensed view.
\item Feed the object to \code{\link[=reporting_checklist]{reporting_checklist()}} and
\code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}} to record the review in publication
bundles. \code{build_apa_outputs()} uses the fit-level
\code{FacetSampleSizeFlag} to add a Methods sentence automatically.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
hs <- analyze_hierarchical_structure(toy,
                                     facets = c("Rater", "Criterion"),
                                     compute_icc = FALSE,
                                     igraph_layout = FALSE)
summary(hs)

\donttest{
# Full review when lme4 and igraph are available.
if (requireNamespace("lme4", quietly = TRUE) &&
    requireNamespace("igraph", quietly = TRUE)) {
  hs_full <- analyze_hierarchical_structure(toy,
                                            facets = c("Rater", "Criterion"))
  summary(hs_full)
  plot(hs_full, type = "icc")
}
}
}
\references{
McEwen, M. R. (2018). \emph{The effects of incomplete rating designs on
results from many-facets-Rasch model analyses} (Doctoral thesis,
Brigham Young University). \url{https://scholarsarchive.byu.edu/etd/6689/}

Linacre, J. M. (2026). \emph{A User's Guide to FACETS, Version 4.5.0}.
Winsteps.com. \url{https://www.winsteps.com/facets.htm}

Kish, L. (1965). \emph{Survey Sampling}. New York: Wiley.

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.
}
\seealso{
\code{\link[=detect_facet_nesting]{detect_facet_nesting()}}, \code{\link[=facet_small_sample_review]{facet_small_sample_review()}},
\code{\link[=compute_facet_icc]{compute_facet_icc()}}, \code{\link[=compute_facet_design_effect]{compute_facet_design_effect()}},
\code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}, \code{\link[=fit_mfrm]{fit_mfrm()}}.
}
\concept{confidence intervals}
\concept{hierarchical structure}
\concept{reporting workflow}
