% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation.R
\name{evaluate_mfrm_diagnostic_screening}
\alias{evaluate_mfrm_diagnostic_screening}
\title{Evaluate legacy and strict marginal diagnostic screening under controlled misfit scenarios}
\usage{
evaluate_mfrm_diagnostic_screening(
  n_person = c(30, 50, 100),
  n_rater = c(4),
  n_criterion = c(4),
  raters_per_person = n_rater,
  design = NULL,
  reps = 10,
  scenarios = c("well_specified", "local_dependence"),
  local_dependence_sd = 0.8,
  local_dependence_facet = NULL,
  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,
  slopes = NULL,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  sim_spec = NULL,
  include_report = FALSE,
  report_include = c("fit", "diagnostics", "tables", "precision", "reporting"),
  report_style = c("qc", "apa", "validation", "reviewer", "technical"),
  seed = NULL
)
}
\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}, or role keywords
(\code{person}, \code{rater}, \code{criterion}, \code{assignment}). Values may be vectors.}

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

\item{scenarios}{Screening scenarios to evaluate. The current first release
supports \code{"well_specified"}, \code{"local_dependence"}, and
\code{"latent_misspecification"}, plus
\code{"step_structure_misspecification"}.}

\item{local_dependence_sd}{Standard deviation of the shared context effect
injected in the \code{"local_dependence"} scenario.}

\item{local_dependence_facet}{Facet that receives the shared
\verb{Person x facet} dependence effect. Use \code{"criterion"}, \code{"rater"}, or an
active public facet name. Defaults to the criterion-like facet.}

\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 passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. Bounded \code{GPCM} is
supported with caveats as slope-aware screening sensitivity evidence.}

\item{step_facet}{Step facet passed to \code{\link[=fit_mfrm]{fit_mfrm()}} when \code{model = "PCM"} or
\code{model = "GPCM"}.}

\item{slope_facet}{Slope facet passed to \code{\link[=fit_mfrm]{fit_mfrm()}} when
\code{model = "GPCM"}. Defaults to the fitted step facet.}

\item{slopes}{Optional bounded-\code{GPCM} slope specification used by direct
simulation calls when \code{sim_spec = NULL}.}

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

\item{quad_points}{Quadrature points for the internal \code{MML} fit.}

\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.}

\item{include_report}{Logical; if \code{TRUE}, each successful replicate also
builds \code{mfrm_results()} and \code{\link[=mfrm_report]{mfrm_report()}} and records the \code{report_index}
readiness/signaling surface. This is intentionally opt-in because it
repeats the comprehensive result-building workflow.}

\item{report_include}{\code{include} vector passed to \code{\link[=mfrm_results]{mfrm_results()}} when
\code{include_report = TRUE}.}

\item{report_style}{Report style passed to \code{\link[=mfrm_report]{mfrm_report()}} when
\code{include_report = TRUE}.}

\item{seed}{Optional seed for reproducible replications.}
}
\value{
An object of class \code{mfrm_diagnostic_screening} with:
\itemize{
\item \code{design_grid}: evaluated design conditions, including public alias columns
when applicable
\item \code{results}: replicate-level screening metrics for each design and scenario
\item \code{scenario_summary}: aggregated scenario-by-design screening summaries
\item \code{performance_summary}: scenario-by-design screening-performance summary
including runtime, agreement, Type I proxy, and sensitivity proxy columns
\item \code{report_signal_summary}: optional scenario-by-design summary of
\code{mfrm_report()} \code{report_index} availability, readiness, and review-signal
counts when \code{include_report = TRUE}
\item \code{scenario_contrast}: each misspecification scenario minus the
well-specified baseline when the baseline scenario was evaluated
\item \code{design_descriptor}: role-based design-variable metadata
\item \code{planning_scope}: explicit record of the current planning contract
\item \code{planning_constraints}: explicit record of mutable/locked design variables
\item \code{planning_schema}: combined planner-schema contract
\item \code{gpcm_boundary}: bounded-\code{GPCM} caveat row when present
\item \code{settings}: simulation and fitting settings
\item \code{ademp}: simulation-study metadata
\item \code{notes}: short interpretation notes
}
}
\description{
Evaluate legacy and strict marginal diagnostic screening under controlled misfit scenarios
}
\details{
This helper performs a compact Monte Carlo validation study for the package's
current diagnostic architecture.

For each design condition and scenario, the function:
\enumerate{
\item generates synthetic data with \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}
\item fits the model with \code{method = "MML"}
\item computes diagnostics with \code{diagnostic_mode = "both"}
\item stores legacy residual-screen metrics and strict marginal-fit metrics
\item optionally stores \code{mfrm_report()} \code{report_index} readiness signals
\item aggregates the results into \code{scenario_summary}, \code{performance_summary},
\code{report_signal_summary}, and \code{scenario_contrast}
}

The \code{"well_specified"} scenario uses the ordinary generator with no injected
extra structure. The \code{"local_dependence"} scenario adds a shared
\verb{Person x facet} random effect, centered within the selected facet levels, so
responses in the same context become correlated without changing the
facet-level mean effect contract. The \code{"latent_misspecification"} scenario
keeps the same marginal spread targets but replaces the normal person
distribution with a centered bimodal empirical support distribution, while
leaving the non-person facets on the original scale contract. The
\code{"step_structure_misspecification"} scenario uses a \code{PCM} or bounded-\code{GPCM}
generator with facet-specific threshold tables that intentionally mismatch
the fitted step contract: \code{RSM} fits receive criterion-specific thresholds,
and \code{PCM} / \code{GPCM} fits receive threshold structures indexed by the opposite
non-person facet. For bounded \code{GPCM}, the generator and fit each keep
\code{slope_facet == step_facet}; the misspecification is the generator-versus-fit
step/slope facet mismatch.

This function is intentionally screening-oriented. The strict marginal branch
remains exploratory in the current release, so the returned summaries should
be used to compare relative sensitivity across scenarios rather than to claim
calibrated inferential power. Bounded-\code{GPCM} rows add explicit
\code{gpcm_boundary} caveats and should be read as slope-aware operating
characteristics under the evaluated role-based design.
}
\examples{
\donttest{
diag_eval <- evaluate_mfrm_diagnostic_screening(
  design = list(person = 10, rater = 2, criterion = 2, assignment = 2),
  reps = 1,
  maxit = 30,
  seed = 123
)
diag_eval$scenario_summary
diag_eval$scenario_contrast
}
}
\seealso{
\code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}
}
