Analyze the hierarchical structure of a rating design

One-stop review that combines the nesting, cross-tabulation, ICC, and design-effect reports into a single object. Its summary feeds into reporting_checklist() after checking the reviewed data against the fit.

Usage

analyze_hierarchical_structure(
  data,
  facets = NULL,
  person = "Person",
  score = "Score",
  compute_icc = TRUE,
  ci_method = c("none", "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,
  missing = c("error", "omit")
)

Arguments

data: Data frame in long format, or an mfrm_fit (its prep$data is used).
facets: Character vector of facet column names. When data is an mfrm_fit, defaults to fit$prep$facet_names.
person: Person column name. Defaults to "Person".
score: Score column name. Defaults to "Score".
compute_icc: Logical; if TRUE and lme4 is available, adds ICC and design-effect tables.
ci_method: ICC confidence-interval method passed through to compute_facet_icc(). One of "none" (default, point estimate only) or "boot". The former "profile" method is refused because it did not calculate an ICC profile-likelihood interval. Deprecated alias: icc_ci_method (kept for backward compatibility, emits a lifecycle warning).
ci_level: Confidence level when ci_method != "none"; default 0.95. Deprecated alias: icc_ci_level.
ci_boot_reps: Number of bootstrap replicates when ci_method = "boot". Default 1000. Deprecated alias: icc_ci_boot_reps.
ci_boot_seed: Optional RNG seed for reproducible bootstrap CIs. Deprecated alias: icc_ci_boot_seed.
igraph_layout: Logical; if TRUE and igraph is available, adds a connectivity component summary using a bipartite graph over person x facet levels.
icc_ci_method, icc_ci_level, icc_ci_boot_reps, icc_ci_boot_seed: Deprecated compatibility spellings of the ci_* arguments above. Supplying a non-NULL value routes through lifecycle::deprecate_warn() and overrides the canonical ci_* argument.
missing: Missing-value policy for the ICC and design-effect tables, passed to compute_facet_icc(). Invalid input or model errors stop the requested ICC analysis. Nesting, cross-tabulation, and connectivity tables describe the supplied design, including rows excluded from the ICC model. When data is a fit, ICC row counts start from its stored fitted rows; they cannot recover exclusions made before fitting the MFRM.

Value

A list of class mfrm_hierarchical_structure with:

nesting: output of detect_facet_nesting().
crosstabs: list of pairwise observation-count data.frames (long format, suitable for heatmap plotting).
icc: output of compute_facet_icc() when requested.
design_effect: output of compute_facet_design_effect() when requested.
connectivity: named list with bipartite-graph component summary when igraph is available.
summary: one-row summary used by downstream reporting helpers.
facets: character vector of facet names that were reviewed (echoed for downstream reporting helpers that need to label rows by review scope).
data_identity: reviewed column roles, input row count and a compact fingerprint for reuse checks. The optional person column also contributes to nesting pair counts; summary$NFacets counts the requested facets.

plot(x, type = "icc") draws variance shares and any available intervals without an embedded title or footnote. Save its returned object as p and use plot_data(p, "notes") to read the interval method or the reason bounds are unavailable. These notes survive saveRDS()/readRDS(); they do not change the underlying ICC estimates.

Interpreting output

nesting: a detect_facet_nesting() object with every facet pair classified as Crossed / Partially / Near-perfectly / Fully nested.
crosstabs: list of (LevelA, LevelB, N) long-format tables, one per facet pair. Plot via plot(x, type = "crosstab", pair = "FacetA__FacetB").
icc: per-facet variance shares. See compute_facet_icc() for the two-scale interpretation.
design_effect: per-facet design-effect approximations and descriptive equivalent row counts; not precision estimates for the full design.
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.

Typical workflow

Optional: fit the MFRM with fit_mfrm().
Call analyze_hierarchical_structure(fit) (or on the raw data).
Read summary(x) for the condensed view.
Pass it as hierarchical_structure to reporting_checklist() and save the review with saveRDS() when its full tables are needed later. build_mfrm_manifest() records a separate fit-level rating-count review; it does not accept or archive this structural-review object.

Saved-result reuse

A reporting checklist checks the reviewed column roles and retained rating rows, including scores when an ICC table was computed. It accepts a subset of fitted facets and reports that scope explicitly. Reviews from raw data also work when the selected columns and rows match, using either canonical Person/Score names or the fit's original source-column names. Row order, unused factor levels, unused columns and MFRM estimates do not affect this match. Nesting and row counts are unweighted; when ICC is absent, the match does not depend on scores. These rules do not establish that a partial review covers all facets or that the design supports valid inference. A review of additional rows, other strata or columns absent from the fit remains usable on its own, but cannot mark this fit's checklist item as available. Recreate older reviews without data_identity from the saved fit or matching retained rows and original options; no MFRM refit is needed. See mfrmr_compatibility_layer.

References

McEwen, M. R. (2018). The effects of incomplete rating designs on results from many-facets-Rasch model analyses (Doctoral thesis, Brigham Young University). https://scholarsarchive.byu.edu/etd/6689/

Linacre, J. M. (2026). A User's Guide to FACETS, Version 4.5.0. Winsteps.com.

Kish, L. (1965). Survey Sampling. New York: Wiley.

Koo, T. K., & Li, M. Y. (2016). A guideline of selecting and reporting intraclass correlation coefficients for reliability research. Journal of Chiropractic Medicine, 15(2), 155-163.

Examples

# Supplementary workflow: run explicitly to keep routine checks brief.
# example("analyze_hierarchical_structure", run.dontrun = TRUE)
if (FALSE) { # \dontrun{
toy <- load_mfrmr_data("example_core")
hs <- analyze_hierarchical_structure(toy,
                                     facets = c("Rater", "Criterion"),
                                     compute_icc = FALSE,
                                     igraph_layout = FALSE)
summary(hs)

# 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")
}
} # }