Skip to contents

Manuscript-oriented four-panel draft (Wright + severity + threshold + summary)

Source: R/api-plotting-extras.R
plot_apa_figure_one.Rd

Builds a 2x2 draft composite for an mfrm_fit, suitable for reviewing a possible "Figure 1" in the Rasch-family RSM/PCM manuscript route. Panels: (1) Wright map, (2) rater severity profile with CI whiskers, (3) threshold ladder, (4) a one-line reliability / separation summary block. Each panel reuses the standalone plot helper so the visual language is consistent with the rest of the package.

Usage

plot_apa_figure_one(
  fit,
  diagnostics = NULL,
  rater_facet = "Rater",
  ci_level = 0.95,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE
)

Arguments

fit

An mfrm_fit from fit_mfrm().

diagnostics

Optional diagnose_mfrm() output.

rater_facet

Facet name to use as the "rater" axis (default "Rater").

ci_level

Confidence level for the rater severity panel.

preset

Visual preset.

draw

If TRUE, draw the composite immediately with graphics::layout().

Value

Invisibly, an mfrm_plot_data object whose data slot bundles the four panel data objects under wright, severity, threshold, and summary. Fit readiness is retained in data$fit_readiness, data$interpretation_status, and data$interpretation_note.

Interpreting output

Designed as a single-figure Methods or Results draft. The summary panel prints the model class, sample size, log-likelihood, AIC/BIC, and the largest non-Person facet's separation / reliability if available. A fit that has not passed its numerical, data, design, and stability gates produces one warning and a visible "REVIEW ONLY" label. Resolve that review before treating the composite as report-ready evidence.

See also

plot.mfrm_fit() (type = "wright"), plot_rater_severity_profile(), plot_threshold_ladder(), build_apa_outputs().

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.
p <- plot_apa_figure_one(fit, draw = FALSE)
#> Warning: Review-only display: Numerical=fail, Data=pass, Design=pass_linked, Stability=pass. Inspect `summary(fit)$readiness` and `fit$data_review` before substantive or cross-subset interpretation.
names(p$data)
#>  [1] "data"                  "title"                 "subtitle"             
#>  [4] "preset"                "plot_name"             "legend"               
#>  [7] "reference_lines"       "fit_readiness"         "interpretation_status"
#> [10] "interpretation_note"  
# }