build_mfrm_replay_script: Build a package-native replay script for an MFRM analysis

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Build a package-native replay script for an MFRM analysis

Description

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.

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.

Value

A named list with class mfrm_replay_script.

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

1. Finalize a fit and diagnostics object.

2. Generate the replay script with the path you want users to read from.

3. Write replay$script to disk, or let export_mfrm_bundle() do it for you.

4. Rerun the script in a fresh R session to confirm reproducibility.

See Also

build_mfrm_manifest(), export_mfrm_bundle(), run_mfrm_facets()

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")]
cat(substr(replay$script, 1, 120))

mfrmr documentation built on March 31, 2026, 1:06 a.m.