% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation.R
\name{assess_mfrm_recovery}
\alias{assess_mfrm_recovery}
\alias{plot.mfrm_recovery_assessment}
\title{Assess whether recovery-simulation results are ready to use}
\usage{
assess_mfrm_recovery(
  x,
  min_reps = 30,
  min_success_rate = 0.95,
  min_convergence_rate = 0.95,
  min_se_available = 0.8,
  coverage_target = 0.95,
  coverage_tolerance = 0.05,
  max_mcse_rmse_ratio = 0.25,
  max_rmse = NULL,
  max_abs_bias = NULL,
  top_n = 6,
  digits = 3,
  ...
)

\method{plot}{mfrm_recovery_assessment}(
  x,
  y = NULL,
  type = c("status", "metrics"),
  metric = c("rmse", "bias", "coverage", "se_available", "mcse_rmse"),
  draw = TRUE,
  ...
)
}
\arguments{
\item{x}{For \code{assess_mfrm_recovery()}, output from
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}}. For \code{plot.mfrm_recovery_assessment()}, output
from \code{assess_mfrm_recovery()}.}

\item{min_reps}{Minimum replication count expected before treating the
simulation as more than a smoke check.}

\item{min_success_rate}{Minimum acceptable proportion of replications that
generated data and produced a fitted model.}

\item{min_convergence_rate}{Minimum acceptable proportion of replications
whose fitted model reported convergence.}

\item{min_se_available}{Minimum acceptable proportion of recovery rows with
standard errors in each parameter group. Set to \code{NULL} to skip this check.}

\item{coverage_target}{Nominal coverage target, usually \code{0.95}.}

\item{coverage_tolerance}{Absolute tolerance around \code{coverage_target}.}

\item{max_mcse_rmse_ratio}{Maximum acceptable Monte Carlo SE of RMSE divided
by RMSE. Set to \code{NULL} to skip this precision check.}

\item{max_rmse}{Optional practical RMSE limit. Use a scalar for all parameter
groups or a named vector/list with names such as \code{"facet"}, \code{"step"},
\code{"slope"}, \code{"Rater"}, or \code{"facet:Rater:logit"}.}

\item{max_abs_bias}{Optional practical absolute-bias limit. Naming follows
\code{max_rmse}.}

\item{top_n}{Number of next-action lines retained in the compact output.}

\item{digits}{Digits used by the print method.}

\item{...}{Reserved for future extensions.}

\item{y}{Reserved for S3 generic compatibility.}

\item{type}{Assessment plot route. \code{"status"} summarizes checklist status
counts; \code{"metrics"} plots a parameter-group assessment metric colored by
its status.}

\item{metric}{Metric used when \code{type = "metrics"}. Supported values are
\code{"rmse"}, \code{"bias"}, \code{"coverage"}, \code{"se_available"}, and \code{"mcse_rmse"}.}

\item{draw}{If \code{TRUE}, draw with base graphics. If \code{FALSE}, return an
\code{mfrm_plot_data} object with reusable plot tables and metadata.}
}
\value{
An object of class \code{mfrm_recovery_assessment} with:
\itemize{
\item \code{overview}: compact run-level status.
\item \code{checklist}: reviewer-facing adequacy checks.
\item \code{condition_review}: generator-condition metadata, including bounded
\code{GPCM} slope-regime interpretation and generated score-category support
when available.
\item \code{condition_reporting_notes}: reporter-facing generator-condition caveats
separated from recovery metrics and release-gate decisions.
\item \code{diagnostic_reporting_notes}: reporter-facing fit/separation caveats
retained as diagnostic context rather than recovery gates.
\item \code{diagnostic_review}: optional fit/separation operating-characteristic
context when retained by \code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}}.
\item \code{metric_review}: parameter-group metric checks.
\item \code{uncertainty_review}: compact coverage / SE availability interpretation.
\item \code{reading_order}: recommended first-read order for the summary, condition,
plot, and row-level recovery outputs.
\item \code{next_actions}: short action list sorted by severity.
\item \code{thresholds}: thresholds used for the assessment.
}
}
\description{
Converts the numerical output from \code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} into a
reviewer-facing adequacy checklist. The goal is not to impose one universal
pass/fail rule; it is to make the main user questions explicit: Did the runs
finish? Did the fitted models converge? Are uncertainty summaries available?
Are coverage and Monte Carlo precision plausible? If practical RMSE or bias
limits are supplied, which parameter groups need follow-up? For bounded
\code{GPCM}, which slope-regime generator condition frames the recovery evidence?
}
\details{
RMSE and bias adequacy depends on the substantive scale and the use case, so
the function does not mark them as failed unless the user supplies
\code{max_rmse} or \code{max_abs_bias}. Without those limits, the corresponding rows are
marked \code{not_assessed} and the next action asks the user to set practical
thresholds when a decision depends on the metric.

The \code{condition_review} table is generator metadata for interpreting the
recovery run. For bounded \code{GPCM}, \code{GPCMSlopeRegime}, \code{StressLevel}, and
generated score-category support describe the data-generating condition;
they are not model-fit tests and they are not literature-derived adequacy
cut points. \code{condition_reporting_notes} turns those generator conditions
into reporter-facing caveats, such as high-dispersion slope stress or sparse
generated score support.

The optional \code{diagnostic_review} table is available when
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} was called with \code{include_diagnostics = TRUE}.
It summarizes fit and separation operating characteristics as diagnostic
context only. Its availability fields do not mean that fit or separation
values are adequate, and those rows do not enter the recovery adequacy
status. \code{diagnostic_reporting_notes} should be read first when drafting
fit/separation language because it separates zero separation/reliability,
absolute fit-ZSTD flags, and df-sensitive ZSTD flags from recovery gates.

\code{plot.mfrm_recovery_assessment()} is a user-facing review aid. Use
\code{type = "status"} first to see where checklist attention is needed, then
\code{type = "metrics"} to inspect the parameter groups behind RMSE, bias,
coverage, standard-error availability, or Monte Carlo precision statuses.
The intended reading order is \code{summary(recovery_review)}, then
\code{condition_reporting_notes} and \code{condition_review}, then
\code{diagnostic_reporting_notes} and \code{diagnostic_review}, then the status plot,
then the metric plot, then the row-level recovery table for the parameter
groups that need follow-up. When \code{draw = FALSE}, the plot data also include
\code{reading_order}, \code{guidance}, condition/diagnostic handoff tables, and
user-facing plot tables such as \code{section_status} for status plots and
\code{metric_review} for metric plots.
}
\examples{
\donttest{
rec <- evaluate_mfrm_recovery(
  n_person = 12,
  n_rater = 2,
  n_criterion = 2,
  reps = 1,
  maxit = 30,
  seed = 123
)
assess_mfrm_recovery(rec, min_reps = 1, max_rmse = 1)

# Read the bounded-GPCM generator condition separately from recovery adequacy.
gpcm_spec <- build_mfrm_sim_spec(
  n_person = 14,
  n_rater = 2,
  n_criterion = 2,
  raters_per_person = 2,
  model = "GPCM",
  step_facet = "Criterion",
  slope_facet = "Criterion",
  slopes = c(0.85, 1.15),
  assignment = "crossed"
)
gpcm_rec <- suppressWarnings(evaluate_mfrm_recovery(
  sim_spec = gpcm_spec,
  reps = 1,
  fit_method = "MML",
  quad_points = 5,
  maxit = 12,
  include_diagnostics = TRUE,
  include_person = FALSE,
  seed = 456
))
gpcm_review <- assess_mfrm_recovery(
  gpcm_rec,
  min_reps = 1,
  max_rmse = c(slope = 2),
  max_abs_bias = c(slope = 1),
  min_se_available = NULL,
  max_mcse_rmse_ratio = NULL
)
gpcm_review$condition_reporting_notes[, c(
  "ConditionArea", "ReportingAttention", "ConditionFinding"
)]
gpcm_review$condition_review[, c(
  "Model", "GPCMSlopeRegime", "StressLevel", "ScoreSupportStatus"
)]
gpcm_review$diagnostic_reporting_notes[, c(
  "Facet", "ReportingAttention", "DiagnosticFinding"
)]
summary(gpcm_review)$reading_order
}
}
\seealso{
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}}, \code{\link[=plot.mfrm_recovery_simulation]{plot.mfrm_recovery_simulation()}}
}
