% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation.R
\name{evaluate_mfrm_design}
\alias{evaluate_mfrm_design}
\title{Evaluate MFRM design conditions by repeated simulation}
\usage{
evaluate_mfrm_design(
  n_person = c(30, 50, 100),
  n_rater = c(3, 5),
  n_criterion = c(3, 5),
  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,
  fit_method = c("JML", "MML"),
  model = c("RSM", "PCM", "GPCM"),
  step_facet = NULL,
  slope_facet = NULL,
  slopes = NULL,
  assignment = NULL,
  sparse_controls = NULL,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  sim_spec = NULL,
  seed = NULL,
  progress = interactive(),
  parallel = c("no", "future")
)
}
\arguments{
\item{n_person}{Vector of person counts to evaluate.}

\item{n_rater}{Vector of rater counts to evaluate.}

\item{n_criterion}{Vector of criterion counts to evaluate.}

\item{raters_per_person}{Vector of rater assignments per person.}

\item{design}{Optional named design-grid override supplied as a named list,
named vector, or one-row data frame. Names may use canonical variables
(\code{n_person}, \code{n_rater}, \code{n_criterion}, \code{raters_per_person}), current
public aliases implied by \code{sim_spec} (for example \code{n_judge}, \code{n_task},
\code{judge_per_person}), or role keywords (\code{person}, \code{rater}, \code{criterion},
\code{assignment}). Values may be vectors. The schema-only future branch input
\code{design$facets = c(person = ..., judge = ..., task = ...)} is also
accepted for the currently exposed facet keys. Do not specify the same
variable through both \code{design} and the scalar design-grid arguments.}

\item{reps}{Number of replications per design condition.}

\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{fit_method}{Estimation method passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{model}{Measurement model passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. \code{RSM} and \code{PCM} use
the validated Rasch-family design-planning layer. Bounded \code{GPCM} is
available as a caveated simulation/refit operating-characteristic route.}

\item{step_facet}{Step facet passed to \code{\link[=fit_mfrm]{fit_mfrm()}} when \code{model = "PCM"} or
\code{model = "GPCM"}.
When left \code{NULL}, the function inherits the generator step facet from
\code{sim_spec} when available and otherwise defaults to \code{"Criterion"}.}

\item{slope_facet}{Slope facet passed to \code{\link[=fit_mfrm]{fit_mfrm()}} when
\code{model = "GPCM"}. The current bounded branch requires
\code{slope_facet == step_facet}.}

\item{slopes}{Optional bounded-\code{GPCM} generator slopes used when
\code{sim_spec = NULL}. See \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} for accepted formats.}

\item{assignment}{Optional assignment design used when \code{sim_spec = NULL}.
\code{"sparse_linked"} activates planned-missing sparse rating designs; use
\code{sparse_controls} to specify the linking set.}

\item{sparse_controls}{Optional named list used when
\code{assignment = "sparse_linked"} and \code{sim_spec = NULL}, or retained from
a sparse linked \code{sim_spec}. See \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}}.}

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

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

\item{residual_pca}{Residual PCA mode passed to \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\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()}} used as the base data-generating mechanism.
When supplied, the design grid still varies \code{n_person}, \code{n_rater},
\code{n_criterion}, and \code{raters_per_person}, but latent-spread assumptions,
thresholds, and other generator settings come from \code{sim_spec}.
If \code{sim_spec} contains step-facet-specific thresholds, the design grid may
not vary the number of levels for that step facet away from the
specification. If \code{sim_spec} stores an active latent-regression population
generator, this helper currently requires \code{fit_method = "MML"} so each
replication can refit the population model.}

\item{seed}{Optional seed for reproducible replications.}

\item{progress}{Logical. Whether to show a progress bar across
design-by-replication cells. Defaults to \code{\link[=interactive]{interactive()}}, so interactive
exploratory runs show progress while non-interactive tests, scripts, and
report rendering stay quiet. Set \code{TRUE} or \code{FALSE} explicitly to override.}

\item{parallel}{Parallelisation strategy for the rep loop within
each design row. \code{"no"} (default) runs serially; \code{"future"}
uses \code{future.apply::future_lapply} and respects whatever
\code{future::plan()} is currently active. The Suggests package
\code{future.apply} must be installed for the parallel path to
activate; otherwise the call falls back to serial execution
with a single message. Cross-design-row parallelism is planned
for a future release.}
}
\value{
An object of class \code{mfrm_design_evaluation} with components:
\itemize{
\item \code{design_grid}: evaluated design conditions. When \code{sim_spec} carries custom
public facet names, matching design-variable alias columns are included
alongside the canonical internal columns.
\item \code{results}: facet-level replicate results, with the same design-variable
alias columns when applicable.
\item \code{rep_overview}: run-level status and timing, with the same design-variable
alias columns when applicable.
\item \code{design_descriptor}: role-based design-variable metadata used by planning
summaries and plots
\item \code{planning_scope}: explicit record of the current planning contract
\item \code{planning_constraints}: explicit record of which design variables remain
mutable under the current simulation specification
\item \code{planning_schema}: combined planner-schema contract bundling the role
descriptor, scope boundary, and current mutability map
\item \code{gpcm_boundary}: bounded-\code{GPCM} caveat row when a \code{GPCM} design route is
used
\item \code{notes}: short interpretation notes
\item \code{settings}: simulation settings
\item \code{ademp}: simulation-study metadata (aims, DGM, estimands, methods, performance measures)
}
}
\description{
Evaluate MFRM design conditions by repeated simulation
}
\details{
This helper runs a compact Monte Carlo design study for common rater-by-item
many-facet settings.

For each design condition, the function:
\enumerate{
\item generates synthetic data with \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}
\item fits the requested MFRM with \code{\link[=fit_mfrm]{fit_mfrm()}}
\item computes diagnostics with \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}
\item stores recovery and precision summaries by facet
}

The result is intended for planning questions such as:
\itemize{
\item how many raters are needed for stable rater separation?
\item how does \code{raters_per_person} affect severity recovery?
\item when do category counts become too sparse for comfortable interpretation?
}

This is a \strong{parametric simulation study}. It does not take one observed
design (for example, 4 raters x 30 persons x 3 criteria) and analytically
extrapolate what would happen under a different design (for example,
2 raters x 40 persons x 5 criteria). Instead, you specify a design grid and
data-generating assumptions (latent spread, facet spread, thresholds, noise,
and scoring structure), and the function repeatedly generates synthetic data
under those assumptions.

When you want the simulated conditions to resemble an existing study, use
substantive knowledge or estimates from that study to choose
\code{theta_sd}, \code{rater_sd}, \code{criterion_sd}, \code{score_levels}, and related
settings before running the design evaluation.

When \code{sim_spec} is supplied, the function uses it as the explicit
data-generating mechanism. This is the recommended route when you want a
design study to stay close to a previously fitted run while still varying the
candidate sample sizes or rater-assignment counts.

Sparse linked simulation specifications and direct
\code{assignment = "sparse_linked"} calls are carried into the design-evaluation
output. The resulting sparse-design columns report planned-missingness and
rater-link diagnostics (for example design density and rater-pair common
persons). They are design diagnostics, not fit statistics or universal
adequacy thresholds.

If that specification also stores a latent-regression population generator,
each replication carries forward the simulated one-row-per-person background
data and refits the MML population-model branch. This remains a scenario
study under explicit assumptions; it is not a closed-form predictive
distribution for one future administration.

Bounded \code{GPCM} design evaluation is available with caveats. It repeatedly
generates data from the supplied or fit-derived slope-aware specification,
refits bounded \code{GPCM}, and summarizes facet-level operating characteristics.
The route remains a role-based person x rater-like x criterion-like planner:
it does not validate diagnostic-screening or signal-detection rules, does
not provide a fully arbitrary-facet planner, and does not replace
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} for slope-recovery adequacy review.

Recovery metrics are reported only when the generator and fitted model target
the same facet-parameter contract. In practice this means the same
\code{model}, and for \code{PCM}, the same \code{step_facet}. When these do not align,
recovery fields are set to \code{NA} and the output records the reason. Even when
these contract checks pass, the recovery summaries still assume compatible
orientation and anchoring conventions across the generator and fitted model.
}
\section{Reported metrics}{

Facet-level simulation results include:
\itemize{
\item \code{Separation} (\eqn{G = \mathrm{SD_{adj}} / \mathrm{RMSE}}):
how many statistically distinct strata the facet resolves.
\item \code{Reliability} (\eqn{G^2 / (1 + G^2)}): analogous to Cronbach's
\eqn{\alpha} for the reproducibility of element ordering.
\item \code{Strata} (\eqn{(4G + 1) / 3}): number of distinguishable groups.
\item Mean \code{Infit} and \code{Outfit}: average fit mean-squares across elements.
\item \code{MisfitRate}: share of elements with \eqn{|\mathrm{ZSTD}| > 2}.
\item Sparse-design diagnostics when \code{assignment = "sparse_linked"}:
\code{MeanDesignDensity}, \code{MeanPlannedMissingRate}, \code{MeanLinkPersons},
\code{MeanMinCommonPersonsPerRaterPair}, \code{MaxZeroCommonRaterPairs}, and
\code{MaxRaterPairsBelowTarget}.
\item \code{SeverityRMSE}: root-mean-square error of recovered parameters vs
the known truth \strong{after facet-wise mean alignment}, so that the
usual Rasch/MFRM location indeterminacy does not inflate recovery
error. This quantity is reported only when the generator and fitted model
target the same facet-parameter contract.
\item \code{SeverityBias}: mean signed recovery error after the same alignment;
values near zero are expected. This is likewise omitted when the
generator/fitted-model contract does not align.
}
}

\section{Interpreting output}{

Start with \code{summary(x)$design_summary}, then plot one focal metric at a time
(for example rater \code{Separation} or criterion \code{SeverityRMSE}).

Higher separation/reliability is generally better, whereas lower
\code{SeverityRMSE}, \code{MeanMisfitRate}, and \code{MeanElapsedSec} are preferable.

When choosing among designs, look for the point where increasing
\code{n_person} or \code{raters_per_person} yields diminishing returns in
separation and RMSE---this identifies the cost-effective design
frontier.  \code{ConvergedRuns / reps} should be near 1.0; low
convergence rates indicate the design is too small for the chosen
estimation method.

This is a Monte Carlo design-evaluation helper. It can visualize how
separation, reliability, strata, RMSE, and fit-screen rates change when
you vary person, rater, criterion, or assignment counts. For analytic
generalizability-theory planning, pair observed variance-component review
from \code{\link[=mfrm_generalizability]{mfrm_generalizability()}} with D-study projections from
\code{\link[=mfrm_d_study]{mfrm_d_study()}}.
}

\section{References}{

The simulation logic follows the general Monte Carlo / operating-characteristic
framework described by Morris, White, and Crowther (2019) and the
ADEMP-oriented planning/reporting guidance summarized for psychology by
Siepe et al. (2024). In \code{mfrmr}, \code{evaluate_mfrm_design()} is a practical
many-facet design-planning wrapper rather than a direct reproduction of one
published simulation study.
\itemize{
\item Morris, T. P., White, I. R., & Crowther, M. J. (2019).
\emph{Using simulation studies to evaluate statistical methods}.
Statistics in Medicine, 38(11), 2074-2102.
\item Siepe, B. S., Bartos, F., Morris, T. P., Boulesteix, A.-L., Heck, D. W.,
& Pawel, S. (2024). \emph{Simulation studies for methodological research in
psychology: A standardized template for planning, preregistration, and
reporting}. Psychological Methods.
}
}

\examples{
\donttest{
sim_eval <- suppressWarnings(evaluate_mfrm_design(
  design = list(person = c(8, 12), rater = 2, criterion = 2, assignment = 1),
  reps = 1,
  maxit = 30,
  seed = 123
))
s_eval <- summary(sim_eval)
s_eval$design_summary[, c("Facet", "n_person", "MeanSeparation", "MeanSeverityRMSE")]
p_eval <- plot(sim_eval, facet = "Rater", metric = "separation", x_var = "n_person", draw = FALSE)
names(p_eval)
}
}
\seealso{
\code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, \link{summary.mfrm_design_evaluation}, \link{plot.mfrm_design_evaluation}
}
