Plot fitted MFRM results with base R

Usage

# S3 method for class 'mfrm_fit'
plot(
  x,
  type = NULL,
  facet = NULL,
  top_n = 30,
  theta_range = c(-6, 6),
  theta_points = 241,
  title = NULL,
  palette = NULL,
  label_angle = 45,
  show_ci = FALSE,
  ci_level = 0.95,
  draw = TRUE,
  preset = c("standard", "publication", "compact"),
  ...
)

Arguments

x: An mfrm_fit object from fit_mfrm().
type: Plot type. Use NULL, "bundle", or "all" for the three-part fit bundle; otherwise choose one of "facet", "person", "step", "wright", "pathway", or "ccc".
facet: Optional facet name for type = "facet".
top_n: Maximum number of facet/step locations retained for compact displays.
theta_range: Numeric length-2 range for pathway and CCC plots.
theta_points: Number of theta grid points used for pathway and CCC plots.
title: Optional custom title.
palette: Optional color overrides.
label_angle: Rotation angle for x-axis labels where applicable.
show_ci: If TRUE, add approximate confidence intervals when available.
ci_level: Confidence level used when show_ci = TRUE.
draw: If TRUE, draw the plot with base graphics.
preset: Visual preset ("standard", "publication", or "compact").
...: Additional arguments ignored for S3 compatibility.

Value

Invisibly, an mfrm_plot_data object or an mfrm_plot_bundle when type is omitted.

Details

This S3 plotting method provides the core fit-family visuals for mfrmr. When type is omitted, it returns a bundle containing a Wright map, pathway map, and category characteristic curves. The returned object still carries machine-readable metadata through the mfrm_plot_data contract, even when the plot is drawn immediately.

type = "wright" shows persons, facet levels, and step thresholds on a shared logit scale. type = "pathway" shows expected score traces and dominant-category regions across theta. type = "ccc" shows category response probabilities. The remaining types provide compact person, step, or facet-specific displays.

Typical workflow

Fit a model with fit_mfrm().
Use plot(fit) to inspect the three core fit-family visuals.
Switch to type = "wright" or type = "pathway" when you need a single figure for reporting or manuscript preparation.

Further guidance

For a plot-selection guide and extended examples, see mfrmr_visual_diagnostics and vignette("mfrmr-visual-diagnostics", package = "mfrmr").

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(
  toy,
  "Person",
  c("Rater", "Criterion"),
  "Score",
  method = "JML",
  model = "RSM",
  maxit = 25
)
bundle <- plot(fit, draw = FALSE)
names(bundle)
#> [1] "wright_map"                     "pathway_map"                   
#> [3] "category_characteristic_curves"
if (interactive()) {
  plot(
    fit,
    type = "wright",
    preset = "publication",
    title = "Customized Wright Map",
    show_ci = TRUE,
    label_angle = 45
  )
  plot(
    fit,
    type = "pathway",
    title = "Customized Pathway Map",
    palette = c("#1f78b4")
  )
  plot(
    fit,
    type = "ccc",
    title = "Customized Category Characteristic Curves",
    palette = c("#1b9e77", "#d95f02", "#7570b3")
  )
}