% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation.R
\name{evaluate_mfrm_signal_detection}
\alias{evaluate_mfrm_signal_detection}
\title{Evaluate DIF power and bias-screening behavior under known simulated signals}
\usage{
evaluate_mfrm_signal_detection(
  n_person = c(30, 50, 100),
  n_rater = c(4),
  n_criterion = c(4),
  raters_per_person = n_rater,
  design = NULL,
  reps = 10,
  group_levels = c("A", "B"),
  reference_group = NULL,
  focal_group = NULL,
  dif_level = NULL,
  dif_effect = 0.6,
  bias_rater = NULL,
  bias_criterion = NULL,
  bias_effect = -0.8,
  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,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  sim_spec = NULL,
  dif_method = c("residual", "refit"),
  dif_min_obs = 10,
  dif_p_adjust = "holm",
  dif_p_cut = 0.05,
  dif_abs_cut = 0.43,
  bias_max_iter = 2,
  bias_p_cut = 0.05,
  bias_abs_t = 2,
  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} (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{group_levels}{Group labels used for DIF simulation. The first two levels
define the default reference and focal groups.}

\item{reference_group}{Optional reference group label used when extracting the
target DIF contrast.}

\item{focal_group}{Optional focal group label used when extracting the target
DIF contrast.}

\item{dif_level}{Target criterion level for the true DIF effect. Can be an
integer index or a criterion label such as \code{"C04"}. Defaults to the last
criterion level in each design.}

\item{dif_effect}{True DIF effect size added to the focal group on the target
criterion.}

\item{bias_rater}{Target rater level for the true interaction-bias effect.
Can be an integer index or a label such as \code{"R04"}. Defaults to the last
rater level in each design.}

\item{bias_criterion}{Target criterion level for the true interaction-bias
effect. Can be an integer index or a criterion label. Defaults to the last
criterion level in each design.}

\item{bias_effect}{True interaction-bias effect added to the target
\verb{Rater x Criterion} cell.}

\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()}}. Bounded \code{GPCM} is
supported with caveats as slope-aware signal-detection sensitivity
evidence.}

\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"}. 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 \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, thresholds,
and other generator settings come from \code{sim_spec}. The target DIF and
interaction-bias signals specified in this function override any signal
tables stored in \code{sim_spec}. 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{dif_method}{Differential-functioning method passed to \code{\link[=analyze_dff]{analyze_dff()}}.}

\item{dif_min_obs}{Minimum observations per group cell for \code{\link[=analyze_dff]{analyze_dff()}}.}

\item{dif_p_adjust}{P-value adjustment method passed to \code{\link[=analyze_dff]{analyze_dff()}}.}

\item{dif_p_cut}{P-value cutoff for counting a target DIF detection.}

\item{dif_abs_cut}{Optional absolute contrast cutoff used when counting a
target DIF detection. When omitted, the effective default is \code{0.43} for
\code{dif_method = "refit"} and \code{0} (no additional magnitude cutoff) for
\code{dif_method = "residual"}.}

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

\item{bias_p_cut}{P-value cutoff for counting a target bias screen-positive result.}

\item{bias_abs_t}{Absolute t cutoff for counting a target bias screen-positive result.}

\item{seed}{Optional seed for reproducible replications.}
}
\value{
An object of class \code{mfrm_signal_detection} with:
\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}: replicate-level detection 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} screening route
is used
\item \code{settings}: signal-analysis settings
\item \code{ademp}: simulation-study metadata (aims, DGM, estimands, methods, performance measures)
\item \code{notes}: short interpretation notes
}
}
\description{
Evaluate DIF power and bias-screening behavior under known simulated signals
}
\details{
This function performs Monte Carlo design screening for two related tasks:
DIF detection via \code{\link[=analyze_dff]{analyze_dff()}} and interaction-bias screening via
\code{\link[=estimate_bias]{estimate_bias()}}.

For each design condition (combination of \code{n_person}, \code{n_rater},
\code{n_criterion}, \code{raters_per_person}), the function:
\enumerate{
\item Generates synthetic data with \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}
\item Injects one known Group \eqn{\times} Criterion DIF effect
(\code{dif_effect} logits added to the focal group on the target criterion)
\item Injects one known Rater \eqn{\times} Criterion interaction-bias
effect (\code{bias_effect} logits)
\item Fits and diagnoses the MFRM
\item Runs \code{\link[=analyze_dff]{analyze_dff()}} and \code{\link[=estimate_bias]{estimate_bias()}}
\item Records whether the injected signals were detected or screen-positive
}

Bounded-\code{GPCM} runs preserve the current package constraint
\code{slope_facet == step_facet} within the generator and fitted model. The
resulting DIF and bias rates are slope-aware screening summaries, not
formal inferential power, alpha calibration, operational scoring, or
arbitrary-facet planning evidence.

\strong{Detection criteria}:
A DIF signal is counted as "detected" when the target contrast has
\eqn{p <} \code{dif_p_cut} \strong{and}, when an absolute contrast cutoff is in
force, \eqn{|\mathrm{Contrast}| \ge} \code{dif_abs_cut}. For
\code{dif_method = "refit"}, \code{dif_abs_cut} is interpreted on the logit scale.
For \code{dif_method = "residual"}, the residual-contrast screening result is
used and the default is to rely on the significance test alone.

Bias results are different: \code{\link[=estimate_bias]{estimate_bias()}} reports \code{t} and \code{Prob.} as
screening metrics rather than formal inferential quantities. Here, a bias
cell is counted as \strong{screen-positive} only when those screening metrics are
available and satisfy

\eqn{p <} \code{bias_p_cut} \strong{and} \eqn{|t| \ge} \code{bias_abs_t}.

\strong{Power} is the proportion of replications in which the target signal
was correctly detected. For DIF this is a conventional power summary.
For bias, the primary summary is \code{BiasScreenRate}, a screening hit rate
rather than formal inferential power.

\strong{False-positive rate} is the proportion of non-target cells that were
incorrectly flagged. For DIF this is interpreted in the usual testing
sense. For bias, \code{BiasScreenFalsePositiveRate} is a screening rate and
should not be read as a calibrated inferential alpha level.

\strong{Default effect sizes}: \code{dif_effect = 0.6} logits corresponds to a
moderate criterion-linked differential-functioning effect; \code{bias_effect = -0.8}
logits represents a substantial rater-criterion interaction.  Adjust
these to match the smallest effect size of practical concern for your
application.

This is again a \strong{parametric simulation study}. The function does not
estimate a new design directly from one observed dataset. Instead, it
evaluates detection or screening behavior under user-specified design
conditions and known injected signals.

If you want to approximate a real study, choose the design grid and
simulation settings so that they reflect the empirical context of interest.
For example, you may set \code{n_person}, \code{n_rater}, \code{n_criterion},
\code{raters_per_person}, and the latent-spread arguments to values motivated by
an existing assessment program, then study how operating characteristics
change as those design settings vary.

When \code{sim_spec} is supplied, the function uses it as the explicit
data-generating mechanism for the latent spreads, thresholds, and assignment
archetype, while still injecting the requested target DIF and bias effects
for each design condition.

If that specification also stores a latent-regression population generator,
each replication carries simulated one-row-per-person background data into
the MML fit. This remains a screening-oriented Monte Carlo study; it is not
a person-level posterior prediction for one observed sample.
}
\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_signal_detection()} is a
many-facet screening helper specialized to DIF and interaction-bias use
cases; it is not a direct implementation of one published many-facet Rasch
simulation design.
\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{
sig_eval <- suppressWarnings(evaluate_mfrm_signal_detection(
  design = list(person = 8, rater = 2, criterion = 2, assignment = 1),
  reps = 1,
  maxit = 30,
  bias_max_iter = 1,
  seed = 123
))
s_sig <- summary(sig_eval)
s_sig$overview
}
}
\seealso{
\code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}, \code{\link[=analyze_dff]{analyze_dff()}}, \code{\link[=analyze_dif]{analyze_dif()}}, \code{\link[=estimate_bias]{estimate_bias()}}
}
