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". By default, export all listed components except predictions when no prediction or plausible-value object is supplied. Explicitly requesting "predictions" requires at least one such object.
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_summary row for data describes the user's untouched input structure; it is not a byte-level equality claim about the CSV replay representation. 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 mfrmr functions for estimation and 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 and interpretation notes via facet_quality_dashboard(), including screening settings in CSV and HTML; HTML tables show every level's estimates and unavailable diagnostics, while CSVs retain full detail
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()
exact source-fit readiness CSVs with fit, component, and parameter scope
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()
replay-source readiness CSVs retained as provenance; the replayed fit recomputes its own readiness
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 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 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 = 300)
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           23           1             1
head(data.frame(
  Component = bundle$written_files$Component,
  File = basename(bundle$written_files$Path)
))
#>          Component                                      File
#> 1      core_person mfrmr_bundle_example_person_estimates.csv
#> 2      core_facets  mfrmr_bundle_example_facet_estimates.csv
#> 3     core_summary      mfrmr_bundle_example_fit_summary.csv
#> 4    core_measures         mfrmr_bundle_example_measures.csv
#> 5       core_steps  mfrmr_bundle_example_step_parameters.csv
#> 6 manifest_summary mfrmr_bundle_example_manifest_summary.csv
# Full paths and data-handling notes remain in bundle$written_files.
# }