% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-hierarchical-audit.R
\name{facet_small_sample_review}
\alias{facet_small_sample_review}
\title{Review per-facet-level sample adequacy}
\usage{
facet_small_sample_review(
  fit,
  diagnostics = NULL,
  thresholds = c(sparse = 10, marginal = 30, standard = 50)
)
}
\arguments{
\item{fit}{An \code{mfrm_fit} from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} output. When supplied,
per-level \code{Infit}, \code{Outfit}, and \code{ModelSE} are added to the report.}

\item{thresholds}{Named numeric vector of count bands. Defaults are
\code{c(sparse = 10, marginal = 30, standard = 50)}. These are adapted
from Linacre (1994): the 30-level band preserves Linacre's
approximately \verb{+-1.0 logit at 95\% CI} line, while the \code{sparse < 10}
floor and the \code{standard = 50} watermark are mfrmr-specific screening
choices below Linacre's 30-examinee minimum and between Linacre's
30 and 100 thresholds.}
}
\value{
A list of class \code{mfrm_facet_sample_review} with:
\itemize{
\item \code{table}: one row per \verb{(Facet, Level)} with \code{N}, \code{Estimate}, \code{SE},
\code{Infit}, \code{Outfit}, and \code{SampleCategory}.
\item \code{summary}: counts of levels in each sample-size category, by facet.
\item \code{facet_summary}: smallest observed level count per facet.
\item \code{thresholds}: the applied count bands.
}
}
\description{
Reports per-level observation counts, SE, and fit statistics for every
level of every facet in a fitted MFRM model, and classifies each level
as \code{"sparse"}, \code{"marginal"}, \code{"standard"}, or \code{"strong"} against the
Linacre sample-size bands.
}
\details{
In mfrmr every facet is a fixed effect (see \code{?fit_mfrm}, "Fixed
effects assumption"), so a level with very few ratings contributes an
estimate with wide SE but no shrinkage toward the facet mean. This
helper surfaces those levels up front so users can decide whether to
drop them, pool them, or move to a hierarchical model outside mfrmr.
}
\section{Interpreting output}{

\itemize{
\item \code{"sparse"} (n < 10): level-level estimate is unstable; SE will be
wide; consider combining with adjacent levels or treating as
exploratory only.
\item \code{"marginal"} (10 <= n < 30): below Linacre (1994) 95\% CI
+-1.0 logit threshold; usable as screening only.
\item \code{"standard"} (30 <= n < 50): meets baseline stability; reasonable
for publication if fit statistics are acceptable.
\item \code{"strong"} (n >= 50): well-targeted; facet estimate is robust.
}

Because mfrmr has no shrinkage by default, sparse and marginal levels
do not "borrow strength" from other levels. Jones and Wind (2018)
report that rater estimates are particularly sensitive to thin
linking; the \code{Facet = "Person"} row is usually less of a concern
because the person prior integrates out the uncertainty.
}

\section{Typical workflow}{

\enumerate{
\item Fit with \code{fit_mfrm()}; optionally also produce \code{diagnostics}
with \code{diagnose_mfrm()} if you want per-level Infit/Outfit.
\item Call \code{facet_small_sample_review(fit, diagnostics)}.
\item Read the \code{facet_summary} first: it highlights the worst level
per facet. The \code{summary} table gives counts in each band.
\item If any facet is flagged as sparse or marginal, discuss it in the
Methods section; \code{\link[=build_apa_outputs]{build_apa_outputs()}} already adds a sentence
about the band when \code{fit$summary$FacetSampleSizeFlag} is set.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
review <- facet_small_sample_review(fit)
summary(review)

# Custom thresholds (e.g. a stricter protocol).
strict <- facet_small_sample_review(
  fit,
  thresholds = c(sparse = 15, marginal = 40, standard = 100)
)
strict$facet_summary
}
\references{
Linacre, J. M. (2026). \emph{A User's Guide to FACETS, Version 4.5.0}.
Winsteps.com. \url{https://www.winsteps.com/facets.htm}

Linacre, J. M. (1994). Sample size and item calibration stability.
\emph{Rasch Measurement Transactions, 7}(4), 328.
\url{https://www.rasch.org/rmt/rmt74m.htm}

Jones, E., & Wind, S. A. (2018). Using repeated ratings to improve
measurement precision in incomplete rating designs. \emph{Journal of
Applied Measurement, 19}(2), 148-161.
}
\seealso{
\code{\link[=detect_facet_nesting]{detect_facet_nesting()}}, \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[=reporting_checklist]{reporting_checklist()}}.
}
