Skip to contents

Build an APA-oriented table handoff using base R structures

Usage

apa_table(
  x,
  which = NULL,
  diagnostics = NULL,
  digits = 2,
  caption = NULL,
  note = NULL,
  bias_results = NULL,
  context = list(),
  whexact = FALSE,
  branch = c("apa", "facets")
)

Arguments

x

A data.frame, mfrm_fit, summary() output supported by build_summary_table_bundle(), an mfrm_summary_table_bundle, diagnostics list, bias-result list, saved RSM/PCM fixed-facet intervals, or saved GPCM slope/curve/bootstrap inference. Ordinary Person-score results also support which = "decisions" when cut scores were requested.

which

Optional table selector when x has multiple tables.

diagnostics

Optional diagnostics from diagnose_mfrm() (used when x is mfrm_fit and which targets diagnostics tables).

digits

Uniform number of rounding digits for numeric columns, except saved decision probabilities, boundaries and priors, which are retained at full precision in table.

caption

Optional caption text.

note

Optional note text.

bias_results

Optional output from estimate_bias() used when auto-generating APA metadata for fit-based tables.

context

Optional context list forwarded when auto-generating APA metadata for fit-based tables.

whexact

Logical forwarded to APA metadata helpers.

branch

Output branch: "apa" for manuscript-oriented labels, "facets" for FACETS-aligned labels.

Value

A list of class apa_table with fields:

  • table (data.frame)

  • which

  • caption

  • note

  • digits

  • branch, style

Details

This helper avoids styling dependencies and returns a reproducible base data.frame plus manuscript-oriented metadata. It does not claim complete APA 7 or JARS compliance: outside the saved decisions table, digits applies the same rounding rule to every numeric column, so statistic-specific formatting (for example, exact p-value, confidence-interval, and effect-size conventions) and the target journal's final typography still require human review.

Supported which values:

  • For mfrm_fit: "summary", "person", "facets", "steps"

  • For summary() outputs or mfrm_summary_table_bundle: names listed in build_summary_table_bundle(x)$table_index

  • For diagnostics list: "overall_fit", "measures", "fit", "reliability", "facets_chisq", "bias", "interactions", "interrater_summary", "interrater_pairs", "obs"

  • For bias-result list: "table", "summary", "chi_sq"

  • For ordinary score_mfrm_persons() output: "decisions". predict_mfrm_units() and score_mfrm_calibration() results and their summaries also accept this selector. Cuts must have been requested.

  • For RSM/PCM fixed-facet intervals: "intervals" (default), "settings", "contrasts", and "clusters" when present. Method, confidence level and unavailable reasons remain with the selected estimates and bounds.

  • For GPCM inference: "intervals" or "curves"; bootstrap results also retain "trials", "checks" and "source_checks" when recorded, "sampling", and "availability" for slope intervals or "test" for a null-model LRT. Extended results also expose "settings", and "clusters"/"contrasts" when present. Saved profile intervals also expose "profile", "profile_endpoints", "profile_checks" and "wald". Target and method columns are preserved.

Interpreting output

Saved ordinary Person-score, unit-prediction and portable-score results with cut probabilities support which = "decisions". Numeric probabilities, cut boundaries and priors are retained without decimal rounding in the table. They condition on calibration and the scoring prior; the cut labels do not establish CEFR alignment or a decision rule.

  • table: plain data.frame ready for export or further formatting.

  • which: source component that produced the table.

  • caption/note: manuscript-oriented metadata stored with the table.

Typical workflow

  1. Build table object with apa_table(...).

  2. Inspect quickly with summary(tbl).

  3. Render base preview via plot(tbl, ...) or export tbl$table.

Examples

library(mfrmr)

# Saved synthetic MML/RSM analysis of example_operational.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "operational-mml.rds", package = "mfrmr"))
fit <- example_fit$fit

# Turn one summary table into a table with a caption and note
results <- summary(fit)
tbl <- apa_table(results, which = "facet_overview",
                 caption = "Distribution of estimates within each facet")
tbl # Prints the table, caption, and note
#> Distribution of estimates within each facet
#>      Facet Levels MeanEstimate SDEstimate MinEstimate MaxEstimate Span
#>  Criterion      3            0        0.3       -0.34        0.22 0.57
#>      Rater      6            0        0.4       -0.61        0.41 1.02
#> Note. No population model was requested; MML used an unconditional normal person distribution.

# Extract the ordinary data frame for further formatting or export
tbl$table
#>       Facet Levels MeanEstimate SDEstimate MinEstimate MaxEstimate Span
#> 1 Criterion      3            0        0.3       -0.34        0.22 0.57
#> 2     Rater      6            0        0.4       -0.61        0.41 1.02
# This table summarizes facets; use as.data.frame(fit) for individual estimates