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
)

# S3 method for class 'mfrm_summary_table_bundle'
summary(object, digits = 3, top_n = 8, ...)

# S3 method for class 'mfrm_summary_table_bundle'
plot(
  x,
  y = NULL,
  type = c("table_rows", "role_tables", "appendix_roles", "appendix_sections",
    "appendix_presets", "selection_handoff_presets", "selection_tables",
    "selection_handoff", "selection_handoff_bundles", "selection_handoff_roles",
    "selection_handoff_role_sections", "selection_bundles", "selection_roles",
    "selection_sections", "numeric_profile", "first_numeric"),
  which = NULL,
  selection_value = c("count", "fraction"),
  appendix_preset = c("recommended", "compact", "all", "methods", "results",
    "diagnostics", "reporting"),
  main = NULL,
  palette = NULL,
  label_angle = 45,
  draw = TRUE,
  ...
)

Arguments

x

For build_summary_table_bundle(): 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_calibration_score, mfrm_unit_prediction, or mfrm_plausible_values object, one of their summary() outputs, or a compatible precomputed recovery-evidence summary.

For plot(): Output from build_summary_table_bundle().

which

For build_summary_table_bundle(): Optional character vector selecting a subset of named tables.

For plot(): Optional table selector used for numeric plot types.

appendix_preset

For build_summary_table_bundle(): 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.

For plot(): Appendix preset used for selection_* plot types.

include_empty

If TRUE, retain empty tables in the returned bundle.

digits

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

For summary(): Number of digits used for numeric summaries.

top_n

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

For summary(): Maximum number of table-profile rows to keep.

preview_chars

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

object

Output from build_summary_table_bundle().

...

Reserved for generic compatibility.

y

Reserved for generic compatibility.

type

Plot type: "table_rows" for returned-table sizes, "role_tables" for returned-table counts by reporting role, "appendix_roles" for returned-table counts by reporting role under the bundle's appendix-routing contract, "appendix_sections" for returned-table counts by manuscript-facing appendix section, "appendix_presets" for conservative appendix-preset counts, "selection_handoff_presets" for workflow-only preset-level appendix handoff counts, "selection_tables" / "selection_handoff" / "selection_handoff_bundles" / "selection_handoff_roles" / "selection_bundles" / "selection_roles" / "selection_sections" for workflow-only appendix selection surfaces when present in the bundle, "numeric_profile" for column means from a selected numeric table, or "first_numeric" for the distribution of the first numeric column in a selected table.

selection_value

For selection_* plot types, whether to plot exact counts ("count") or the corresponding exact fraction ("fraction") when that surface exposes one.

main

Optional title override.

palette

Optional named color overrides.

label_angle

Axis-label rotation angle for bar-type plots.

draw

If TRUE, draw using base graphics.

Value

An object of class mfrm_summary_table_bundle with:

overview
table_index
plot_index
tables
appendix_preset
notes
source_class
summary_class

For summary(): An object of class summary.mfrm_summary_table_bundle.

For plot(): Invisibly, a ggplot object carrying its saved plot payload accessible via plot_data().

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.

summary() method: Summarize a summary-table bundle for manuscript QC

For summary(): This summary is designed to answer a manuscript-facing question: which reporting tables are available, how large are they, which roles do they serve, and which of them contain numeric content suitable for quick plotting or appendix export.

plot() method: Plot a summary-table bundle for manuscript QC

For plot(): This helper keeps summary-bundle plotting conservative. It either visualizes the bundle's own bundle-level indexes ("table_rows", "role_tables", "appendix_roles", "appendix_sections", "appendix_presets") or routes a selected table through apa_table() and plot.apa_table() for numeric QC.

Supported inputs

mfrm_g_study(), mfrm_d_study(), mfrm_multivariate_d_compare(), mfrm_residual_network() or their mfrm_report() objects; supply saved intervals to mfrm_report() first. These routes retain all evidence tables, including signed estimates, settings and unavailable states, without top_n truncation.
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)
simulate_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)
score_mfrm_calibration() or summary(scores); includes all review dispositions and unrounded conditional decisions when requested
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, comparison_warnings, model_roles, downstream_routes, and report_templates so RSM/PCM versus GPCM comparisons remain tied to their same-basis limits, equal-weighting, sensitivity, and reporting-boundary roles.

For summary():

overview: source class, returned-table count, note count, and whether a numeric table is available for plotting.
role_summary: counts and total size by reporting role.
table_catalog: complete returned-table registry with plot/export bridges.
table_profile: table-level dimensions, numeric-column counts, and missing values for the largest returned tables.
plot_index: which returned tables are plot-ready and which bundle-level numeric QC routes they support.
appendix_presets: conservative all / recommended / compact plus section-aware methods / results / diagnostics / reporting appendix-export presets derived from table roles.
appendix_role_summary: counts of returned tables by reporting role under the same conservative appendix routing used by the bundle catalog.
appendix_section_summary: counts of returned tables by manuscript-facing appendix section.
selection_handoff_table_summary: workflow-only table-level appendix handoff crosswalk when present in the bundle.
selection_handoff_preset_summary: workflow-only appendix handoff overview aggregated at the preset level when present in the bundle.
selection_handoff_bundle_summary: workflow-only appendix handoff overview aggregated at the bundle-by-section level when present in the bundle.
selection_handoff_role_summary: workflow-only appendix handoff overview aggregated at the reporting-role level when present in the bundle.
selection_handoff_role_section_summary: workflow-only appendix handoff overview aggregated at the reporting-role by appendix-section level when present in the bundle.
selection_summary, selection_table_summary, selection_table_preset_summary, selection_role_summary, selection_section_summary, and selection_catalog: preset-filtered appendix selection surfaces when workflow-only handoff tables are embedded in the bundle.
reporting_map: where to go next for plotting, APA formatting, and export.
notes: carried forward source-level caveats from the originating summary.

For plot():

"table_rows": compares returned table sizes to show where reporting mass sits.
"role_tables": shows how many returned tables belong to each reporting role.
"appendix_roles": shows how returned tables contribute to conservative appendix routing by reporting role.
"appendix_sections": shows how returned tables are distributed across methods/results/diagnostics/reporting sections.
"appendix_presets": shows how many tables the current bundle contributes to the conservative appendix presets.
"selection_handoff_presets": shows plot-ready appendix handoff counts by preset for workflow-only appendix routing surfaces in the bundle.
"selection_tables" / "selection_handoff" / "selection_handoff_bundles" / "selection_handoff_roles" / "selection_handoff_role_sections" / "selection_bundles" / "selection_roles" / "selection_sections": show workflow-only appendix selection surfaces already materialized inside the bundle.
"numeric_profile" / "first_numeric": reuse the same numeric QC logic as plot.apa_table() but start from a summary-table bundle.

Typical workflow

Build a compact object with summary(...).
Convert it with build_summary_table_bundle(...).
Use bundle$tables[[...]] directly, or hand a selected table to apa_table() for formatted manuscript output.
If you want a manuscript appendix subset up front, use a preset such as appendix_preset = "recommended", "compact", or "diagnostics".
For recovery-assessment or recovery-validation summaries, inspect bundle$tables$reading_order first when it is available.
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 GPCM generator stress is part of the plan.