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,
  output_dir = ".",
  prefix = "mfrmr_bundle",
  include = c("core_tables", "checklist", "dashboard", "apa", "anchors", "manifest",
    "visual_summaries", "predictions", "script", "html"),
  facet = NULL,
  include_person_anchors = FALSE,
  overwrite = FALSE,
  zip_bundle = FALSE,
  zip_name = 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().
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", "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".

Value

A named list with class mfrm_export_bundle.

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.

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.
"html" for a light, shareable summary page.
"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", "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()
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()
a lightweight HTML report that bundles the exported tables/text

Interpreting output

The returned object reports both high-level bundle status and the exact files written. In practice, bundle$summary is the quickest sanity 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

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
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")]
#>   FilesWritten HtmlWritten ScriptWritten
#> 1           16           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/RtmpeUKqG2/mfrmr_bundle_example_person_estimates.csv
#> 2  /tmp/RtmpeUKqG2/mfrmr_bundle_example_facet_estimates.csv
#> 3      /tmp/RtmpeUKqG2/mfrmr_bundle_example_fit_summary.csv
#> 4         /tmp/RtmpeUKqG2/mfrmr_bundle_example_measures.csv
#> 5  /tmp/RtmpeUKqG2/mfrmr_bundle_example_step_parameters.csv
#> 6 /tmp/RtmpeUKqG2/mfrmr_bundle_example_manifest_summary.csv