% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-results.R
\name{mfrm_results}
\alias{mfrm_results}
\title{Build comprehensive first-screen MFRM results}
\usage{
mfrm_results(
  fit,
  include = "standard",
  response_time = NULL,
  response_time_data = NULL,
  response_time_facets = NULL,
  response_time_score = NULL,
  output = c("object", "summary", "tables", "html")
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}. A standard
long-format \code{data.frame} is also accepted when person and score columns can
be inferred unambiguously from common names such as \code{Person} and \code{Score};
all remaining columns are treated as facets.}

\item{include}{Result sections or purpose presets to include. Purpose
presets are \code{"standard"}, \code{"publication"}, \code{"validation"}, \code{"facets"},
\code{"bias"}, \code{"misfit_review"}, \code{"linking"}, \code{"network"},
\code{"gpcm_review"}, and \code{"all"}.
Section names include \code{"fit"}, \code{"diagnostics"}, \code{"tables"},
\code{"precision"}, \code{"reporting"}, \code{"categories"}, \code{"plots"},
\code{"facets_fit"}, \code{"bias"}, \code{"misfit"}, \code{"linking"}, \code{"network"},
and \code{"apa"}.}

\item{response_time}{Optional response-time column name. When \code{NULL} and
\code{include} contains \code{"response_time"}, conservative column names such as
\code{ResponseTime}, \code{response_time}, or \code{RT} are detected when available.}

\item{response_time_data}{Optional original long-format data containing the
timing column. Required for already fitted objects unless the timing
column is still present in \code{fit$prep$data}.}

\item{response_time_facets}{Optional facet columns for response-time
summaries. Defaults to the fitted model's source facet columns when
available.}

\item{response_time_score}{Optional score column for response-time
summaries. Defaults to the fitted model's source score column when
available.}

\item{output}{Return format: \code{"object"} for an \code{mfrm_results} object,
\code{"summary"} for its compact summary, \code{"tables"} for a named list of
available data frames, or \code{"html"} for a temporary HTML report.}
}
\value{
Depending on \code{output}, an \code{mfrm_results} object, a
\code{summary.mfrm_results} object, a named table list, or an
\code{mfrm_results_html} object.
}
\description{
Build comprehensive first-screen MFRM results
}
\details{
\code{mfrm_results()} is a high-level result object. It does not introduce a new
estimator or a new validity rule. It fits only when \code{fit} is a data frame,
computes diagnostics automatically when needed, and collects output from
existing helpers such as \code{\link[=diagnose_mfrm]{diagnose_mfrm()}},
\code{\link[=fit_measures_table]{fit_measures_table()}}, \code{\link[=precision_review_report]{precision_review_report()}}, and
\code{\link[=reporting_checklist]{reporting_checklist()}}. Sections that are unsupported for a particular fit
are retained in the \code{status} table as \code{not_available} rather than stopping
the whole results workflow. The returned object also carries
\code{next_actions} and \code{input$reproducible_code} so users can move from the
comprehensive first screen to explicit reporting or replay code.
}
\section{Include presets}{

\itemize{
\item \code{"standard"}: fit, diagnostics, tables, precision, reporting, categories,
and plot routes
\item \code{"publication"}: standard sections plus APA output assembly
\item \code{"validation"}: standard sections plus FACETS-fit/df-sensitivity review
\item \code{"facets"}: fit, diagnostics, tables, categories, plots, and FACETS-fit
review for FACETS-facing migration work
\item \code{"bias"} / \code{"bias_review"}: standard sections plus facet-level bias-screen
guidance; interaction bias still requires explicit facet-pair selection
\item \code{"misfit"} / \code{"misfit_review"}: standard sections plus unexpected-response,
displacement, and pathway-map case-review surfaces
\item \code{"linking"} / \code{"anchors"}: standard sections plus anchor-readiness and
operational linking-review surfaces from the fitted object's stored
anchor review; drift and screened-chain review still require multiple
fitted forms or waves
\item \code{"network"}: standard sections plus network/connectivity review
\item \code{"response_time"}: descriptive response-time QC review when timing
metadata are supplied through \code{response_time} / \code{response_time_data}
\item \code{"gpcm_review"}: standard sections with bounded-\code{GPCM} caveats retained
in the collected summaries and reports
\item \code{"all"}: standard sections plus FACETS-fit, network, APA, and
response-time sections
}
}

\section{Response-time metadata}{

Response-time review is opt-in and descriptive. It does not change fitted
MFRM estimates, fit a joint speed-accuracy model, or create automatic
exclusion rules. Use \code{include = "response_time"} together with
\code{response_time = "ResponseTime"}. When \code{fit} is an already fitted object,
also supply \code{response_time_data = original_data} because fitted objects keep
only the measurement columns needed for estimation.
}

\section{What to inspect first}{

Start with \code{summary(res)}. The most useful fields are:
\itemize{
\item \code{overview}: input mode, model, method, table count, and plot-route count
\item \code{triage}: first-screen signals ordered by unavailable/review/info/ok
\item \code{status}: which sections were available, skipped, or unsupported
\item \code{plot_map}: the supported \code{plot(res, type = ...)} routes for this object
\item \code{next_actions}: recommended follow-up calls
\item \code{reproducible_code}: replay scaffold for the first-screen route
}
}

\section{Data-frame input}{

Direct data-frame input is intentionally conservative. It is intended for
standard columns such as \code{Person}, \code{Score}, \code{Rater}, and \code{Criterion}. For
research scripts, use \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=run_mfrm_facets]{run_mfrm_facets()}} explicitly when
column roles, model, method, anchors, or missing-data rules need to be
documented. Use \code{\link[=mfrm_results_interactive]{mfrm_results_interactive()}} only when you want an opt-in
column-selection wizard in an interactive session.
}

\section{Visualization and HTML}{

\code{plot(res)} routes to a FACETS-style model-level visual bundle by default.
Other routes include \code{plot(res, type = "wright")}, \code{"pathway"}, \code{"qc"},
\code{"category"}, \code{"anchors"}, and \code{"tables"}. \code{output = "html"} writes a
lightweight temporary HTML file;
use \code{\link[=launch_mfrmr_viewer]{launch_mfrmr_viewer()}} when you want an optional local Shiny reader
for an already-created \code{mfrm_results} object. Use
\code{\link[=export_mfrm_results]{export_mfrm_results()}} for a lightweight download of the comprehensive
results object, or \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} when a fit-centered durable
analysis archive is needed.
}

\section{Typical workflow}{

\enumerate{
\item Fit explicitly with \code{\link[=fit_mfrm]{fit_mfrm()}} in scripts and manuscripts.
\item Call \code{res <- mfrm_results(fit)}.
\item Read \code{summary(res)$triage}, \code{summary(res)$status},
\code{summary(res)$plot_map}, and \code{summary(res)$next_actions}.
\item Use \code{plot(res, type = "qc")} for the first visual screen.
\item Optionally inspect the same result with \code{\link[=launch_mfrmr_viewer]{launch_mfrmr_viewer()}} in an
interactive session.
\item Use \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} or the helper named in
\code{summary(res)$next_actions} for report-specific follow-up.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:8], , drop = FALSE]

# JML keeps the help example fast; use the recommended workflow settings
# for final analyses.
fit <- fit_mfrm(toy_small, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
res <- mfrm_results(fit)

sx <- summary(res)
sx$overview
sx$triage
sx$plot_map
sx$next_actions
mfrm_results(fit, include = "validation", output = "summary")$status

plot(res, type = "qc", draw = FALSE)

# Direct data-frame input is available for conservative exploratory use
# when Person and Score columns are unambiguous.
mfrm_results(
  toy_small,
  include = c("fit", "diagnostics"),
  output = "summary"
)$mapping
}
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}},
\code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}},
\code{\link[=export_mfrm_results]{export_mfrm_results()}},
\code{\link[=launch_mfrmr_viewer]{launch_mfrmr_viewer()}}, \code{\link[=mfrmr_output_guide]{mfrmr_output_guide()}}
}
