% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{category_structure_report}
\alias{category_structure_report}
\title{Build a category structure report (preferred alias)}
\usage{
category_structure_report(
  fit,
  diagnostics = NULL,
  theta_range = c(-6, 6),
  theta_points = 241,
  drop_unused = FALSE,
  include_fixed = FALSE,
  fixed_max_rows = 200
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{theta_range}{Theta/logit range used to derive transition points.}

\item{theta_points}{Number of grid points used for transition-point search.}

\item{drop_unused}{If \code{TRUE}, remove zero-count categories from outputs.}

\item{include_fixed}{If \code{TRUE}, include a legacy-compatible fixed-width text
block.}

\item{fixed_max_rows}{Maximum rows per fixed-width section.}
}
\value{
A named list with category-structure components. Class:
\code{mfrm_category_structure}.
}
\description{
Build a category structure report (preferred alias)
}
\details{
Preferred high-level API for category-structure diagnostics.
This wraps the legacy-compatible bar/transition export and returns a stable
bundle interface for reporting and plotting.
}
\section{Interpreting output}{

Key components include:
\itemize{
\item category usage/fit table (count, expected, infit/outfit, ZSTD)
\item threshold ordering and adjacent threshold gaps
\item category transition-point table on the requested theta grid
}

Practical read order:
\enumerate{
\item \code{summary(out)} for compact warnings and threshold ordering.
\item \code{out$category_table} for sparse/misfitting categories.
\item \code{out$median_thresholds} for adjacent-threshold caveats when zero-count
categories are retained.
\item \code{plot(out)} for quick visual check.
}
}

\section{Typical workflow}{

\enumerate{
\item \code{\link[=fit_mfrm]{fit_mfrm()}} -> model.
\item \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} -> residual/fit diagnostics (optional argument here).
\item \code{category_structure_report()} -> category health snapshot.
\item \code{summary()} and \code{plot()} for draft-oriented review of category structure.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
out <- category_structure_report(fit)
summary(out)
head(out$category_table[, c("Category", "Count", "Infit", "Outfit")])
p_cs <- plot(out, draw = FALSE)
p_cs$data$plot
}
\seealso{
\code{\link[=rating_scale_table]{rating_scale_table()}}, \code{\link[=category_curves_report]{category_curves_report()}}, \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}},
\link{mfrmr_reports_and_tables}, \link{mfrmr_visual_diagnostics}
}
