% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{build_mfrm_replay_script}
\alias{build_mfrm_replay_script}
\title{Build a package-native replay script for an MFRM analysis}
\usage{
build_mfrm_replay_script(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  population_prediction = NULL,
  unit_prediction = NULL,
  plausible_values = NULL,
  data_file = "your_data.csv",
  fit_person_data_file = NULL,
  script_mode = c("auto", "fit", "facets"),
  include_bundle = FALSE,
  bundle_dir = "analysis_bundle",
  bundle_prefix = "mfrmr_replay"
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. When \code{NULL},
diagnostics are reused from \code{run_mfrm_facets()} when available, otherwise
recomputed.}

\item{bias_results}{Optional output from \code{\link[=estimate_bias]{estimate_bias()}} or a named list of
bias bundles. When supplied, the generated script includes package-native
bias estimation calls.}

\item{population_prediction}{Optional output from
\code{\link[=predict_mfrm_population]{predict_mfrm_population()}} to recreate in the generated script.}

\item{unit_prediction}{Optional output from \code{\link[=predict_mfrm_units]{predict_mfrm_units()}} to
recreate in the generated script.}

\item{plausible_values}{Optional output from
\code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}} to recreate in the generated script.}

\item{data_file}{Path to the analysis data file used in the generated script.}

\item{fit_person_data_file}{Optional CSV filename to read for the fit-level
latent-regression replay person table. When \code{NULL}, the replay script
embeds that table inline. \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} uses this to keep replay
scripts portable while avoiding large inline literals.}

\item{script_mode}{One of \code{"auto"}, \code{"fit"}, or \code{"facets"}. \code{"auto"} uses
\code{run_mfrm_facets()} when the input object came from that workflow.}

\item{include_bundle}{If \code{TRUE}, append an \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} call to the
generated script.}

\item{bundle_dir}{Output directory used when \code{include_bundle = TRUE}.}

\item{bundle_prefix}{Prefix used by the generated bundle exporter call.}
}
\value{
A named list with class \code{mfrm_replay_script}.
}
\description{
Build a package-native replay script for an MFRM analysis
}
\details{
This helper mirrors the Streamlit app's reproducible-download idea, but uses
\code{mfrmr}'s installed API rather than embedding a separate estimation engine.
The generated script assumes the user has the package installed and provides
a data file at \code{data_file}.

Anchor and group-anchor constraints are embedded directly from the fitted
object's stored configuration, so the script can replay anchored analyses
without manual table reconstruction.

When the supplied fit uses the latent-regression \code{MML} branch, the generated
fit-mode script also carries the stored replay-ready person table together
with the corresponding \code{population_formula} / \code{person_id} /
\code{population_policy} arguments needed to recreate the population model.
By default that replay-ready table is embedded inline; when
\code{fit_person_data_file} is supplied, the generated script reads it from that
sidecar CSV relative to the replay script location.

For bounded \code{GPCM}, replay scripts are available with an explicit
\code{gpcm_boundary} table. The generated script records \code{step_facet} and
\code{slope_facet} settings, but full FACETS score-side contract review remains
outside this replay contract. Role-based design forecasting is available
through \code{\link[=predict_mfrm_population]{predict_mfrm_population()}} as a separate caveated helper route.
}
\section{When to use this}{

Use \code{build_mfrm_replay_script()} when you want a package-native recipe that
another analyst can rerun later. Compared with related helpers:
\itemize{
\item \code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}} records settings but does not run anything.
\item \code{build_mfrm_replay_script()} produces executable R code.
\item \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} can optionally write the replay script to disk.
}
}

\section{Interpreting output}{

The returned object contains:
\itemize{
\item \code{summary}: a one-row overview of the chosen replay mode and whether bundle
export was included
\item \code{script}: the generated R code as a single string
\item \code{anchors} and \code{group_anchors}: the exact stored constraints that were
embedded into the script
}

If \code{ScriptMode} is \code{"facets"}, the script replays the higher-level
\code{\link[=run_mfrm_facets]{run_mfrm_facets()}} workflow. If it is \code{"fit"}, the script uses
\code{\link[=fit_mfrm]{fit_mfrm()}} directly.
}

\section{Mode guide}{

\itemize{
\item \code{"auto"} is the safest default and follows the structure of the supplied
object.
\item \code{"fit"} is useful when you want a minimal script centered on
\code{\link[=fit_mfrm]{fit_mfrm()}}.
\item \code{"facets"} is useful when you want to preserve the higher-level
\code{\link[=run_mfrm_facets]{run_mfrm_facets()}} workflow, including stored column mapping.
}
}

\section{Typical workflow}{

\enumerate{
\item Finalize a fit and diagnostics object.
\item Generate the replay script with the path you want users to read from.
\item Write \code{replay$script} to disk, or let \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} do it for
you.
\item Rerun the script in a fresh R session to confirm reproducibility.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
replay <- build_mfrm_replay_script(fit, data_file = "your_data.csv")
replay$summary[, c("ScriptMode", "ResidualPCA", "BiasPairs")]
cat(substr(replay$script, 1, 120))
}
\seealso{
\code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}, \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}, \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}
}
