Build native graph and observation-score output files

Build native graph and observation-score output files

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

fit

Output from fit_mfrm().

diagnostics

Optional output from diagnose_mfrm() (used for score file). Must match this fitted analysis; see mfrmr_compatibility_layer for migration of saved diagnostics. Exported score rows are observations, whereas FACETS Scorefile rows are elements. These formats are not interchangeable.

include

Output components to include: "graph" and/or "score".

theta_range

Theta/logit range for graph coordinates.

theta_points

Number of points on the theta grid for graph coordinates.

digits

Rounding digits for numeric fields. ConditionalVariance in the score table and delimited export retains full precision so small positive variances remain distinguishable from zero.

score_se_method

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

include_fixed

If TRUE, include fixed-width text mirrors of output tables.

fixed_max_rows

Maximum rows shown in fixed-width text blocks.

write_files

If TRUE, write selected outputs to files in output_dir.

output_dir

Output directory used when write_files = TRUE.

file_prefix

Prefix used for output file names.

overwrite

If FALSE, existing output files are not overwritten.

Value

A named list including:

• graphfile / graphfile_syntactic when "graph" is requested

• scorefile when "score" is requested

• graphfile_fixed / scorefile_fixed when include_fixed = TRUE

• written_files when write_files = TRUE

• settings: applied options

Details

Legacy-compatible output files often include:

• graph coordinates for Table 8 curves (GRAPH= / Graphfile=), and

• observation-level modeled score lines (SCORE=-style inspection).

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

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_output_bundle (type = "graph_expected", "score_residuals", "obs_probability", "score_se").

Interpreting output

• graphfile: legacy-compatible wide curve coordinates (human-readable labels).

• graphfile_syntactic: same curves with syntactic column names for programmatic use.

• scorefile: observation-level observed/expected/residual diagnostics.

• written_files: traceability record of files produced when write_files = TRUE.

For reproducible pipelines, prefer graphfile_syntactic and keep written_files in run logs.

Preferred route for new analyses

For new scripts, prefer category_curves_report() or category_structure_report() for scale outputs, then use export_mfrm_bundle() for file handoff. Use facets_output_file_bundle() for its native graph/observation-row contract. Its score file is not the element-level FACETS Scorefile format; use read_facets_results() to import actual FACETS element output.

GPCM boundary

For GPCM, graph output and package-native scorefile output are available with caveats. 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 score_se_method to choose "both" (default), "native", "score_side", or "none". The score-side route transforms a logit-side standard error with the GPCM expected-score derivative \(dE[X]/d\eta = \alpha Var(X)\), where ScoreSlope is \(\alpha\). ScoreSideLogitSE remains on the logit side; ScoreSideSE and its interval columns are on the expected-score scale. 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 mfrmr_output_guide("gpcm_capabilities", view = "scores") and mfrmr_output_guide("gpcm_capabilities") (mfrmr_gpcm_scope) for the current scope.

Typical workflow

1. Fit and diagnose model.

2. Generate bundle with include = c("graph", "score").

3. Validate with summary(out) / plot(out).

4. Export with write_files = TRUE for reporting handoff.

See also

category_curves_report(), diagnose_mfrm(), unexpected_response_table(), export_mfrm_bundle(), mfrmr_reports_and_tables, mfrmr_compatibility_layer

Examples

# Long-running workflow; run explicitly when needed.
# example("facets_output_file_bundle", run.dontrun = TRUE)
if (FALSE) { # \dontrun{
# Saved synthetic JML/RSM analysis of example_core.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "core-jml.rds", package = "mfrmr"))
fit <- example_fit$fit
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
} # }