% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/facets_mode_api.R
\name{run_mfrm_facets}
\alias{run_mfrm_facets}
\alias{mfrmRFacets}
\title{Run a legacy-compatible estimation workflow wrapper}
\usage{
run_mfrm_facets(
  data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  keep_original = FALSE,
  model = c("RSM", "PCM"),
  method = c("JML", "JMLE", "MML"),
  step_facet = NULL,
  anchors = NULL,
  group_anchors = NULL,
  noncenter_facet = "Person",
  dummy_facets = NULL,
  positive_facets = NULL,
  quad_points = 15,
  maxit = 400,
  reltol = 1e-06,
  mml_engine = c("direct", "em", "hybrid"),
  top_n_interactions = 20L
)

mfrmRFacets(
  data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  keep_original = FALSE,
  model = c("RSM", "PCM"),
  method = c("JML", "JMLE", "MML"),
  step_facet = NULL,
  anchors = NULL,
  group_anchors = NULL,
  noncenter_facet = "Person",
  dummy_facets = NULL,
  positive_facets = NULL,
  quad_points = 15,
  maxit = 400,
  reltol = 1e-06,
  mml_engine = c("direct", "em", "hybrid"),
  top_n_interactions = 20L
)
}
\arguments{
\item{data}{A data.frame in long format.}

\item{person}{Optional person column name. If \code{NULL}, guessed from names.}

\item{facets}{Optional facet column names. If \code{NULL}, inferred from remaining
columns after person/score/weight mapping.}

\item{score}{Optional score column name. If \code{NULL}, guessed from names.}

\item{weight}{Optional weight column name.}

\item{keep_original}{Passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{model}{MFRM model (\code{"RSM"} default, or \code{"PCM"}).}

\item{method}{Estimation method (\code{"JML"} default; \code{"JMLE"} and \code{"MML"} also supported).}

\item{step_facet}{Step facet for PCM mode; passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{anchors}{Optional anchor table (data.frame).}

\item{group_anchors}{Optional group-anchor table (data.frame).}

\item{noncenter_facet}{Non-centered facet passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{dummy_facets}{Optional dummy facets fixed at zero.}

\item{positive_facets}{Optional facets with positive orientation.}

\item{quad_points}{Quadrature points for MML; passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{maxit}{Maximum optimizer iterations.}

\item{reltol}{Optimization tolerance.}

\item{mml_engine}{MML optimization engine passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. Applies
only when \code{method = "MML"}.}

\item{top_n_interactions}{Number of rows for interaction diagnostics.}
}
\value{
A list with components:
\itemize{
\item \code{fit}: \code{\link[=fit_mfrm]{fit_mfrm()}} result
\item \code{diagnostics}: \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} result
\item \code{iteration}: \code{\link[=estimation_iteration_report]{estimation_iteration_report()}} result
\item \code{fair_average}: \code{\link[=fair_average_table]{fair_average_table()}} result
\item \code{rating_scale}: \code{\link[=rating_scale_table]{rating_scale_table()}} result
\item \code{run_info}: run metadata table
\item \code{mapping}: resolved column mapping
}
}
\description{
This helper mirrors \code{mfrmRFacets.R} behavior as a package API and keeps
legacy-compatible defaults (\code{model = "RSM"}, \code{method = "JML"}), while allowing
users to choose compatible estimation options.
}
\details{
\code{run_mfrm_facets()} is intended as a one-shot workflow helper:
fit -> diagnostics -> key report tables.
Returned objects can be inspected with \code{summary()} and \code{plot()}.
}
\section{Estimation-method notes}{

\itemize{
\item \code{method = "JML"} (default): legacy-compatible joint estimation
route; the default preserves the FACETS-style output continuity
that existing one-shot scripts expect. For new analysis scripts,
prefer \code{fit_mfrm(..., method = "MML")} -- MML is the package-wide
recommended route because person parameters are integrated out
under an N(0, 1) prior and per-person posterior SEs are available.
\item \code{method = "JMLE"}: explicit JMLE label; internally equivalent to
JML route.
\item \code{method = "MML"}: marginal maximum likelihood route using
\code{quad_points}. Use \code{mml_engine = "em"} or \code{"hybrid"} only for
\code{RSM} / \code{PCM} fits when you want the staged MML alternatives.
}

\code{model = "PCM"} is supported; set \code{step_facet} when facet-specific step
structure is needed.
}

\section{Visualization}{

\itemize{
\item \code{plot(out, type = "fit")} delegates to \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}} and returns
fit-level visual bundles (e.g., Wright/pathway/CCC).
\item \code{plot(out, type = "qc")} delegates to \code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}} and returns
a QC dashboard plot object.
}
}

\section{Interpreting output}{

Start with \code{summary(out)}:
\itemize{
\item check convergence and iteration count in \code{overview}.
\item confirm resolved columns in \code{mapping}.
}

Then inspect:
\itemize{
\item \code{out$rating_scale} for category/threshold behavior.
\item \code{out$fair_average} for observed-vs-model scoring tendencies.
\item \code{out$diagnostics} for misfit/reliability/interactions.
}
}

\section{Typical workflow}{

\enumerate{
\item Run \code{run_mfrm_facets()} with explicit column mapping.
\item Check \code{summary(out)} and \code{summary(out$diagnostics)}.
\item Visualize with \code{plot(out, type = "fit")} and \code{plot(out, type = "qc")}.
\item Export selected tables for reporting (\code{out$rating_scale}, \code{out$fair_average}).
}
}

\section{Preferred route for new analyses}{

For new scripts, prefer the package-native route:
\code{\link[=fit_mfrm]{fit_mfrm()}} -> \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} -> \code{\link[=reporting_checklist]{reporting_checklist()}} ->
\code{\link[=build_apa_outputs]{build_apa_outputs()}}.
Use \code{run_mfrm_facets()} when you specifically need the legacy-compatible
one-shot wrapper.
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:12], , drop = FALSE]

# Legacy-compatible default: RSM + JML
out <- run_mfrm_facets(
  data = toy_small,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  maxit = 30
)
out$fit$summary[, c("Model", "Method", "MethodUsed")]
s <- summary(out)
s$overview[, c("Model", "Method", "Converged")]
p_fit <- plot(out, type = "fit", draw = FALSE)
p_fit$wright_map$data$plot

# Optional: MML route
if (interactive()) {
  out_mml <- run_mfrm_facets(
    data = toy_small,
    person = "Person",
    facets = c("Rater", "Criterion"),
    score = "Score",
    method = "MML",
    quad_points = 5,
    maxit = 30
  )
  out_mml$fit$summary[, c("Model", "Method", "MethodUsed")]
}
}
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=estimation_iteration_report]{estimation_iteration_report()}},
\code{\link[=fair_average_table]{fair_average_table()}}, \code{\link[=rating_scale_table]{rating_scale_table()}}, \link{mfrmr_visual_diagnostics},
\link{mfrmr_workflow_methods}, \link{mfrmr_compatibility_layer}
}
