% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mfrmr-package.R
\docType{package}
\name{mfrmr-package}
\alias{mfrmr}
\alias{mfrmr-package}
\title{mfrmr: Many-Facet Ordered-Response Modeling in R}
\description{
\code{mfrmr} provides estimation, diagnostics, and reporting utilities for
many-facet ordered-response measurement models: the Rasch-family \code{RSM} /
\code{PCM} route and the package's bounded \code{GPCM} extension where explicitly
documented.
}
\details{
Start with the following core workflow before branching into the longer
\code{GPCM}, simulation, and planning notes:
\enumerate{
\item Fit with \code{\link[=fit_mfrm]{fit_mfrm()}} using \code{method = "MML"}
\item For \code{RSM} / \code{PCM}, run \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} with
\code{diagnostic_mode = "both"}; for bounded \code{GPCM}, use the direct
diagnostic route and read \code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}}
\item Build a comprehensive first screen with \code{\link[=mfrm_results]{mfrm_results()}}
\item Read \code{summary(fit)}, \code{summary(diag)}, and \code{summary(res)} before branching
\item Use \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}} and \code{\link[=reporting_checklist]{reporting_checklist()}} as the first visual
and reporting screens
}

Recommended workflow:
\enumerate{
\item Fit model with \code{\link[=fit_mfrm]{fit_mfrm()}}
\item For \code{RSM} / \code{PCM}, compute diagnostics with
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}} and prefer \code{diagnostic_mode = "both"} when you want
legacy residual continuity plus the newer strict marginal-fit screen
\item For \code{RSM} / \code{PCM}, run residual PCA with \code{\link[=analyze_residual_pca]{analyze_residual_pca()}} if needed
\item For \code{RSM} / \code{PCM}, or bounded \code{GPCM} with the documented screening
caveat, estimate interactions with \code{\link[=estimate_bias]{estimate_bias()}}
\item For \code{RSM} / \code{PCM}, choose a downstream branch:
\code{\link[=reporting_checklist]{reporting_checklist()}} for manuscript/report preparation, or
\code{\link[=build_misfit_casebook]{build_misfit_casebook()}} / \code{\link[=build_linking_review]{build_linking_review()}} for operational
misfit or anchor/drift review. After
\code{\link[=build_misfit_casebook]{build_misfit_casebook()}}, inspect \code{casebook$group_view_index} before
moving to source-specific plots.
\item For \code{RSM} / \code{PCM}, build narrative/report outputs with
\code{\link[=build_apa_outputs]{build_apa_outputs()}} and \code{\link[=build_visual_summaries]{build_visual_summaries()}}
\item Treat bounded \code{GPCM}, prediction, and planning helpers as advanced scope
after the basic \code{RSM} / \code{PCM} route is working cleanly.
}

Guide pages:
\itemize{
\item \code{\link[=mfrmr_output_guide]{mfrmr_output_guide()}} for the compact purpose-to-helper map
\item \link{mfrmr_workflow_methods}
\item \link{mfrmr_visual_diagnostics}
\item \link{mfrmr_reports_and_tables}
\item \link{mfrmr_reporting_and_apa}
\item \link{mfrmr_linking_and_dff}
\item \link{gpcm_capability_matrix}
\item \link{mfrmr_compatibility_layer}
}

Companion vignettes:
\itemize{
\item \code{vignette("mfrmr-workflow", package = "mfrmr")}
\item \code{vignette("mfrmr-mml-and-marginal-fit", package = "mfrmr")}
\item \code{vignette("mfrmr-visual-diagnostics", package = "mfrmr")}
\item \code{vignette("mfrmr-reporting-and-apa", package = "mfrmr")}
\item \code{vignette("mfrmr-linking-and-dff", package = "mfrmr")}
}

A two-page landscape cheatsheet of the public API ships at
\code{system.file("cheatsheet", "mfrmr-cheatsheet.pdf", package = "mfrmr")}
(pre-rendered) and \code{system.file("cheatsheet", "mfrmr-cheatsheet.Rmd", package = "mfrmr")} (source). Open the PDF directly for a printable
reference card, or knit the source with \code{rmarkdown::render()} when
you want a customised version.
}
\section{First 5-minute route}{

Use this order before exploring the broader feature surface:
\enumerate{
\item \code{\link[=fit_mfrm]{fit_mfrm()}} with \code{method = "MML"}
\item \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} with \code{diagnostic_mode = "both"} for \code{RSM} / \code{PCM};
for bounded \code{GPCM}, keep diagnostics on the direct exploratory route
\item \code{\link[=mfrm_results]{mfrm_results()}} for a FACETS-style first screen
\item \code{summary(fit)}, \code{summary(diag)}, and \code{summary(res)}
\item \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}} for first-pass triage
\item Choose the next branch:
\code{\link[=reporting_checklist]{reporting_checklist()}} for reporting,
\code{\link[=build_weighting_review]{build_weighting_review()}} for Rasch-versus-\code{GPCM} weighting review,
\code{\link[=build_misfit_casebook]{build_misfit_casebook()}} for operational case review, or
\code{\link[=build_linking_review]{build_linking_review()}} for operational linking review (\code{RSM} / \code{PCM})
or caveated bounded-\code{GPCM} linking synthesis
}
}

\section{Advanced scope}{

After the basic route above:
\itemize{
\item the package now includes a first-version latent-regression \code{MML} branch
for ordered-response \code{RSM} / \code{PCM} models with a one-dimensional
conditional-normal population model and explicit one-row-per-person
covariates expanded through \code{stats::model.matrix()}
\item bounded \code{GPCM} support is summarized by \code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}}
\item bounded \code{GPCM} supports the core fit/summary/scoring/information
path, direct Wright/pathway/CCC plots, residual-PCA follow-up, and the
residual-based diagnostics tables/plots as exploratory tools
\item posterior-predictive computation, \code{MCMC} engines, and Docker-based
advanced runtimes are future extensions rather than requirements for the
current bounded \code{GPCM} route
\item direct \code{GPCM} data generation through \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}},
\code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}}, and \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}} is available when
the specification carries both thresholds and slopes
\item slope-aware \code{\link[=fair_average_table]{fair_average_table()}} and \code{\link[=estimate_bias]{estimate_bias()}} are available for
bounded \code{GPCM} with explicit caveats; \code{\link[=build_apa_outputs]{build_apa_outputs()}},
\code{\link[=build_visual_summaries]{build_visual_summaries()}}, \code{\link[=run_qc_pipeline]{run_qc_pipeline()}},
\code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}, \code{\link[=build_mfrm_replay_script]{build_mfrm_replay_script()}}, and
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} are available as caveated partial reporting/export
surfaces; score-side FACETS compatibility and broader planning semantics
remain validated for \code{RSM} / \code{PCM}
\item \code{predict_mfrm_population()} remains a scenario-level forecast helper and
should not be described as the latent-regression estimator itself
\item the current simulation/planning layer remains role-based for two
non-person facets rather than fully arbitrary-facet planning, with boundaries
exposed through planner metadata such as \code{planning_scope},
\code{planning_constraints}, and \code{planning_schema}
\item latent-class mixture models and response-time / careless-rating
adjustment are not estimated by mfrmr; use residual, person-fit,
local-dependence, and rater-drift diagnostics as screening layers rather
than as mixture-model substitutes
}
}

\section{Equal weighting versus bounded GPCM}{

The package's operational reference route is the Rasch-family
\code{RSM} / \code{PCM} branch. That route enforces fixed discrimination and therefore
preserves an equal-weighting scoring interpretation across observed ratings.

Bounded \code{GPCM} is supported because some users want a slope-aware model-
comparison or sensitivity layer inside the same many-facet workflow. However,
the package does not treat bounded \code{GPCM} as a universal replacement for the
Rasch-family route. A better fit under \code{GPCM} should be read as evidence
about discrimination-based reweighting, not as an automatic reason to
discard the equal-weighting model.

Observation weights are a different concept again. Optional \code{Weight}
columns change how observed rating events enter estimation and summaries, but
they do not create a free-form facet-weighting scheme and do not alter the
fixed-discrimination meaning of \code{RSM} / \code{PCM}.

Public entry map:
\itemize{
\item First-screen results: \code{\link[=mfrm_results]{mfrm_results()}}, \code{summary(res)$next_actions},
and \code{mfrmr_output_guide("entry")}
\item Interactive exploration: \code{\link[=mfrm_results_interactive]{mfrm_results_interactive()}} only when prompts
are explicitly wanted at the console
}

Function families:
\itemize{
\item Model fitting: \code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=summary.mfrm_fit]{summary.mfrm_fit()}}, \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}}
\item Legacy-compatible workflow wrapper: \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}, \code{\link[=mfrmRFacets]{mfrmRFacets()}}
\item Diagnostics: \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{summary(diag)},
\code{\link[=analyze_residual_pca]{analyze_residual_pca()}}, \code{\link[=plot_residual_pca]{plot_residual_pca()}}
\item Bias and interaction: \code{\link[=estimate_bias]{estimate_bias()}}, \code{\link[=estimate_all_bias]{estimate_all_bias()}},
\code{summary(bias)}, \code{\link[=bias_interaction_report]{bias_interaction_report()}}, \code{\link[=plot_bias_interaction]{plot_bias_interaction()}}
\item Differential functioning: \code{\link[=analyze_dff]{analyze_dff()}}, \code{\link[=analyze_dif]{analyze_dif()}},
\code{\link[=dif_interaction_table]{dif_interaction_table()}}, \code{\link[=plot_dif_heatmap]{plot_dif_heatmap()}}, \code{\link[=dif_report]{dif_report()}}
\item Design simulation: \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}}, \code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}},
\code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, \code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}},
\code{\link[=assess_mfrm_recovery]{assess_mfrm_recovery()}}, \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}},
\code{\link[=evaluate_mfrm_signal_detection]{evaluate_mfrm_signal_detection()}}, \code{\link[=predict_mfrm_population]{predict_mfrm_population()}},
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}}, \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}} (including
fit-derived empirical / resampled / skeleton-based simulation
specifications; fixed-calibration unit scoring supports \code{MML} fits
directly, latent-regression \code{MML} fits through the fitted population
model when scored units also provide one-row-per-person background data,
and \code{JML} fits through a post hoc reference-prior EAP layer;
fit-derived simulation specifications also support direct bounded
\code{GPCM} data generation, recovery checks, role-based design evaluation,
population forecasting, diagnostic-screening, and signal-detection
helpers with documented caveats; curve reports, graph-only exports,
fair-average tables, and bias screening are also available for bounded
\code{GPCM} with documented caveats)
\item Reporting: \code{\link[=build_apa_outputs]{build_apa_outputs()}}, \code{\link[=build_visual_summaries]{build_visual_summaries()}},
\code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=apa_table]{apa_table()}} for the full \code{RSM} / \code{PCM} route;
bounded \code{GPCM} currently stays on the checklist / direct-table / direct-
plot / summary-appendix side instead of the narrative/QC layer
\item Weighting review: \code{\link[=compare_mfrm]{compare_mfrm()}}, \code{\link[=build_weighting_review]{build_weighting_review()}},
\code{\link[=build_model_choice_review]{build_model_choice_review()}}, \code{\link[=compute_information]{compute_information()}}, \code{\link[=plot_information]{plot_information()}}
\item Case review: \code{\link[=build_misfit_casebook]{build_misfit_casebook()}}, \code{\link[=plot_unexpected]{plot_unexpected()}},
\code{\link[=plot_displacement]{plot_displacement()}}, \code{\link[=plot_marginal_fit]{plot_marginal_fit()}}, \code{\link[=plot_marginal_pairwise]{plot_marginal_pairwise()}}
\item Linking and scale maintenance: \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}},
\code{\link[=detect_anchor_drift]{detect_anchor_drift()}}, \code{\link[=build_equating_chain]{build_equating_chain()}},
\code{\link[=build_linking_review]{build_linking_review()}}, \code{\link[=plot_anchor_drift]{plot_anchor_drift()}}
\item Dashboards: \code{\link[=facet_quality_dashboard]{facet_quality_dashboard()}}, \code{\link[=plot_facet_quality_dashboard]{plot_facet_quality_dashboard()}}
\item Export / reproducibility: \code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}, \code{\link[=build_mfrm_replay_script]{build_mfrm_replay_script()}},
\code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}}, \code{\link[=normalize_conquest_overlap_files]{normalize_conquest_overlap_files()}},
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}},
\code{\link[=review_conquest_overlap]{review_conquest_overlap()}},
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} for the diagnostics-compatible Rasch-family route;
bounded \code{GPCM} remains outside the current fit-based
manifest/replay/bundle layer but can use \code{\link[=export_summary_appendix]{export_summary_appendix()}} for
documented direct outputs
\item Equivalence: \code{\link[=analyze_facet_equivalence]{analyze_facet_equivalence()}}, \code{\link[=plot_facet_equivalence]{plot_facet_equivalence()}}
\item Data and anchors: \code{\link[=describe_mfrm_data]{describe_mfrm_data()}}, \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}},
\code{\link[=make_anchor_table]{make_anchor_table()}}, \code{\link[=load_mfrmr_data]{load_mfrmr_data()}}
}

Data interface:
\itemize{
\item Input analysis data is long format (one row per observed rating).
\item Required columns are one person column, one ordered score column, and one
or more non-person facet columns named in \code{facets = c(...)}.
\item Score values should be ordered integer categories. Binary \code{0/1} or \code{1/2}
input is supported as the two-category Rasch-family special case; by
contrast, fractional score values should be recoded before fitting rather
than relying on automatic coercion.
\item If \code{keep_original = FALSE}, unused intermediate categories are collapsed
to a contiguous internal scale and the mapping is stored in
\code{fit$prep$score_map}.
\item If the intended scale has unused boundary categories, such as a 1-5 scale
with only 2-5 observed, set \verb{rating_min = 1, rating_max = 5} so the
zero-count boundary category remains in the fitted support. If unused
intermediate categories should also remain in the original scale, set
\code{keep_original = TRUE}.
\item \code{summary(describe_mfrm_data(...))} reports retained zero-count categories
in \code{Notes}, printed \code{Caveats}, and \verb{$caveats}; \code{summary(fit)} carries full
structured rows into printed \code{Caveats} and \verb{$caveats}, with \verb{Key warnings}
as a short triage subset. Summary-table exports route those rows through
\code{score_category_caveats} or \code{analysis_caveats}. Treat adjacent thresholds
as weakly identified when an intermediate category is unobserved.
\item Optional columns such as \code{Subset}, \code{Weight}, and \code{Group} support linking,
weighted analysis, and fairness-focused follow-up workflows.
\item Packaged simulation data is available via \code{\link[=load_mfrmr_data]{load_mfrmr_data()}} or \code{data()}.
}
}

\section{Interpreting output}{

Core object classes are:
\itemize{
\item \code{mfrm_fit}: fitted model parameters and metadata.
\item \code{mfrm_diagnostics}: fit, facet-level reliability, and flag diagnostics,
plus inter-rater agreement when one facet is treated as a rater facet.
\item \code{mfrm_bias}: interaction bias estimates.
\item \code{mfrm_dff} / \code{mfrm_dif}: differential-functioning contrasts and screening summaries.
\item \code{mfrm_population_prediction}: scenario-level forecast summaries for one
future design.
\item \code{mfrm_unit_prediction}: posterior summaries for future or partially
observed persons under the fitted scoring basis.
\item \code{mfrm_plausible_values}: posterior draws for future or partially observed
persons under the fitted scoring basis.
\item \code{mfrm_bundle} families: summary/report bundles and draw-free plot data.
}
}

\section{Typical workflow}{

\enumerate{
\item Prepare long-format data.
\item Fit with \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item For \code{RSM} / \code{PCM}, diagnose with \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} and prefer
\code{diagnostic_mode = "both"} for final \code{MML} runs.
\item For \code{RSM} / \code{PCM}, run \code{\link[=analyze_dff]{analyze_dff()}} or \code{\link[=estimate_bias]{estimate_bias()}} when
fairness or interaction questions matter; bounded \code{GPCM} also supports
\code{\link[=estimate_bias]{estimate_bias()}} as a conditional screening review.
\item For \code{RSM} / \code{PCM}, report with \code{\link[=build_apa_outputs]{build_apa_outputs()}} and
\code{\link[=build_visual_summaries]{build_visual_summaries()}}.
\item For design planning, move to \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}},
\code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}, \code{\link[=mfrm_generalizability]{mfrm_generalizability()}}, \code{\link[=mfrm_d_study]{mfrm_d_study()}},
and \code{\link[=predict_mfrm_population]{predict_mfrm_population()}}. Bounded
\code{GPCM} also supports direct simulation via
\code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}} / \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}, but not the broader
planning helpers. Those helpers assume two non-person facet roles
even though the estimation core supports arbitrary facet counts. Treat
\code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}} as Monte Carlo design evaluation, and use
\code{\link[=mfrm_d_study]{mfrm_d_study()}} for analytic G/Phi design projections.
\code{predict_mfrm_population()} remains the scenario-level forecast helper,
not the latent-regression estimator.
\item For future-unit scoring, retain an \code{MML} calibration when you want the
fitted marginal model directly, use an active latent-regression \code{MML}
fit when scored units also provide one-row-per-person background data, or
use a \code{JML} calibration when a post hoc fixed-calibration EAP layer is
acceptable; then score with
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}} or \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}}.
\item For bounded \code{GPCM}, use \code{\link[=summary.mfrm_fit]{summary.mfrm_fit()}},
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=analyze_residual_pca]{analyze_residual_pca()}},
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}}, \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}},
\code{\link[=compute_information]{compute_information()}}, \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}, \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}},
\code{\link[=category_structure_report]{category_structure_report()}}, \code{\link[=category_curves_report]{category_curves_report()}},
graph-only \code{\link[=facets_output_file_bundle]{facets_output_file_bundle()}}, direct simulation-spec
generation/data generation, recovery checks, \code{\link[=fair_average_table]{fair_average_table()}},
\code{\link[=estimate_bias]{estimate_bias()}}, and the residual-based table helpers with their
documented caveats. Caveated APA/QC/export bundles and exploratory
linking review plus role-based design evaluation, population
forecasting, diagnostic-screening, and signal-detection helpers are
available, while full score-side FACETS review, posterior-predictive
checks, and heavy backends remain outside the bounded \code{GPCM} route. Use
\code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}} as the formal boundary statement.
}
}

\section{Model formulation}{

The Rasch-family branch used by \code{RSM} and \code{PCM} extends the basic Rasch
model by incorporating multiple measurement facets into a single additive
linear predictor on the log-odds scale.

\strong{RSM/PCM adjacent-category equation}

For an observation where person \eqn{n} with ability \eqn{\theta_n} is
rated by rater \eqn{j} with severity \eqn{\delta_j} on criterion \eqn{i}
with difficulty \eqn{\beta_i}, the probability of observing category
\eqn{k} (out of \eqn{K} ordered categories) is:

\deqn{P(X_{nij} = k \mid \theta_n, \delta_j, \beta_i, \tau) =
  \frac{\exp\bigl[\sum_{s=1}^{k}(\theta_n - \delta_j - \beta_i - \tau_s)\bigr]}
       {\sum_{c=0}^{K}\exp\bigl[\sum_{s=1}^{c}(\theta_n - \delta_j - \beta_i - \tau_s)\bigr]}}

where \eqn{\tau_s} are the Rasch-Andrich threshold (step) parameters in the
\code{RSM} reference case and
\eqn{\sum_{s=1}^{0}(\cdot) \equiv 0} by convention.  Additional facets
enter as additive terms in the linear predictor
\eqn{\eta = \theta_n - \delta_j - \beta_i - \ldots}.

This additive predictor generalises to any number of facets; the
\code{facets} argument to \code{\link[=fit_mfrm]{fit_mfrm()}} accepts an arbitrary-length
character vector.

\strong{Rating Scale Model (RSM)}

Under the RSM (Andrich, 1978), all levels of the step facet share a
single set of threshold parameters \eqn{\tau_1, \ldots, \tau_K}.

\strong{Partial Credit Model (PCM)}

Under the PCM (Masters, 1982), each level of the designated \code{step_facet}
has its own threshold vector on the package's common observed score scale.
In the current implementation, threshold locations may vary by step-facet
level, but the fitted score range is defined by one global category
set taken from the observed data.

\strong{Bounded Generalized Partial Credit Model (GPCM)}

Under bounded \code{GPCM} (Muraki, 1992), the same adjacent-category partial-credit
kernel is multiplied by a positive slope \eqn{\alpha_g} for the designated
slope-facet level \eqn{g}:

\deqn{\ln\frac{P(X_{nij} = k)}{P(X_{nij} = k-1)} =
  \alpha_g(\theta_n - \delta_j - \beta_i - \tau_{gk}).}

The current implementation requires \code{slope_facet == step_facet} and
identifies slopes on the log scale with geometric mean 1. This makes bounded
\code{GPCM} a slope-aware sensitivity/extension route, not a replacement for the
equal-weighting \code{RSM}/\code{PCM} interpretation.

\strong{Ordered-response scope}

The implemented response-model scope is ordered categorical only.
Binary responses are the \eqn{K = 1} special case of the same formulation,
so they are handled through the ordinary ordered-score interface. This means
\code{mfrmr} supports ordered binary and ordered polytomous data under \code{RSM} and
\code{PCM}, plus a narrow bounded \code{GPCM} branch with one designated
\code{slope_facet} that currently must equal \code{step_facet}. Unordered
nominal/multinomial response models are not yet implemented.
}

\section{Estimation methods}{

\strong{Marginal Maximum Likelihood (MML)}

MML integrates over the person ability distribution using Gauss-Hermite
quadrature, in the broader marginal-likelihood framework introduced by
Bock & Aitkin (1981) for IRT:

\deqn{L = \prod_{n} \int P(\mathbf{X}_n \mid \theta, \boldsymbol{\delta})
  \, \phi(\theta) \, d\theta
  \approx \prod_{n} \sum_{q=1}^{Q} w_q \,
  P(\mathbf{X}_n \mid \theta_q, \boldsymbol{\delta})}

where \eqn{\phi(\theta)} is the assumed normal prior and
\eqn{(\theta_q, w_q)} are quadrature nodes and weights.  Person
estimates are obtained post-hoc via Expected A Posteriori (EAP):

\deqn{\hat{\theta}_n^{\mathrm{EAP}} =
  \frac{\sum_q \theta_q \, w_q \, L(\mathbf{X}_n \mid \theta_q)}
       {\sum_q w_q \, L(\mathbf{X}_n \mid \theta_q)}}

MML avoids the incidental-parameter problem and is generally preferred
for smaller samples.

Note: Bock & Aitkin (1981) is the canonical citation for the
Gauss-Hermite-quadrature MML \emph{framework}. The default mfrmr engine
(\code{mml_engine = "direct"}) optimises this marginal log-likelihood by
direct gradient methods (BFGS / L-BFGS-B), not by Bock & Aitkin's
signature EM algorithm. The \code{"em"} and \code{"hybrid"} engines do follow
the EM template but use a BFGS M-step rather than B&A's probit IRLS,
because the target is the polytomous Rasch family rather than B&A's
2PL probit model.

\strong{Joint Maximum Likelihood (JML)}

JML estimates all person and facet parameters simultaneously as fixed
effects by maximising the joint log-likelihood
\eqn{\ell(\boldsymbol{\theta}, \boldsymbol{\delta} \mid \mathbf{X})}
directly.  It does not assume a parametric person distribution, which
can be advantageous when the population shape is strongly non-normal,
but parameter estimates are known to be biased when the number of
persons is small relative to the number of items (Neyman & Scott, 1948).
The package still accepts \code{"JMLE"} as a backward-compatible alias, but
user-facing summaries and documentation use \code{"JML"} as the public label.

See \code{\link[=fit_mfrm]{fit_mfrm()}} for practical guidance on choosing between the two.
}

\section{Strict marginal diagnostics}{

For \code{RSM} / \code{PCM}, \code{diagnose_mfrm(..., diagnostic_mode = "both")}
returns two complementary targets: the \code{legacy} residual / EAP
diagnostics and a \code{marginal_fit} layer whose expected counts and
pairwise summaries are integrated over the posterior quadrature
bundle rather than plugged in at the EAP point. The screen is
structured as limited-information evidence (Orlando & Thissen,
2000; Haberman & Sinharay, 2013; Sinharay & Monroe, 2025), not as
an omnibus accept / reject test, and it complements rather than
replaces separation / reliability and inter-rater agreement
summaries. The full derivation, with notation and pairwise
local-dependence events, lives in
\code{vignette("mfrmr-mml-and-marginal-fit", package = "mfrmr")}.
}

\section{Statistical background}{

Key statistics reported throughout the package:

\strong{Infit (Information-Weighted Mean Square)}

Weighted average of squared standardized residuals, where weights are the
model-based variance of each observation:

\deqn{\mathrm{Infit}_j = \frac{\sum_i Z_{ij}^2 \, \mathrm{Var}_i \, w_i}
                              {\sum_i \mathrm{Var}_i \, w_i}}

Expected value is 1.0 under model fit.  Values below 0.5 suggest overfit
(Mead-style responses); values above 1.5 suggest underfit (noise or
misfit).  Infit is most sensitive to unexpected patterns among on-target
observations (Wright & Masters, 1982).

Note: The 0.5--1.5 range is the general "productive for measurement"
band given by Linacre (2002, \emph{RMT} 16(2), 878). Context-specific bands
come from Wright & Linacre (1994, \emph{RMT} 8(3), 370): 0.8--1.2 for
high-stakes MCQ, 0.7--1.3 for run-of-the-mill MCQ, 0.6--1.4 for
rating-scale surveys, 0.5--1.7 for clinical observation, and 0.4--1.2
for judged performance. See also Bond & Fox (2015) for textbook
summaries of these conventions.

\strong{Outfit (Unweighted Mean Square)}

Simple average of squared standardized residuals:

\deqn{\mathrm{Outfit}_j = \frac{\sum_i Z_{ij}^2 \, w_i}{\sum_i w_i}}

Same expected value and flagging thresholds as Infit, but more sensitive
to extreme off-target outliers (e.g., a high-ability person scoring the
lowest category).

\strong{ZSTD (Standardized Fit Statistic)}

Wilson-Hilferty (1931) cube-root transformation that converts the
mean-square chi-square ratio to an approximate standard normal deviate:

\deqn{\mathrm{ZSTD} = \frac{\mathrm{MnSq}^{1/3} - (1 - 2/(9\,\mathit{df}))}
                           {\sqrt{2/(9\,\mathit{df})}}}

Values near 0 indicate expected fit; \eqn{|\mathrm{ZSTD}| > 2} flags
potential misfit at the 5\\% level, and \eqn{|\mathrm{ZSTD}| > 3} at the
1\\% level (Wright & Linacre, 1994; see also Wilson & Hilferty, 1931).
ZSTD is reported alongside every Infit and Outfit value. ZSTD is
withheld (\code{NA}) when the applicable df falls below 1, where the
Wilson-Hilferty transformation is numerically unstable; FACETS/Winsteps
under \code{WHEXACT} can continue with a linear approximation on such cells.

\strong{Residual basis under MML vs JMLE engines}

For \code{method = "MML"} fits, the standardized residuals behind Infit,
Outfit, and ZSTD are evaluated at EAP person measures, which are
shrunken toward the population mean. JMLE engines such as FACETS
evaluate the same formulas at unshrunken JMLE estimates, so MnSq and
ZSTD values are not numerically interchangeable across the two residual
bases, most visibly for extreme-scoring persons. Use \code{method = "JML"}
when an external FACETS fit comparison requires a JMLE-style residual
basis, and see \code{\link[=facets_fit_df_guide]{facets_fit_df_guide()}} for the separate
standardization-side df/ZSTD conventions.

\strong{PTMEA (Point-Measure Correlation)}

Pearson correlation between observed scores and estimated person measures
within each facet level.  Positive values indicate that scoring aligns
with the latent trait dimension; negative values suggest reversed
orientation or scoring errors.

\strong{Separation}

Package-reported separation is the ratio of adjusted true standard deviation
to root-mean-square measurement error:

\deqn{G = \frac{\mathrm{SD}_{\mathrm{adj}}}{\mathrm{RMSE}}}

where \eqn{\mathrm{SD}_{\mathrm{adj}} =
\sqrt{\mathrm{ObservedVariance} - \mathrm{ErrorVariance}}}. Higher values
indicate the facet discriminates more statistically distinct levels along the
measured variable. In \code{mfrmr}, \code{Separation} is the model-based value and
\code{RealSeparation} provides a more conservative companion based on \code{RealSE}.

\strong{Reliability}

\deqn{R = \frac{G^2}{1 + G^2}}

Analogous to Cronbach's alpha or KR-20 for the reproducibility of element
ordering. In \code{mfrmr}, \code{Reliability} is the model-based value and
\code{RealReliability} gives the conservative companion based on \code{RealSE}. For
\code{MML}, these are anchored to observed-information \code{ModelSE}
estimates for non-person facets; \code{JML} keeps them as exploratory summaries.

For the person facet under \code{MML}, the same \eqn{G} and \eqn{R} formulas
are applied to EAP person measures with posterior SDs in the error slot.
EAP measures are shrunken, so their observed variance is already deflated
(approximately the true variance times the reliability), and subtracting
the mean posterior variance deflates it again. The reported MML person
separation/reliability is therefore a conservative summary: it is
systematically lower than the IRT empirical-reliability convention
\eqn{\mathrm{Var}(\mathrm{EAP}) / (\mathrm{Var}(\mathrm{EAP}) +
\overline{\mathrm{PSD}^2})} and is not numerically comparable to
JMLE-based person separation reliability from FACETS. The gap is small
when measurement is precise and grows as precision drops. Person rows can
still carry the model-based precision tier because posterior SDs are
model-based quantities; that tier describes the SE source, not FACETS
comparability. Use \code{method = "JML"} when a FACETS-style person separation
table is required, and treat MML person rows as conservative summaries.

This is a Rasch/FACETS-style separation reliability on the fitted logit
scale, not an intra-class correlation. Use \code{\link[=compute_facet_icc]{compute_facet_icc()}} only when
you want the complementary random-effects variance-share view on the
observed-score scale; for non-person facets, large ICC values indicate
systematic facet variance rather than desirable measurement reliability.

\strong{Strata}

Number of statistically distinguishable groups of elements:

\deqn{H = \frac{4G + 1}{3}}

Three or more strata are commonly used as a practical target
(Wright & Masters, 1982), but in this package the estimate inherits the
same approximation limits as the separation index.
}

\section{Key references}{

\itemize{
\item Andrich, D. (1978). A rating formulation for ordered response
categories. \emph{Psychometrika}, 43, 561--573.
\item Bond, T. G., & Fox, C. M. (2015). \emph{Applying the Rasch model} (3rd
ed.). Routledge.
\item Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood estimation
of item parameters: Application of an EM algorithm. \emph{Psychometrika}, 46,
443--459.
\item Burnham, K. P., & Anderson, D. R. (2002). \emph{Model selection and
multimodel inference: A practical information-theoretic approach}
(2nd ed.). Springer. (AIC / BIC weights and Delta-IC bands used
by \code{compare_mfrm()}.)
\item Drasgow, F., Levine, M. V., & Williams, E. A. (1985).
Appropriateness measurement with polychotomous item response
models and standardized indices. \emph{British Journal of Mathematical
and Statistical Psychology}, 38(1), 67--86. (Source for the \code{lz}
person-fit statistic implemented in \code{compute_person_fit_indices()}.)
\item Haberman, S. J., & Sinharay, S. (2013). Generalized residuals for general
models for contingency tables with application to item response theory.
\emph{Journal of the American Statistical Association}, 108, 1435--1444.
\item Eckes, T. (2005). Examining rater effects in TestDaF writing and speaking
performance assessments: A many-facet Rasch analysis. \emph{Language Assessment
Quarterly}, 2, 197--221.
\item Muraki, E. (1992). A generalized partial credit model: Application of
an EM algorithm. \emph{Applied Psychological Measurement}, 16(2),
159--176. (Source for the bounded \code{GPCM} extension used in
\code{fit_mfrm(model = "GPCM")}, \code{fair_average_table()}, and
\code{estimate_bias()}.)
\item Muraki, E. (1993). Information functions of the generalized partial
credit model. \emph{Applied Psychological Measurement}, 17(4),
351--363. (Companion paper to Muraki 1992 that derives the GPCM
item information identity \eqn{I_j(\theta) = D^2 a_j^2
  \mathrm{Var}(T \mid \theta)} via Samejima's (1974) polytomous
information formula. This is the canonical reference for
\code{compute_information()} under bounded \code{GPCM}.)
\item Samejima, F. (1974). Normal ogive model on the continuous response
level in the multidimensional latent space. \emph{Psychometrika}, 39,
111--121. (General polytomous information formula that Muraki
1993 specializes to the GPCM.)
\item Snijders, T. A. B. (2001). Asymptotic null distribution of person
fit statistics with estimated person parameter. \emph{Psychometrika},
66(3), 331--342. (Source for the \code{lz_star} correction in
\code{compute_person_fit_indices()} when person estimates come from the
JML/fixed-effect route. MML/EAP person scores are left uncorrected
because EAP does not satisfy the Snijders estimating-equation setup.)
\item Linacre, J. M. (1989). \emph{Many-facet Rasch measurement}. MESA Press.
\item Linacre, J. M. (2002). What do Infit and Outfit, mean-square and
standardized mean? \emph{Rasch Measurement Transactions}, 16(2), 878.
\item Masters, G. N. (1982). A Rasch model for partial credit scoring.
\emph{Psychometrika}, 47, 149--174.
\item Orlando, M., & Thissen, D. (2000). Likelihood-based item-fit indices for
dichotomous item response theory models. \emph{Applied Psychological
Measurement}, 24, 50--64.
\item Orlando, M., & Thissen, D. (2003). Further investigation of the
performance of S-X2: An item fit index for use with dichotomous item
response theory models. \emph{Applied Psychological Measurement}, 27, 289--298.
\item Sinharay, S., Johnson, M. S., & Stern, H. S. (2006). Posterior predictive
assessment of item response theory models. \emph{Applied Psychological
Measurement}, 30, 298--321.
\item Sinharay, S., & Monroe, S. (2025). Assessment of fit of item response
theory models: A critical review of the status quo and some future
directions. \emph{British Journal of Mathematical and Statistical Psychology},
78, 711--733.
\item Wright, B. D., & Masters, G. N. (1982). \emph{Rating scale analysis}.
MESA Press.
\item Wright, B. D., & Linacre, J. M. (1994). Reasonable mean-square fit
values. \emph{Rasch Measurement Transactions}, 8(3), 370.
\item Wilson, E. B., & Hilferty, M. M. (1931). The distribution of
chi-square. \emph{Proceedings of the National Academy of Sciences of the
United States of America}, 17(12), 684-688.
}
}

\section{Model selection}{

\strong{RSM vs PCM}

The Rating Scale Model (RSM; Andrich, 1978) assumes all levels of the
step facet share identical threshold parameters.  The Partial Credit
Model (PCM; Masters, 1982) allows each level of the \code{step_facet} to have
its own set of thresholds on the package's shared observed score scale.
Use RSM when the rating rubric is identical across all items/criteria;
use PCM when category boundaries are expected to vary by item or criterion.
In the current implementation, PCM assumes one common observed score
support across the fitted data, so it should not be described as a fully
mixed-category model with arbitrary item-specific category counts.

\strong{MML vs JML}

Marginal Maximum Likelihood (MML) integrates over the person ability
distribution using Gauss-Hermite quadrature and does not directly estimate
person parameters; person estimates are computed post-hoc via Expected A
Posteriori (EAP).  Joint Maximum Likelihood (JML) estimates all person
and facet parameters simultaneously as fixed effects; \code{"JMLE"} remains a
backward-compatible alias.

MML is generally preferred for smaller samples because it avoids the
incidental-parameter problem of JML.  JML does not assume a normal person
distribution and can be lighter computationally in some settings, which
may be an advantage when the population shape is strongly non-normal.

See \code{\link[=fit_mfrm]{fit_mfrm()}} for usage.

\strong{Fixed-calibration scoring after fitting}

\code{\link[=predict_mfrm_units]{predict_mfrm_units()}} and \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}} score future or
partially observed persons on a quadrature grid under the fitted scoring
basis. For ordinary \code{MML} fits, these summaries inherit the fitted marginal
calibration directly. For latent-regression \code{MML} fits, they use the fitted
one-dimensional conditional normal population model and therefore require
one-row-per-person background data for the scored units when the fitted
population model includes covariates. Intercept-only latent-regression fits
(\code{population_formula = ~ 1}) can reconstruct that minimal person table from
the scored person IDs. For \code{JML} fits, \code{mfrmr} uses the fitted facet and
step parameters together with a standard normal reference prior introduced
only for the post hoc scoring layer. This is useful for practical
fixed-scale scoring, but it should still be described as a limited
approximation rather than as full ConQuest-style population modeling.

\strong{Current ConQuest overlap}

The package now includes a first-version latent-regression \code{MML} branch, but
the overlap with ConQuest should still be described conservatively. The
documented overlap is:
ordered-response \code{RSM} / \code{PCM}, one latent dimension, a conditional-normal
person population model, and person covariates supplied through an explicit
one-row-per-person table and expanded through the package-built model
matrix. Categorical person covariates carry fitted levels and contrasts into
scoring. This is a scoped overlap, not a claim of broad ConQuest numerical
equivalence for arbitrary imported design matrices, multidimensional models,
imported design specifications, or the full plausible-values workflow.
}

\examples{
mfrm_threshold_profiles()
list_mfrmr_data()

\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(
  toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  model = "RSM",
  quad_points = 7
)
diag <- diagnose_mfrm(fit, diagnostic_mode = "both", residual_pca = "none")
summary(diag)
}

}
\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/Ryuya-dot-com/mfrmr}
  \item Report bugs at \url{https://github.com/Ryuya-dot-com/mfrmr/issues}
}

}
\author{
\strong{Maintainer}: Ryuya Komuro \email{ryuya.komuro.c4@tohoku.ac.jp} (\href{https://orcid.org/0000-0001-9205-0926}{ORCID}) [copyright holder]

Authors:
\itemize{
  \item Ryuya Komuro \email{ryuya.komuro.c4@tohoku.ac.jp} (\href{https://orcid.org/0000-0001-9205-0926}{ORCID}) [copyright holder]
}

}
