% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{export_mfrm_bundle}
\alias{export_mfrm_bundle}
\title{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{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. When \code{NULL},
diagnostics are reused from \code{run_mfrm_facets()} when available, otherwise
computed with \code{residual_pca = "none"} (or \code{"both"} when visual summaries
are requested).}

\item{bias_results}{Optional output from \code{\link[=estimate_bias]{estimate_bias()}} or a named list of
bias bundles.}

\item{population_prediction}{Optional output from
\code{\link[=predict_mfrm_population]{predict_mfrm_population()}}.}

\item{unit_prediction}{Optional output from \code{\link[=predict_mfrm_units]{predict_mfrm_units()}}.}

\item{plausible_values}{Optional output from \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}}.}

\item{summary_tables}{Optional manuscript-summary bundle input. Can be
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} output, any object supported by
\code{build_summary_table_bundle()}, or a named list of such objects. When
\code{NULL} and \code{"summary_tables"} is requested in \code{include}, a default set is
built from \code{fit}, \code{diagnostics}, \code{\link[=reporting_checklist]{reporting_checklist()}}, and
\code{\link[=build_apa_outputs]{build_apa_outputs()}}. Recovery-validation summaries can be supplied here
to co-locate release-review appendix tables with a fit-based export bundle.}

\item{output_dir}{Directory where files will be written.}

\item{prefix}{File-name prefix.}

\item{include}{Components to export. Supported values are
\code{"core_tables"}, \code{"checklist"}, \code{"dashboard"}, \code{"apa"}, \code{"anchors"},
\code{"manifest"}, \code{"visual_summaries"}, \code{"predictions"}, \code{"summary_tables"},
\code{"script"}, and \code{"html"}.}

\item{facet}{Optional facet for \code{\link[=facet_quality_dashboard]{facet_quality_dashboard()}}.}

\item{include_person_anchors}{If \code{TRUE}, include person measures in the
exported anchor table.}

\item{overwrite}{If \code{FALSE}, refuse to overwrite existing files.}

\item{zip_bundle}{If \code{TRUE}, attempt to zip the written files into a single
archive using \code{\link[utils:zip]{utils::zip()}}. This is best-effort and may depend on the
local R installation.}

\item{zip_name}{Optional zip-file name. Defaults to \code{"{prefix}_bundle.zip"}.}

\item{data}{Optional original analysis data frame. When supplied,
\code{export_mfrm_bundle()} co-locates a CSV copy of the data
alongside the replay script and updates the script's
\code{read.csv()} path to point at it. The manifest's \code{input_hash}
row for \code{data} is also computed against the user's untouched
input so the recorded fingerprint matches what the replay
script will load. Default \code{NULL} falls back to the legacy
\code{your_data.csv} placeholder path.}
}
\value{
A named list with class \code{mfrm_export_bundle}.
}
\description{
Export an analysis bundle for sharing or archiving
}
\details{
This function is the package-native counterpart to the app's download bundle.
It reuses existing \code{mfrmr} helpers instead of reimplementing estimation or
diagnostics.
}
\section{Choosing exports}{

The \code{include} argument lets you assemble a bundle for different audiences:
\itemize{
\item \code{"core_tables"} for analysts who mainly want CSV output.
\item \code{"manifest"} for a compact analysis record.
\item \code{"script"} for reproducibility and reruns. For latent-regression fits,
this also writes the fit-level replay person-data sidecar when available.
\item \code{"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.
\item \code{"summary_tables"} for manuscript-facing CSV exports of validated
\code{summary()} surfaces and their compact indexes.
\item \code{"visual_summaries"} when you want warning maps or residual PCA summaries
to travel with the bundle.
}
}

\section{Recommended presets}{

Common starting points are:
\itemize{
\item minimal tables: \code{include = c("core_tables", "manifest")}
\item reporting bundle: \code{include = c("core_tables", "checklist", "dashboard", "summary_tables", "html")}
\item archival bundle: \code{include = c("core_tables", "manifest", "script", "visual_summaries", "html")}
}
}

\section{Written outputs}{

Depending on \code{include}, the exporter can write:
\itemize{
\item core CSV tables via \code{\link[=export_mfrm]{export_mfrm()}}
\item checklist CSVs via \code{\link[=reporting_checklist]{reporting_checklist()}}
\item facet-dashboard CSVs via \code{\link[=facet_quality_dashboard]{facet_quality_dashboard()}}
\item APA text files via \code{\link[=build_apa_outputs]{build_apa_outputs()}}
\item manuscript-summary CSVs via \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}
\item anchor CSV via \code{\link[=make_anchor_table]{make_anchor_table()}}
\item manifest CSV/TXT via \code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}
\item visual warning/summary artifacts via \code{\link[=build_visual_summaries]{build_visual_summaries()}}
\item prediction/forecast CSVs via \code{\link[=predict_mfrm_population]{predict_mfrm_population()}},
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}}, and \code{\link[=sample_mfrm_plausible_values]{sample_mfrm_plausible_values()}}
\item a package-native replay script via \code{\link[=build_mfrm_replay_script]{build_mfrm_replay_script()}}
\item for latent-regression fits, a replay-side person-data CSV paired with the
replay script
\item 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. \code{\link[=predict_mfrm_population]{predict_mfrm_population()}} remains the scenario-level
forecast helper, whereas \code{\link[=predict_mfrm_units]{predict_mfrm_units()}} and
\code{\link[=sample_mfrm_plausible_values]{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
\verb{*_population_prediction_settings.csv} or ADeMP CSVs; the compact simulation
specification files carry the replay-relevant settings instead.

For bounded \code{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 \code{gpcm_boundary}.
Package-native bounded-\code{GPCM} scorefile export is available with caveats,
while full FACETS-style score-side contract review and design forecasting
remain outside this bundle contract.
}

\section{Interpreting output}{

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

\section{Typical workflow}{

\enumerate{
\item Fit a model and compute diagnostics once.
\item Decide whether the audience needs tables only, or also a manifest,
replay script, and HTML summary.
\item Call \code{export_mfrm_bundle()} with a dedicated output directory.
\item Inspect \code{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 = 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)
}
\seealso{
\code{\link[=build_mfrm_manifest]{build_mfrm_manifest()}}, \code{\link[=build_mfrm_replay_script]{build_mfrm_replay_script()}},
\code{\link[=export_mfrm]{export_mfrm()}}, \code{\link[=reporting_checklist]{reporting_checklist()}}, \code{\link[=export_summary_appendix]{export_summary_appendix()}}
}
