Export a fit-level analysis archive

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,
  acknowledge_sensitive = 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(). Compatible precomputed recovery-evidence summaries can be supplied here to co-locate their 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.
acknowledge_sensitive: Logical; set to TRUE only after acknowledging that the archive can contain direct person identifiers, person-level estimates, original labels, replay data, and local paths. This suppresses the privacy warning; it does not deidentify any file.
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.

Value

A named list with class mfrm_export_bundle.

Details

This function is the one-call fit-level archive and HTML route. It reuses existing mfrmr helpers instead of reimplementing estimation or diagnostics. When diagnostics = NULL, the exporter computes the diagnostics it needs, then writes the requested CSV/text/replay artifacts and a lightweight HTML page from the fitted object. Use mfrm_results() and mfrm_report() first when you want to inspect a results object before writing files; use export_mfrm_bundle() when the goal is a project-folder bundle from fit.

Every bundle is an analysis archive, not a deidentified or automatically shareable package. Core tables, anchors, predictions, replay sidecars, scripts, and HTML can contain identifying or study-sensitive information. Review and transform every file under the applicable data-handling policy before sharing it.

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 lightweight summary page. This is not a deidentification guarantee. 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 documented 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 structural-design 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

Fit a model and compute diagnostics once.
Decide whether the audience needs tables only, or also a manifest, replay script, and HTML summary.
Call export_mfrm_bundle() with a dedicated output directory.
Inspect bundle$written_files or open the generated HTML file.

Examples

# \donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
#> Warning: Optimization convergence review did not produce an inference-ready numerical solution (code = 1, status = iteration_limit). Optimizer reached the iteration limit before the terminal gradient became small enough for review-only acceptance. Inspect the model specification, data support, and starting values. Do not interpret estimates until the review is resolved.
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,
  acknowledge_sensitive = TRUE
)
bundle$summary[, c("FilesWritten", "HtmlWritten", "ScriptWritten")]
#>   FilesWritten HtmlWritten ScriptWritten
#> 1           17           1             1
head(bundle$written_files)
#>          Component Format
#> 1      core_person    csv
#> 2      core_facets    csv
#> 3     core_summary    csv
#> 4    core_measures    csv
#> 5       core_steps    csv
#> 6 manifest_summary    csv
#>                                                        Path
#> 1 /tmp/RtmpIbcapd/mfrmr_bundle_example_person_estimates.csv
#> 2  /tmp/RtmpIbcapd/mfrmr_bundle_example_facet_estimates.csv
#> 3      /tmp/RtmpIbcapd/mfrmr_bundle_example_fit_summary.csv
#> 4         /tmp/RtmpIbcapd/mfrmr_bundle_example_measures.csv
#> 5  /tmp/RtmpIbcapd/mfrmr_bundle_example_step_parameters.csv
#> 6 /tmp/RtmpIbcapd/mfrmr_bundle_example_manifest_summary.csv
#>                    DataHandling
#> 1 may_contain_person_level_data
#> 2         review_before_sharing
#> 3         review_before_sharing
#> 4         review_before_sharing
#> 5         review_before_sharing
#> 6         review_before_sharing
# }