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

toy <- load_mfrmr_data("example_core")
hs <- analyze_hierarchical_structure(toy,
                                     facets = c("Rater", "Criterion"),
                                     compute_icc = FALSE,
                                     igraph_layout = FALSE)
summary(hs)
#> mfrm_hierarchical_structure
#> 
#> Summary:
#>  NFacets NestedPairs CrossedPairs ICCAvailable ConnectivityComponents
#>        2           0            3        FALSE                     NA
#> 
#> Nesting review:
#>  FacetA    FacetB NestingIndex_AinB NestingIndex_BinA Direction
#>  Person     Rater                 0                 0   crossed
#>  Person Criterion                 0                 0   crossed
#>   Rater Criterion                 0                 0   crossed

# 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")
}
#> mfrm_hierarchical_structure
#> 
#> Summary:
#>  NFacets NestedPairs CrossedPairs ICCAvailable ConnectivityComponents
#>        2           0            3         TRUE                      1
#> 
#> Nesting review:
#>  FacetA    FacetB NestingIndex_AinB NestingIndex_BinA Direction
#>  Person     Rater                 0                 0   crossed
#>  Person Criterion                 0                 0   crossed
#>   Rater Criterion                 0                 0   crossed
#> 
#> ICC (lme4 variance-components):
#> mfrm_facet_icc
#>   ICC rows: 768 input, 768 used, 0 excluded.
#>      Facet   Variance    ICC Interpretation InterpretationScale ICC_CI_Lower
#>     Person 0.34626071 0.3511           Poor  Koo-Li reliability           NA
#>      Rater 0.02667343 0.0270  Trivial share      Variance share           NA
#>  Criterion 0.02188365 0.0222  Trivial share      Variance share           NA
#>   Residual 0.59144865 0.5997    Large share      Variance share           NA
#>  ICC_CI_Upper ICC_CI_Level ICC_CI_Method ICC_CI_Status InputRows UsedRows
#>            NA         0.95          none Not requested       768      768
#>            NA         0.95          none Not requested       768      768
#>            NA         0.95          none Not requested       768      768
#>            NA         0.95          none Not requested       768      768
#>  ExcludedRows
#>             0
#>             0
#>             0
#>             0
#> 
#> Design-effect approximations:
#> mfrm_facet_design_effect (per-facet approximation)
#>   EffectiveN is a descriptive row count, not full-design precision.
#>   ICC rows: 768 input, 768 used, 0 excluded.
#>      Facet AvgClusterSize    ICC DesignEffect EffectiveN InputRows UsedRows
#>      Rater            192 0.0270        6.157      124.7       768      768
#>  Criterion            192 0.0222        5.240      146.6       768      768
#>  ExcludedRows
#>             0
#>             0
#> 
#> Bipartite connectivity (via igraph):
#>   Components: 1 
#>   Largest component: 56 
#>   Isolates: 0