% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{facets_output_file_bundle}
\alias{facets_output_file_bundle}
\title{Build a legacy-compatible output-file bundle (\verb{GRAPH=} / \verb{SCORE=})}
\usage{
facets_output_file_bundle(
  fit,
  diagnostics = NULL,
  include = c("graph", "score"),
  theta_range = c(-6, 6),
  theta_points = 241,
  digits = 4,
  score_se_method = c("both", "native", "score_side", "none"),
  include_fixed = FALSE,
  fixed_max_rows = 400,
  write_files = FALSE,
  output_dir = NULL,
  file_prefix = "mfrmr_output",
  overwrite = FALSE
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} (used for score file).}

\item{include}{Output components to include: \code{"graph"} and/or \code{"score"}.}

\item{theta_range}{Theta/logit range for graph coordinates.}

\item{theta_points}{Number of points on the theta grid for graph coordinates.}

\item{digits}{Rounding digits for numeric fields.}

\item{score_se_method}{For bounded \code{GPCM} scorefile exports, which
observation-level score uncertainty columns to compute. \code{"both"}
(default) includes native structural expected-score SEs and score-side
delta-method SEs; \code{"native"} includes only the structural expected-score
route; \code{"score_side"} includes only the score-side delta route; \code{"none"}
records explicit \code{not_requested} status columns.}

\item{include_fixed}{If \code{TRUE}, include fixed-width text mirrors of output tables.}

\item{fixed_max_rows}{Maximum rows shown in fixed-width text blocks.}

\item{write_files}{If \code{TRUE}, write selected outputs to files in \code{output_dir}.}

\item{output_dir}{Output directory used when \code{write_files = TRUE}.}

\item{file_prefix}{Prefix used for output file names.}

\item{overwrite}{If \code{FALSE}, existing output files are not overwritten.}
}
\value{
A named list including:
\itemize{
\item \code{graphfile} / \code{graphfile_syntactic} when \code{"graph"} is requested
\item \code{scorefile} when \code{"score"} is requested
\item \code{graphfile_fixed} / \code{scorefile_fixed} when \code{include_fixed = TRUE}
\item \code{written_files} when \code{write_files = TRUE}
\item \code{settings}: applied options
}
}
\description{
Build a legacy-compatible output-file bundle (\verb{GRAPH=} / \verb{SCORE=})
}
\details{
Legacy-compatible output files often include:
\itemize{
\item graph coordinates for Table 8 curves (\verb{GRAPH=} / \verb{Graphfile=}), and
\item observation-level modeled score lines (\verb{SCORE=}-style inspection).
}

This helper returns both as data frames and can optionally write
CSV/fixed-width text files to disk.

\code{summary(out)} is supported through \code{summary()}.
\code{plot(out)} is dispatched through \code{plot()} for class
\code{mfrm_output_bundle} (\code{type = "graph_expected"}, \code{"score_residuals"},
\code{"obs_probability"}, \code{"score_se"}).
}
\section{Interpreting output}{

\itemize{
\item \code{graphfile}: legacy-compatible wide curve coordinates (human-readable labels).
\item \code{graphfile_syntactic}: same curves with syntactic column names for programmatic use.
\item \code{scorefile}: observation-level observed/expected/residual diagnostics.
\item \code{written_files}: traceability record of files produced when \code{write_files = TRUE}.
}

For reproducible pipelines, prefer \code{graphfile_syntactic} and keep
\code{written_files} in run logs.
}

\section{Preferred route for new analyses}{

For new scripts, prefer \code{\link[=category_curves_report]{category_curves_report()}} or
\code{\link[=category_structure_report]{category_structure_report()}} for scale outputs, then use
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}} for file handoff. Use
\code{facets_output_file_bundle()} only when a legacy-compatible graphfile or
scorefile contract is required.
}

\section{Bounded GPCM boundary}{

For bounded \code{GPCM}, graph output and package-native scorefile output are
available with caveats. \code{include = "score"} returns observation-level fitted
expected score, residual, standardized residual, observed-category
probability, GPCM slope fields, and native structural delta-method
expected-score uncertainty and/or score-side delta-method SEs when the
required MML diagnostics are available. Use \code{score_se_method} to choose
\code{"both"} (default), \code{"native"}, \code{"score_side"}, or \code{"none"}.
The scorefile also carries explicit score-side caveat columns. It is not a
FACETS score-side equivalence file, does not export FACETS-equivalent
score-side standard errors, and does not establish an operational
score-scale decision. Use \code{\link[=gpcm_score_side_contract]{gpcm_score_side_contract()}} and
\code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}} for the current scope.
}

\section{Typical workflow}{

\enumerate{
\item Fit and diagnose model.
\item Generate bundle with \code{include = c("graph", "score")}.
\item Validate with \code{summary(out)} / \code{plot(out)}.
\item Export with \code{write_files = TRUE} for reporting handoff.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
out <- facets_output_file_bundle(fit, diagnostics = diagnose_mfrm(fit, residual_pca = "none"))
summary(out)
p_out <- plot(out, draw = FALSE)
p_out$data$plot
}
\seealso{
\code{\link[=category_curves_report]{category_curves_report()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=unexpected_response_table]{unexpected_response_table()}},
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}, \link{mfrmr_reports_and_tables},
\link{mfrmr_compatibility_layer}
}
