export_mfrm_bundle: Export an analysis bundle for sharing or archiving

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

Export an analysis bundle for sharing or archiving

Description

Export an analysis bundle for sharing or archiving

Usage

export_mfrm_bundle(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  population_prediction = NULL,
  unit_prediction = NULL,
  plausible_values = NULL,
  summary_tables = NULL,
  output_dir = ".",
  prefix = "mfrmr_bundle",
  include = c("core_tables", "checklist", "dashboard", "apa", "anchors", "manifest",
    "visual_summaries", "predictions", "summary_tables", "script", "html"),
  facet = NULL,
  include_person_anchors = FALSE,
  overwrite = FALSE,
  zip_bundle = FALSE,
  zip_name = NULL,
  data = NULL
)

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 computed with residual_pca = "none" (or "both" when visual summaries are requested).
bias_results	Optional output from estimate_bias() or a named list of bias bundles.
population_prediction	Optional output from predict_mfrm_population().
unit_prediction	Optional output from predict_mfrm_units().
plausible_values	Optional output from sample_mfrm_plausible_values().
summary_tables	Optional manuscript-summary bundle input. Can be build_summary_table_bundle() output, any object supported by build_summary_table_bundle(), or a named list of such objects. When NULL and "summary_tables" is requested in include, a default set is built from fit, diagnostics, reporting_checklist(), and build_apa_outputs(). Recovery-validation summaries can be supplied here to co-locate release-review appendix tables with a fit-based export bundle.
output_dir	Directory where files will be written.
prefix	File-name prefix.
include	Components to export. Supported values are "core_tables", "checklist", "dashboard", "apa", "anchors", "manifest", "visual_summaries", "predictions", "summary_tables", "script", and "html".
facet	Optional facet for facet_quality_dashboard().
include_person_anchors	If TRUE, include person measures in the exported anchor table.
overwrite	If FALSE, refuse to overwrite existing files.
zip_bundle	If TRUE, attempt to zip the written files into a single archive using utils::zip(). This is best-effort and may depend on the local R installation.
zip_name	Optional zip-file name. Defaults to "{prefix}_bundle.zip".
data	Optional original analysis data frame. When supplied, export_mfrm_bundle() co-locates a CSV copy of the data alongside the replay script and updates the script's read.csv() path to point at it. The manifest's input_hash row for data is also computed against the user's untouched input so the recorded fingerprint matches what the replay script will load. Default NULL falls back to the legacy your_data.csv placeholder path.

Details

This function is the package-native counterpart to the app's download bundle. It reuses existing mfrmr helpers instead of reimplementing estimation or diagnostics.

Value

A named list with class mfrm_export_bundle.

Choosing exports

The include argument lets you assemble a bundle for different audiences:

• "core_tables" for analysts who mainly want CSV output.

• "manifest" for a compact analysis record.

• "script" for reproducibility and reruns. For latent-regression fits, this also writes the fit-level replay person-data sidecar when available.

• "html" for a light, shareable summary page. When replay sidecars are present, the HTML shows an artifact index for them rather than embedding the raw person-level replay table.

• "summary_tables" for manuscript-facing CSV exports of validated summary() surfaces and their compact indexes.

• "visual_summaries" when you want warning maps or residual PCA summaries to travel with the bundle.

Recommended presets

Common starting points are:

• minimal tables: include = c("core_tables", "manifest")

• reporting bundle: include = c("core_tables", "checklist", "dashboard", "summary_tables", "html")

• archival bundle: include = c("core_tables", "manifest", "script", "visual_summaries", "html")

Written outputs

Depending on include, the exporter can write:

• core CSV tables via export_mfrm()

• checklist CSVs via reporting_checklist()

• facet-dashboard CSVs via facet_quality_dashboard()

• APA text files via build_apa_outputs()

• manuscript-summary CSVs via build_summary_table_bundle()

• anchor CSV via make_anchor_table()

• manifest CSV/TXT via build_mfrm_manifest()

• visual warning/summary artifacts via build_visual_summaries()

• prediction/forecast CSVs via predict_mfrm_population(), predict_mfrm_units(), and sample_mfrm_plausible_values()

• a package-native replay script via build_mfrm_replay_script()

• for latent-regression fits, a replay-side person-data CSV paired with the replay script

• a lightweight HTML report that bundles the exported tables/text and, for replay sidecars, an artifact summary instead of raw person-level rows

For latent-regression fits, prediction-side artifacts can carry the fitted population-model scoring basis when you explicitly supply the corresponding prediction objects. predict_mfrm_population() remains the scenario-level forecast helper, whereas predict_mfrm_units() and sample_mfrm_plausible_values() are the scoring layer. To keep exports and replay scripts practical, large future-planning schemas from scenario-level population predictions are not flattened into ⁠*_population_prediction_settings.csv⁠ or ADeMP CSVs; the compact simulation specification files carry the replay-relevant settings instead.

For bounded GPCM, this exporter is available as a caveated partial bundle over supported diagnostics, report text, visual summaries, manifests, and replay scripts. The returned object and manifest include gpcm_boundary. Package-native bounded-GPCM scorefile export is available with caveats, while full FACETS-style score-side contract review and design forecasting remain outside this bundle contract.

Interpreting output

The returned object reports both high-level bundle status and the exact files written. In practice, bundle$summary is the direct status check, while bundle$written_files is the file inventory to inspect or hand off to other tools.

Typical workflow

1. Fit a model and compute diagnostics once.

2. Decide whether the audience needs tables only, or also a manifest, replay script, and HTML summary.

3. Call export_mfrm_bundle() with a dedicated output directory.

4. Inspect bundle$written_files or open the generated HTML file.

See Also

build_mfrm_manifest(), build_mfrm_replay_script(), export_mfrm(), reporting_checklist(), export_summary_appendix()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bundle <- export_mfrm_bundle(
  fit,
  diagnostics = diag,
  output_dir = tempdir(),
  prefix = "mfrmr_bundle_example",
  include = c("core_tables", "manifest", "script", "html"),
  overwrite = TRUE
)
bundle$summary[, c("FilesWritten", "HtmlWritten", "ScriptWritten")]
head(bundle$written_files)

mfrmr documentation built on June 13, 2026, 1:07 a.m.