RMplotTile: Tile Plot of Item Response Distributions

In easyRasch2: Psychometric Analysis with Rasch Measurement Theory

Tile Plot of Item Response Distributions

Description

Creates a tile (heat map) plot showing the distribution of responses across all items and response categories. Each cell displays the count (or percentage) of responses, with optional conditional highlighting for cells with low counts. Optional faceting by a grouping variable is provided for inspecting subgroup response distributions before DIF analyses – particularly useful for spotting empty categories or under-represented subgroups before fitting Rasch models per group.

Usage

RMplotTile(
  data,
  group = NULL,
  cutoff = 10,
  highlight = TRUE,
  percent = FALSE,
  text_color = "orange",
  text_size = 4,
  zero_fill = "white",
  item_labels = NULL,
  category_labels = NULL,
  group_labels = NULL,
  facet_ncol = NULL,
  output = c("ggplot", "dataframe")
)

Arguments

data	A data.frame in wide format containing only the item response columns. Each column is one item, each row is one person. All columns must be numeric (integer-valued). Response categories may be coded starting from 0 or 1. Do not include person IDs, grouping variables, or other non-item columns – supply the grouping variable separately via group.
group	Optional vector of length nrow(data) (factor, character, or numeric) defining a grouping variable. When provided, the plot is faceted by group and counts / percentages are computed within each group. Default NULL (no faceting). Persons with NA group are excluded, with a message() reporting how many rows were dropped.
cutoff	Integer. Cells with counts below this value are highlighted (when highlight = TRUE). Default 10.
highlight	Logical. If TRUE (default), cell labels with counts below cutoff are displayed in red. This includes empty cells (n = 0), useful for identifying gaps in the response distribution.
percent	Logical. If TRUE, cell labels show percentages instead of raw counts. Percentages are computed within item (and within group, when group is supplied). Default FALSE.
text_color	Character. Colour for non-highlighted cell labels. Default "orange".
text_size	Numeric. Size of the cell labels (passed to ggplot2::geom_text()). Default 4, matching RMitemCatProb().
zero_fill	Colour for cells with zero responses, or NULL to keep them on the fill scale. Default "white": empty cells are shown unfilled with a light grey outline, so the absence of data reads as absence rather than as the darkest end of the colour scale (where n = 0 is nearly indistinguishable from n = 1).
item_labels	Optional character vector of descriptive labels for the items (y-axis), same length as ncol(data). Default NULL uses the column names.
category_labels	Optional character vector of labels for the response categories (x-axis), same length as the number of categories spanning min to max observed value. Default NULL uses the numeric category values.
group_labels	Optional character vector of length nlevels(as.factor(group)) to override the displayed facet labels. Order corresponds to levels(as.factor(group)).
facet_ncol	Integer or NULL. Number of columns in the facet grid when group is supplied. Default NULL (ggplot2 chooses).
output	Character. "ggplot" (default) returns the plot; "dataframe" returns the underlying per-cell counts (one row per item x category, plus group when supplied).

Details

Adapted from easyRaschBayes::plot_tile() and extended with the group parameter for faceted display.

Items are placed on the y-axis (in the same order as the columns of data, top to bottom) and response categories on the x-axis. Cell shading represents the count of responses (darker = more responses). Categories with zero responses are explicitly shown (n = 0), which helps identify gaps in the response distribution – one of the primary purposes of the plot, especially before DIF analyses where under-represented categories within a subgroup can break model fitting on that subgroup.

When group is supplied, percentages and the highlight cutoff are applied within each group, so a cell labelled "5" in the group-A facet contains the count for group A only.

The plot caption reports the sample in the standard ⁠n = X of Y respondents (policy)⁠ form: rows with NA group are dropped (and counted in Y only), while item-level NAs are retained – each cell simply counts the non-missing responses for that item.

Value

Either a ggplot object or a data.frame, depending on output.

Examples

if (requireNamespace("eRm", quietly = TRUE)) {
  data("pcmdat2", package = "eRm")

  # Basic tile plot
  RMplotTile(pcmdat2)

  # With percentages
  RMplotTile(pcmdat2, percent = TRUE)

  # Faceted by an external grouping variable
  set.seed(1)
  grp <- sample(c("A", "B"), nrow(pcmdat2), replace = TRUE)
  RMplotTile(pcmdat2, group = grp)

  # With custom labels and tighter cutoff
  RMplotTile(pcmdat2,
             group = grp,
             group_labels = c("Female", "Male"),
             cutoff = 5,
             facet_ncol = 2)

  # Underlying counts as a data.frame
  RMplotTile(pcmdat2, group = grp, output = "dataframe")
}

easyRasch2 documentation built on Sept. 13, 2026, 1:07 a.m.