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",
  script_mode = c("auto", "fit", "facets"),
  include_bundle = FALSE,
  bundle_dir = "analysis_bundle",
  bundle_prefix = "mfrmr_replay"
)

Arguments

fit: Output from fit_mfrm() or run_mfrm_facets().
diagnostics: Optional output from diagnose_mfrm(). When NULL, diagnostics are reused from run_mfrm_facets() when available, otherwise recomputed.
bias_results: Optional output from estimate_bias() or a named list of bias bundles. When supplied, the generated script includes package-native bias estimation calls.
population_prediction: Optional output from predict_mfrm_population() to recreate in the generated script.
unit_prediction: Optional output from predict_mfrm_units() to recreate in the generated script.
plausible_values: Optional output from sample_mfrm_plausible_values() to recreate in the generated script.
data_file: Path to the analysis data file used in the generated script.
script_mode: One of "auto", "fit", or "facets". "auto" uses run_mfrm_facets() when the input object came from that workflow.
include_bundle: If TRUE, append an export_mfrm_bundle() call to the generated script.
bundle_dir: Output directory used when include_bundle = TRUE.
bundle_prefix: Prefix used by the generated bundle exporter call.

Value

A named list with class mfrm_replay_script.

Details

This helper mirrors the Streamlit app's reproducible-download idea, but uses 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 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 to use this

Use build_mfrm_replay_script() when you want a package-native recipe that another analyst can rerun later. Compared with related helpers:

build_mfrm_manifest() records settings but does not run anything.
build_mfrm_replay_script() produces executable R code.
export_mfrm_bundle() can optionally write the replay script to disk.

Interpreting output

The returned object contains:

summary: a one-row overview of the chosen replay mode and whether bundle export was included
script: the generated R code as a single string
anchors and group_anchors: the exact stored constraints that were embedded into the script

If ScriptMode is "facets", the script replays the higher-level run_mfrm_facets() workflow. If it is "fit", the script uses fit_mfrm() directly.

Mode guide

"auto" is the safest default and follows the structure of the supplied object.
"fit" is useful when you want a minimal script centered on fit_mfrm().
"facets" is useful when you want to preserve the higher-level run_mfrm_facets() workflow, including stored column mapping.

Typical workflow

Finalize a fit and diagnostics object.
Generate the replay script with the path you want users to read from.
Write replay$script to disk, or let export_mfrm_bundle() do it for you.
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 = 25)
replay <- build_mfrm_replay_script(fit, data_file = "your_data.csv")
replay$summary[, c("ScriptMode", "ResidualPCA", "BiasPairs")]
#>   ScriptMode ResidualPCA BiasPairs
#> 1        fit        none         0
cat(substr(replay$script, 1, 120))
#> #!/usr/bin/env Rscript
#> # Generated by mfrmr::build_mfrm_replay_script()
#> # Model: RSM | Method: JML | InternalMethod: JML