% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation.R
\name{evaluate_mfrm_recovery}
\alias{evaluate_mfrm_recovery}
\title{Evaluate parameter recovery by repeated simulation and refitting}
\usage{
evaluate_mfrm_recovery(
  n_person = 50,
  n_rater = 4,
  n_criterion = 4,
  raters_per_person = n_rater,
  design = NULL,
  reps = 10,
  score_levels = 4,
  theta_sd = 1,
  rater_sd = 0.35,
  criterion_sd = 0.25,
  noise_sd = 0,
  step_span = 1.4,
  model = c("RSM", "PCM", "GPCM"),
  step_facet = NULL,
  slope_facet = NULL,
  thresholds = NULL,
  slopes = NULL,
  assignment = NULL,
  sparse_controls = NULL,
  sim_spec = NULL,
  fit_method = c("JML", "MML"),
  maxit = 25,
  quad_points = 7,
  include_person = TRUE,
  include_diagnostics = FALSE,
  diagnostic_fit_df_method = c("both", "engine", "facets"),
  seed = NULL
)
}
\arguments{
\item{n_person}{Number of persons/respondents.}

\item{n_rater}{Number of rater facet levels.}

\item{n_criterion}{Number of criterion/item facet levels.}

\item{raters_per_person}{Number of raters assigned to each person.}

\item{design}{Optional named design override supplied as a named list,
named vector, or one-row data frame. When \code{sim_spec = NULL}, names may use
canonical variables (\code{n_person}, \code{n_rater}, \code{n_criterion},
\code{raters_per_person}) or role keywords (\code{person}, \code{rater}, \code{criterion},
\code{assignment}). For the currently exposed facet keys, the schema-only
future branch input \code{design$facets = c(person = ..., rater = ..., criterion = ...)} is also accepted. Do not specify the same variable
through both \code{design} and the scalar count arguments.}

\item{reps}{Number of Monte Carlo replications.}

\item{score_levels}{Number of ordered score categories.}

\item{theta_sd}{Standard deviation of simulated person measures.}

\item{rater_sd}{Standard deviation of simulated rater severities.}

\item{criterion_sd}{Standard deviation of simulated criterion difficulties.}

\item{noise_sd}{Optional observation-level noise added to the linear predictor.}

\item{step_span}{Spread of step thresholds on the logit scale.}

\item{model}{Measurement model recorded in the simulation setup. The current
public generator supports \code{RSM}, \code{PCM}, and bounded \code{GPCM}.}

\item{step_facet}{Step facet used when \code{model = "PCM"} and threshold values
vary across levels. Currently \code{"Criterion"} and \code{"Rater"} are supported.}

\item{slope_facet}{Slope facet used when \code{model = "GPCM"}. The current
bounded \code{GPCM} branch requires \code{slope_facet == step_facet}.}

\item{thresholds}{Optional threshold specification. Use a numeric vector of
common thresholds; a named list such as \code{list(C01 = c(-1, 0, 1))}; a
numeric matrix with one row per \code{StepFacet} and one column per step; or a
long data frame with columns \code{StepFacet}, \code{Step}/\code{StepIndex}, and
\code{Estimate}.}

\item{slopes}{Optional slope specification used when \code{model = "GPCM"}.
Use either a numeric vector aligned to the generated slope-facet levels or
a data frame with columns \code{SlopeFacet} and \code{Estimate}. Supplied slopes are
treated as relative discriminations and normalized to the package's
geometric-mean-one identification convention on the log scale. When
omitted, slopes default to 1 for every slope-facet level, giving an exact
\code{PCM} reduction.}

\item{assignment}{Assignment design. \code{"crossed"} means every person sees
every rater; \code{"rotating"} uses a balanced rotating subset; \code{"resampled"}
reuses person-level rater-assignment profiles stored in \code{sim_spec};
\code{"sparse_linked"} uses an incomplete rating design with optional linking
persons; \code{"skeleton"} reuses an observed response skeleton stored in
\code{sim_spec}, including optional \code{Group}/\code{Weight} columns when available.
When omitted, the function chooses \code{"crossed"} if
\code{raters_per_person == n_rater}, otherwise \code{"rotating"}.}

\item{sparse_controls}{Optional named list used when
\code{assignment = "sparse_linked"}. Supported entries are \code{link_fraction},
\code{link_persons}, \code{link_raters_per_person}, \code{assignment_mode}, and
\code{min_common_persons_per_rater_pair}. See \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} for the
same contract.}

\item{sim_spec}{Optional output from \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} or
\code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}}. When supplied, it defines the generator setup;
direct scalar arguments are treated as legacy inputs and should generally
be left at their defaults except for \code{seed}. Any custom public two-facet
names recorded in \code{sim_spec$facet_names} are also carried into the
simulated output and downstream planning helpers. If \code{sim_spec} stores an
active latent-regression population generator, the returned object also
carries the generated one-row-per-person background-data table needed to
refit that population model later.}

\item{fit_method}{Estimation method passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{maxit}{Maximum optimizer iterations passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{quad_points}{Quadrature points used when \code{fit_method = "MML"}.}

\item{include_person}{Logical. When \code{TRUE}, include person-measure recovery
rows when the fitted object exposes person estimates.}

\item{include_diagnostics}{Logical. When \code{TRUE}, run \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} after
each successful refit and retain facet-level fit/separation operating
characteristics. These diagnostics are reported separately from recovery
metrics and are not release-success criteria by themselves.}

\item{diagnostic_fit_df_method}{Fit-ZSTD degrees-of-freedom convention used
for optional diagnostic operating-characteristic summaries. Use \code{"both"}
when reviewing FACETS-style df sensitivity.}

\item{seed}{Optional random seed.}
}
\value{
An object of class \code{mfrm_recovery_simulation} with components:
\itemize{
\item \code{recovery}: row-level truth/estimate comparisons by replication.
\item \code{recovery_summary}: parameter-type summaries across replications.
\item \code{rep_overview}: replication-level convergence, timing, error status, and
sparse-design diagnostics when applicable.
\item \code{diagnostic_oc}: optional replication-by-facet fit/separation operating
characteristics when \code{include_diagnostics = TRUE}.
\item \code{diagnostic_oc_summary}: optional facet-level diagnostic operating-
characteristic summary.
\item \code{settings}: fitting and simulation settings.
\item \code{ademp}: simulation-study metadata.
}
}
\description{
Runs a compact parameter-recovery simulation study: generate data from a
known ordered many-facet data-generating setup, refit the requested model,
align estimates to the known truth where location indeterminacy requires it,
and summarize bias, RMSE, MAE, correlation, and standard-error coverage.
}
\details{
This helper is deliberately narrower than \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}. Design
evaluation asks which design condition is operationally adequate; recovery
simulation asks whether the fitted model recovers the known parameters under
one explicit data-generating setup.

Location-like parameters (\code{Person}, non-person facets, and steps) are
summarized after mean alignment within each replication and parameter group.
This follows the usual Rasch/MFRM identification convention: adding a common
constant to one location block should not be counted as recovery failure.
Raw, unaligned errors are retained in \code{recovery} and summarized as
\code{RawBias} / \code{RawRMSE}.

For bounded \code{GPCM}, supplied generator slopes are treated as relative
discriminations and normalized to the same geometric-mean-one log-slope
identification used by the fitter. Slope recovery is therefore summarized on
the identified log-slope scale without an additional mean-alignment step.
Direct data generation and refitting are supported, but broader GPCM design-
planning claims remain outside the current package boundary.

Sparse linked generators are supported through \code{sim_spec} or direct
\code{assignment = "sparse_linked"} plus \code{sparse_controls}. Their design-density
and rater-link diagnostics are retained in \code{rep_overview}; recovery metrics
remain parameter-recovery summaries and should not be read as evidence that
a sparse linking design is adequate by itself.

The returned \code{ademp} component follows the simulation-study framing of
Morris, White, and Crowther (2019) and the ADEMP planning/reporting template
used in later simulation-study guidance.
}
\section{Typical workflow}{

\enumerate{
\item Build a simulation specification with \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} or pass scalar
generator arguments directly.
\item Run \code{evaluate_mfrm_recovery(...)} with a modest \code{reps} value for a smoke
check, then increase \code{reps} for stable Monte Carlo summaries.
\item Inspect \code{summary(x)$recovery_summary} and the row-level \code{x$recovery} table.
}
}

\examples{
\donttest{
rec <- evaluate_mfrm_recovery(
  n_person = 12,
  n_rater = 2,
  n_criterion = 2,
  reps = 1,
  maxit = 30,
  seed = 123
)
summary(rec)$recovery_summary[, c("ParameterType", "Facet", "RMSE", "Bias")]
}
}
\seealso{
\code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}, \code{\link[=fit_mfrm]{fit_mfrm()}}
}
