Build a manuscript-oriented table bundle from summary() outputs

Build a manuscript-oriented table bundle from summary() outputs

Usage

build_summary_table_bundle(
  x,
  which = NULL,
  appendix_preset = NULL,
  include_empty = FALSE,
  digits = 3,
  top_n = 10,
  preview_chars = 160
)

Arguments

x

An mfrm_fit, mfrm_diagnostics, mfrm_precision_review, mfrm_fit_measures, mfrm_facets_fit_review, mfrm_person_fit_indices, mfrm_data_description, mfrm_reporting_checklist, mfrm_apa_outputs, mfrm_design_evaluation, mfrm_signal_detection, mfrm_recovery_simulation, mfrm_recovery_assessment, mfrm_population_prediction, mfrm_facets_run, mfrm_bias, mfrm_anchor_review, mfrm_linking_review, mfrm_misfit_casebook, mfrm_model_choice_review, mfrm_weighting_review, mfrm_unit_prediction, or mfrm_plausible_values object, one of their summary() outputs, or a compatible precomputed recovery-evidence summary.

which

Optional character vector selecting a subset of named tables.

appendix_preset

Optional appendix-oriented table preset: "all", "recommended", "compact", "methods", "results", "diagnostics", or "reporting". Cannot be combined with which. Section-aware presets keep returned tables whose bundle catalog maps to the requested appendix section.

include_empty

If TRUE, retain empty tables in the returned bundle.

digits

Digits forwarded when summary() must be computed from a raw object.

top_n

Row cap forwarded to compact summary() methods when x is a raw object.

preview_chars

Character cap forwarded to summary.mfrm_apa_outputs() when x is a raw APA-output object.

Value

An object of class mfrm_summary_table_bundle with:

• overview

• table_index

• plot_index

• tables

• appendix_preset

• notes

• source_class

• summary_class

Details

This helper turns the package's compact summary objects into a reproducible table bundle for manuscript drafting, appendix handoff, or downstream formatting. It does not replace apa_table(); instead, it provides a consistent bridge from summary() to named data.frame components that can later be rendered with apa_table() or exported directly.

The public entry point validates x and the summary-object contract up front, so malformed summaries fail with a package-level message instead of falling through to opaque downstream errors.

The function first normalizes x through the corresponding summary() method when needed, then records a table_index describing every available table and returns the selected tables in tables. Optional appendix presets can be applied at bundle-construction time when you want a conservative manuscript-facing subset before plotting or export.

Supported inputs

• fit_mfrm() or summary(fit)

• diagnose_mfrm() or summary(diag)

• precision_review_report() or summary(precision_review)

• fit_measures_table() or summary(fit_measures)

• facets_fit_review() or summary(facets_fit_review)

• compute_person_fit_indices() or summary(person_fit)

• describe_mfrm_data() or summary(ds)

• reporting_checklist() or summary(chk)

• build_apa_outputs() or summary(apa)

• evaluate_mfrm_design() or summary(sim_eval)

• evaluate_mfrm_signal_detection() or summary(sig_eval)

• evaluate_mfrm_recovery() or summary(rec)

• assess_mfrm_recovery() or summary(rec_assessment)

• a compatible precomputed recovery-evidence summary

• predict_mfrm_population() or summary(pred)

• the structural_design_review component of a design or prediction summary

• run_mfrm_facets() or summary(out)

• estimate_bias() or summary(bias)

• review_mfrm_anchors() or summary(review)

• build_linking_review() or summary(review)

• build_misfit_casebook() or summary(casebook)

• build_model_choice_review() or summary(review)

• build_weighting_review() or summary(review)

• predict_mfrm_units() or summary(pred_units)

• sample_mfrm_plausible_values() or summary(pv)

Interpreting output

• overview: one-row metadata about the source summary and table counts.

• table_index: table names, dimensions, roles, and manuscript-oriented descriptions.

• plot_index: which returned tables contain numeric content and which bundle-level plot types can use them directly.

• tables: named data.frame objects ready for formatting or export.

• appendix_preset: active appendix subset mode ("none" when not used).

• notes: short guidance about omitted empty tables or source-level caveats.

• fit-level caveats use the analysis_caveats role; pre-fit data score-support caveats use the score_category_caveats role. Both roles are classified as diagnostics and stay in recommended appendix subsets.

• recovery-assessment and recovery-validation summaries expose diagnostic_reporting_notes before diagnostic_review or diagnostic_oc_summary so fit/separation caveats can be reported without treating them as direct evidence of parameter recovery.

• recovery-validation summaries expose condition_reporting_notes before condition_summary so GPCM generator stress and sparse score support are not mistaken for recovery-metric failures.

• precision-review summaries expose fit_separation_basis so fit, ZSTD, separation/reliability/strata, and QC thresholds remain distinct forms of evidence rather than interchangeable summaries.

• fit-measure and FACETS fit-review summaries expose df/ZSTD sensitivity tables under precision-review roles, keeping MnSq status, ZSTD standardization, and external FACETS matching distinct in appendix handoffs.

• latent-regression fit summaries expose population_coding in the methods appendix role so categorical levels, contrasts, and encoded columns can be documented with the coefficient table.

• model-choice-review summaries expose comparison_table, model_roles, downstream_routes, and report_templates so RSM/PCM versus bounded GPCM comparisons remain tied to their equal-weighting, sensitivity, and reporting-boundary roles.

Typical workflow

1. Build a compact object with summary(...).

2. Convert it with build_summary_table_bundle(...).

3. Use bundle$tables[[...]] directly, or hand a selected table to apa_table() for formatted manuscript output.

4. If you want a manuscript appendix subset up front, use a preset such as appendix_preset = "recommended", "compact", or "diagnostics".

5. For recovery-assessment or recovery-validation summaries, inspect bundle$tables$reading_order first when it is available.

6. For recovery-assessment or recovery-validation summaries with retained diagnostics, read diagnostic_reporting_notes before the raw diagnostic_review or diagnostic_oc_summary. Read condition_reporting_notes before condition_review or condition_summary when bounded GPCM generator stress is part of the plan.

See also

summary(), apa_table(), reporting_checklist(), build_apa_outputs(), compare_mfrm(), build_model_choice_review(), build_weighting_review()

Examples

# \donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
  method = "JML", maxit = 30
)
#> Warning: Optimization convergence review did not produce an inference-ready numerical solution (code = 1, status = iteration_limit). Optimizer reached the iteration limit before the terminal gradient became small enough for review-only acceptance. Inspect the model specification, data support, and starting values. Do not interpret estimates until the review is resolved.
bundle <- build_summary_table_bundle(fit)
bundle$table_index
#>                  Table Rows Cols                 Role
#> 1             overview    1   52         run_overview
#> 2  population_overview    1   11     population_basis
#> 5    population_coding    0    6    population_coding
#> 6       facet_overview    2    7   facet_distribution
#> 7      person_overview    1    7  person_distribution
#> 8        step_overview    1    5   category_structure
#> 10   settings_overview    1   18  estimation_settings
#> 11       reporting_map    6    3        reporting_map
#> 12             caveats    0    8     analysis_caveats
#> 13      facet_extremes    8    3 extreme_facet_levels
#> 14         person_high   10    4  extreme_person_high
#> 15          person_low   10    4   extreme_person_low
#>                                                                                                                                       Description
#> 1                                                                              One-row model fit, convergence, and information-criteria overview.
#> 2                                                                                   Population-model basis, posterior basis, and omission review.
#> 5                                                    Latent-regression categorical covariate levels, contrasts, and encoded model-matrix columns.
#> 6                                                                                               Per-facet spread, range, and level-count summary.
#> 7                                                                                     Distribution of person measures and posterior SD summaries.
#> 8                                                                                                       Threshold range and monotonicity summary.
#> 10                                                                             Estimation settings that affect identification and interpretation.
#> 11                                                                                   Companion outputs to cite for manuscript-oriented reporting.
#> 12 Structured fit-level caveats such as retained zero-count categories, score-category recoding, and latent-regression population-model warnings.
#> 13                                                                                              Facet levels with the largest absolute estimates.
#> 14                                                                                                  Highest person measures from the current fit.
#> 15                                                                                                   Lowest person measures from the current fit.
summary(bundle)$role_summary
#>                    Role Tables TotalRows TotalCols
#> 12         run_overview      1         1        52
#> 11        reporting_map      1         6         3
#> 10    population_coding      1         0         6
#> 9      population_basis      1         1        11
#> 8   person_distribution      1         1         7
#> 7    facet_distribution      1         2         7
#> 6    extreme_person_low      1        10         4
#> 5   extreme_person_high      1        10         4
#> 4  extreme_facet_levels      1         8         3
#> 3   estimation_settings      1         1        18
#> 2    category_structure      1         1         5
#> 1      analysis_caveats      1         0         8
# }