% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-hierarchical-audit.R
\name{detect_facet_nesting}
\alias{detect_facet_nesting}
\title{Detect nesting structure between facets}
\usage{
detect_facet_nesting(data, facets, person = NULL, weight_col = NULL)
}
\arguments{
\item{data}{Data frame in long format (one row per rating).}

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

\item{person}{Optional name of the person column (adds Person to the
nesting matrix if supplied).}

\item{weight_col}{Optional name of a weight column; if supplied, rows
are replicated proportionally when counting element co-occurrences.}
}
\value{
A list of class \code{mfrm_facet_nesting} with:
\itemize{
\item \code{pairwise_table}: one row per ordered facet pair with
\code{NestingIndex_AinB}, \code{NestingIndex_BinA}, classification strings,
and \code{Direction}.
\item \code{summary}: a one-line summary table with facet counts and whether
any non-crossed structure was detected.
\item \code{facets}: the facet vector that was reviewed.
}
}
\description{
Classifies every ordered pair of facets (optionally including \code{Person})
as crossed, partially nested, near-perfectly nested, or fully nested,
based on a conditional-entropy index:
\deqn{\text{nesting\_index}(A \to B) = 1 - H(B \mid A) / H(B).}
An index near 1 means that knowing the level of \code{A} essentially
determines the level of \code{B} (A is nested in B).
}
\details{
This is a pure descriptive review of the observed design. It does not
affect estimation; fit_mfrm() continues to treat all facets as fixed
effects.
}
\section{Classification bands}{

\itemize{
\item \code{"Fully nested"}: nesting index >= 0.99.
\item \code{"Near-perfectly nested"}: 0.95 <= index < 0.99.
\item \code{"Partially nested"}: 0.50 <= index < 0.95.
\item \code{"Crossed"}: index < 0.50.
}

The direction column records which facet is nested in which, or
\code{"crossed"} when neither direction is above 0.95.
}

\section{Interpreting output}{

A \code{Direction} value of \code{"Rater nested in Region"} means that every
rater appears in exactly one region (or very close to it). For
additive fixed-effects MFRM, this is a concern: the severity of a
rater is confounded with region-level variance that the model cannot
partition. Consider reporting the nesting direction explicitly and,
when relevant, refitting without the nested facet or moving to a
hierarchical estimation tool (e.g. \code{lme4::lmer}, \code{brms}, \code{TAM}) to
separate the variance components.

\code{Direction = "crossed"} is the most common reading when both nesting
indices are below 0.5; the two facets largely co-occur at multiple
combinations, which is the setting Linacre (1989) assumed.
}

\section{Typical workflow}{

\enumerate{
\item Call \code{detect_facet_nesting(data, facets)} before fitting.
\item If any pair is flagged as nested or partially nested, review the
numeric index and the \code{LevelsA}/\code{LevelsB} counts.
\item For downstream reporting, use \code{\link[=analyze_hierarchical_structure]{analyze_hierarchical_structure()}}
to bundle this output with ICC and design-effect summaries, which
\code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}} then records for reproducibility.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
nesting <- detect_facet_nesting(toy, c("Rater", "Criterion"))
summary(nesting)

# Synthetic example: raters fully nested within regions.
d <- data.frame(
  Person = rep(paste0("P", formatC(1:20, width = 2, flag = "0")),
               each = 6),
  Rater  = rep(paste0("R", 1:6), 20),
  Region = rep(rep(c("A", "A", "B", "B", "C", "C"), 20)),
  Score  = sample(0:4, 120, replace = TRUE),
  stringsAsFactors = FALSE
)
nest <- detect_facet_nesting(d, c("Rater", "Region"))
nest$pairwise_table[, c("FacetA", "FacetB",
                        "NestingIndex_AinB", "Direction")]
}
\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. (1989). \emph{Many-facet Rasch measurement}. MESA Press.
}
\seealso{
\code{\link[=facet_small_sample_review]{facet_small_sample_review()}},
\code{\link[=analyze_hierarchical_structure]{analyze_hierarchical_structure()}}, \code{\link[=compute_facet_icc]{compute_facet_icc()}},
\code{\link[=compute_facet_design_effect]{compute_facet_design_effect()}}, \code{\link[=fit_mfrm]{fit_mfrm()}} (see "Fixed effects
assumption" in its details).
}
