% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/help_reports_and_tables.R
\name{mfrmr_reports_and_tables}
\alias{mfrmr_reports_and_tables}
\title{mfrmr Reports and Tables Map}
\description{
Quick guide to choosing the right report or table helper in \code{mfrmr}.
Use this page when you know the reporting question but have not yet decided
which bundle, table, or reporting helper to call.
}
\section{Start with the question}{

\itemize{
\item "How should I document the model setup and run settings?"
Use \code{\link[=specifications_report]{specifications_report()}}.
\item "Was data filtered, dropped, or mapped in unexpected ways?"
Use \code{\link[=data_quality_report]{data_quality_report()}} and \code{\link[=describe_mfrm_data]{describe_mfrm_data()}}.
\item "Did estimation converge cleanly and how formal is the precision layer?"
Use \code{\link[=estimation_iteration_report]{estimation_iteration_report()}} and \code{\link[=precision_review_report]{precision_review_report()}}.
\item "Which facets are measurable, variable, or weakly separated?"
Use \code{\link[=facet_statistics_report]{facet_statistics_report()}}, \code{\link[=measurable_summary_table]{measurable_summary_table()}}, and
\code{\link[=facets_chisq_table]{facets_chisq_table()}}.
\item "Are score categories functioning in a usable sequence?"
Use \code{\link[=rating_scale_table]{rating_scale_table()}}, \code{\link[=category_structure_report]{category_structure_report()}}, and
\code{\link[=category_curves_report]{category_curves_report()}}.
\item "Is the design linked well enough across subsets, forms, or waves?"
Use \code{\link[=subset_connectivity_report]{subset_connectivity_report()}} and \code{\link[=plot_anchor_drift]{plot_anchor_drift()}}.
\item "What should go into the manuscript text and tables?"
For \code{RSM} / \code{PCM}, use \code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=build_apa_outputs]{build_apa_outputs()}},
and \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} or \code{\link[=export_summary_appendix]{export_summary_appendix()}}. For
bounded \code{GPCM}, use the same route only where
\code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}} marks it as \code{supported_with_caveat}: direct
table/plot helpers, summary-table appendix export, caveated
\code{\link[=build_apa_outputs]{build_apa_outputs()}}, and caveated \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} are available
with a \code{gpcm_boundary}; score-side exports and design-forecasting evidence
use their own caveated or blocked \code{GPCM} routes.
\item "Did a simulation recover the known generating parameters well enough?"
Use \code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} for the recovery study,
\code{\link[=assess_mfrm_recovery]{assess_mfrm_recovery()}} for the adequacy checklist, and then
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} or \code{\link[=export_summary_appendix]{export_summary_appendix()}} for the
appendix handoff.
}
}

\section{Recommended report route}{

\enumerate{
\item Start with \code{\link[=specifications_report]{specifications_report()}} and \code{\link[=data_quality_report]{data_quality_report()}} to
document the run and confirm usable data.
\item Continue with \code{\link[=estimation_iteration_report]{estimation_iteration_report()}} and
\code{\link[=precision_review_report]{precision_review_report()}} to judge convergence and inferential strength.
\item Use \code{\link[=facet_statistics_report]{facet_statistics_report()}} and \code{\link[=subset_connectivity_report]{subset_connectivity_report()}} to
describe spread, linkage, and measurability.
\item Add \code{\link[=rating_scale_table]{rating_scale_table()}}, \code{\link[=category_structure_report]{category_structure_report()}}, and
\code{\link[=category_curves_report]{category_curves_report()}} to document scale functioning.
\item For \code{RSM} / \code{PCM}, finish with \code{\link[=reporting_checklist]{reporting_checklist()}} and
\code{\link[=build_apa_outputs]{build_apa_outputs()}} for manuscript-oriented output, then
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} for reusable handoff tables or
\code{\link[=export_summary_appendix]{export_summary_appendix()}} for direct appendix export. For bounded
\code{GPCM}, the same report/export route is available only as a caveated
sensitivity-reporting layer with \code{gpcm_boundary}; keep FACETS-style
score-side review and design forecasting on their separate capability
rows.
}

If you are unsure which helper to call, start with
\code{\link[=mfrmr_output_guide]{mfrmr_output_guide()}}. It returns a compact purpose-to-helper table that
separates \verb{*_table}, \verb{*_report}, \verb{*_review}, \verb{*_bundle}, \verb{export_*}, and
compatibility routes.
}

\section{Which output answers which question}{

\describe{
\item{\code{\link[=specifications_report]{specifications_report()}}}{Documents model type, estimation method,
anchors, and core run settings. Best for method sections and
reproducibility records.}
\item{\code{\link[=data_quality_report]{data_quality_report()}}}{Summarizes retained and dropped rows,
missingness, and unknown elements. Best for data cleaning narratives.}
\item{\code{\link[=estimation_iteration_report]{estimation_iteration_report()}}}{Shows replayed convergence
trajectories. Best for diagnosing slow or unstable estimation.}
\item{\code{\link[=precision_review_report]{precision_review_report()}}}{Summarizes whether \code{SE}, \code{CI}, and
reliability indices are model-based, hybrid, or exploratory. Best for
deciding how strongly to phrase inferential claims.}
\item{\code{\link[=facet_statistics_report]{facet_statistics_report()}}}{Bundles facet summaries, precision
summaries, and variability tests. Best for facet-level reporting.}
\item{\code{\link[=subset_connectivity_report]{subset_connectivity_report()}}}{Summarizes disconnected subsets and
coverage bottlenecks. Best for linking and anchor strategy review.}
\item{\code{\link[=rating_scale_table]{rating_scale_table()}}}{Gives category counts, average measures, and
threshold diagnostics. Best for first-pass category evaluation.}
\item{\code{\link[=category_structure_report]{category_structure_report()}}}{Adds transition points and compact
category warnings. Best for category-order interpretation.}
\item{\code{\link[=category_curves_report]{category_curves_report()}}}{Returns category-probability,
cumulative-probability, expected-ogive, total-information, and
category-specific information coordinates. Best for downstream graphics
and report drafts.}
\item{\code{\link[=write_mfrm_residual_file]{write_mfrm_residual_file()}}}{Writes an observation-level residual
file, optionally with modeled category probabilities. Best for external
case review or reproducible handoff.}
\item{\code{\link[=write_mfrm_subset_file]{write_mfrm_subset_file()}}}{Writes connected-subset summary and
node-membership files. Best for scale-linking review outside R.}
\item{\code{\link[=reporting_checklist]{reporting_checklist()}}}{Turns analysis status into an action list
with priorities and next steps. Best for closing reporting gaps.}
\item{\code{\link[=build_apa_outputs]{build_apa_outputs()}}}{Creates manuscript-draft text, notes,
captions, and section maps from a shared reporting contract.}
\item{\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}}{Converts supported \code{summary()}
outputs into named \code{data.frame} tables with a compact index for appendix
or manuscript handoff, including recovery simulation and recovery
assessment outputs. It also supports bundle-level \code{summary()} / \code{plot()}
for QC before export.}
\item{\code{\link[=export_summary_appendix]{export_summary_appendix()}}}{Exports those validated summary-table
bundles as CSV and optional HTML appendix artifacts without requiring the
broader fit-based export bundle. This is the preferred export route for
recovery simulation evidence.}
\item{\code{\link[=apa_table]{apa_table()}}}{Can now take those summary-table bundles directly,
so a selected component can move from \code{summary()} to a formatted handoff
table without rebuilding the analysis object path.}
}
}

\section{Practical interpretation rules}{

\itemize{
\item Use bundle summaries first, then drill down into component tables.
\item Treat \code{\link[=precision_review_report]{precision_review_report()}} as the gatekeeper for formal inference.
\item Treat category and bias outputs as complementary layers rather than
substitutes for overall fit review.
\item Treat zero-count score categories as scale-functioning caveats. Boundary
zero-count categories can be retained with explicit \code{rating_min} /
\code{rating_max}; intermediate zero-count categories require
\code{keep_original = TRUE} and make adjacent thresholds weakly identified.
\code{summary(describe_mfrm_data(...))} exposes these in \code{Notes}, printed
\code{Caveats}, and \verb{$caveats}; \code{summary(fit)} carries full structured caveats
into printed \code{Caveats} and \verb{$caveats}, with \verb{Key warnings} as a short
triage subset. Summary-table exports use \code{score_category_caveats} and
\code{analysis_caveats}.
\item Use \code{\link[=reporting_checklist]{reporting_checklist()}} before \code{\link[=build_apa_outputs]{build_apa_outputs()}} when a report
still needs missing diagnostics or clearer caveats.
}
}

\section{Typical workflow}{

\itemize{
\item Run documentation:
\code{\link[=fit_mfrm]{fit_mfrm()}} -> \code{\link[=specifications_report]{specifications_report()}} -> \code{\link[=data_quality_report]{data_quality_report()}}.
\item Precision and facet review:
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}} -> \code{\link[=precision_review_report]{precision_review_report()}} ->
\code{\link[=facet_statistics_report]{facet_statistics_report()}}.
\item Scale review:
\code{\link[=rating_scale_table]{rating_scale_table()}} -> \code{\link[=category_structure_report]{category_structure_report()}} ->
\code{\link[=category_curves_report]{category_curves_report()}}.
\item Manuscript handoff (\code{RSM} / \code{PCM}):
\code{\link[=reporting_checklist]{reporting_checklist()}} -> \code{\link[=build_apa_outputs]{build_apa_outputs()}} ->
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} -> \code{summary()} / \code{plot()} -> \code{\link[=apa_table]{apa_table()}}
or \code{\link[=export_summary_appendix]{export_summary_appendix()}} /
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}(include = "summary_tables").
\item Bounded \code{GPCM} handoff:
\code{\link[=reporting_checklist]{reporting_checklist()}} -> direct summaries/plots ->
\code{\link[=build_apa_outputs]{build_apa_outputs()}} or \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} ->
\code{\link[=export_summary_appendix]{export_summary_appendix()}} or caveated \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}, with
\code{gpcm_boundary} retained in report/export objects.
\item Recovery simulation handoff:
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} -> \code{\link[=plot]{plot()}} / \code{\link[=assess_mfrm_recovery]{assess_mfrm_recovery()}} ->
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} -> \code{\link[=export_summary_appendix]{export_summary_appendix()}}.
}
}

\section{Companion guides}{

\itemize{
\item For visual follow-up, see \link{mfrmr_visual_diagnostics}.
\item For one-shot analysis routes, see \link{mfrmr_workflow_methods}.
\item For manuscript assembly, see \link{mfrmr_reporting_and_apa}.
\item For linking and DFF review, see \link{mfrmr_linking_and_dff}.
\item For legacy-compatible wrappers and exports, see \link{mfrmr_compatibility_layer}.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:12], , drop = FALSE]
fit <- fit_mfrm(
  toy_small,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  quad_points = 7,
  maxit = 30
)
diag <- diagnose_mfrm(fit, residual_pca = "none", diagnostic_mode = "both")

spec <- specifications_report(fit)
summary(spec)$overview

prec <- precision_review_report(fit, diagnostics = diag)
summary(prec)$checks

checklist <- reporting_checklist(fit, diagnostics = diag)
subset(checklist$checklist, Section == "Visual Displays", c("Item", "NextAction"))

apa <- build_apa_outputs(fit, diagnostics = diag)
apa$section_map[, c("Heading", "Available")]
bundle <- build_summary_table_bundle(checklist)
bundle$table_index
}

}
