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

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.
fit_person_data_file: Optional CSV filename to read for the fit-level latent-regression replay person table. When NULL, the replay script embeds that table inline. export_mfrm_bundle() uses this to keep replay scripts portable while avoiding large inline literals.
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 builds a reproducible script from mfrmr's installed API. 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. The script retains centering_scope; a native fit saved before this setting was recorded uses "remainder". Running it performs a new fit under that convention, not a conversion of the saved object. To adopt whole-facet centering, review the generated call and change it to "facet", preserving the intended population, uncentered facet, rubric and step/slope owners. Recheck the resulting constraints and readiness. Use saveRDS()/readRDS() to reopen an unchanged fit, or the replay from export_mfrm_results() to reopen a saved results bundle without refitting.

Adjustments made with apply_empirical_bayes_shrinkage() are replayed after fitting, using the most recently recorded prior and Person settings. The original fitting settings remain separate so that attaching diagnostic SEs and then applying shrinkage is reproduced in the same order. For a workflow object with a post-fit adjustment, "auto" selects "fit" mode; an explicit "facets" request is refused because it cannot retain that operation order. Older shrinkage results without complete settings must first be refreshed with apply_empirical_bayes_shrinkage(). Manually edited SEs or other table edits require their own reproducible editing steps.

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

For GPCM, replay scripts are available with an explicit gpcm_boundary table. The generated script records step_facet and slope_facet settings, but full FACETS score-side contract review remains outside this replay contract. Role-based design forecasting is available through predict_mfrm_population() as a separate caveated helper route.

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
source_readiness, source_readiness_components, and source_readiness_parameters: readiness provenance from the source fit
anchors and group_anchors: the exact stored constraints that were embedded into the script

The source readiness row is not copied into the replayed fit. The generated script recomputes readiness and warns when its fit-level decision fields do not match the source record. Identifier columns are read as text, preserving leading zeros and literal "NA" labels. Original column names and factor coding in exported person-level background data are retained. Stored diagnostic settings are replayed as well; older diagnostic objects may not retain interaction selection or PCA limits, so rerun diagnose_mfrm() before exporting them when those settings matter.

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.

Saved-result reuse

Supplied screening results must describe this fitted analysis. Results from another fit or older results without identity metadata are refused. See mfrmr_compatibility_layer to recreate them from the saved fit and matching diagnostics without refitting the model. Supplied unit scores, plausible values and fit-derived forecasts must also match this calibration. A forecast created with sim_spec remains a separate scenario; its source is recorded without asserting a match to the fit.

Examples

library(mfrmr)
# Saved synthetic MML/RSM analysis of example_operational.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "operational-mml.rds", package = "mfrmr"))
fit <- example_fit$fit
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: MML
#> # Recorded mfrmr vers