% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tile_plot.R
\name{RMplotTile}
\alias{RMplotTile}
\title{Tile Plot of Item Response Distributions}
\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{
\item{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 \code{group}.}

\item{group}{Optional vector of length \code{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 \code{NULL} (no faceting). Persons with \code{NA} group are
excluded, with a \code{message()} reporting how many rows were dropped.}

\item{cutoff}{Integer. Cells with counts below this value are
highlighted (when \code{highlight = TRUE}). Default \code{10}.}

\item{highlight}{Logical. If \code{TRUE} (default), cell labels with counts
below \code{cutoff} are displayed in red. This includes empty cells
(\code{n = 0}), useful for identifying gaps in the response distribution.}

\item{percent}{Logical. If \code{TRUE}, cell labels show percentages
instead of raw counts. Percentages are computed within item (and
within group, when \code{group} is supplied). Default \code{FALSE}.}

\item{text_color}{Character. Colour for non-highlighted cell labels.
Default \code{"orange"}.}

\item{text_size}{Numeric. Size of the cell labels (passed to
\code{ggplot2::geom_text()}). Default \code{4}, matching \code{\link[=RMitemCatProb]{RMitemCatProb()}}.}

\item{zero_fill}{Colour for cells with zero responses, or \code{NULL} to
keep them on the fill scale. Default \code{"white"}: empty cells are
shown unfilled with a light grey outline, so the \emph{absence} of data
reads as absence rather than as the darkest end of the colour
scale (where \code{n = 0} is nearly indistinguishable from \code{n = 1}).}

\item{item_labels}{Optional character vector of descriptive labels
for the items (y-axis), same length as \code{ncol(data)}. Default \code{NULL}
uses the column names.}

\item{category_labels}{Optional character vector of labels for the
response categories (x-axis), same length as the number of
categories spanning \code{min} to \code{max} observed value. Default \code{NULL}
uses the numeric category values.}

\item{group_labels}{Optional character vector of length
\code{nlevels(as.factor(group))} to override the displayed facet labels.
Order corresponds to \code{levels(as.factor(group))}.}

\item{facet_ncol}{Integer or \code{NULL}. Number of columns in the facet
grid when \code{group} is supplied. Default \code{NULL} (ggplot2 chooses).}

\item{output}{Character. \code{"ggplot"} (default) returns the plot;
\code{"dataframe"} returns the underlying per-cell counts (one row per
item x category, plus group when supplied).}
}
\value{
Either a \code{ggplot} object or a data.frame, depending on
\code{output}.
}
\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.
}
\details{
Adapted from \code{easyRaschBayes::plot_tile()} and extended with the
\code{group} parameter for faceted display.

Items are placed on the y-axis (in the same order as the columns of
\code{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 (\code{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 \code{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
\verb{n = X of Y respondents (policy)} form: rows with \code{NA} group are
dropped (and counted in \code{Y} only), while item-level \code{NA}s are retained
-- each cell simply counts the non-missing responses for that item.
}
\examples{
\donttest{
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")
}
}

}
