% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data_plots.R
\name{plot_tile}
\alias{plot_tile}
\title{Tile Plot of Item Response Distributions}
\usage{
plot_tile(
  data,
  cutoff = 10,
  highlight = TRUE,
  percent = FALSE,
  text_color = "orange",
  item_labels = NULL,
  category_labels = NULL
)
}
\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.}

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

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

\item{percent}{Logical. If \code{TRUE}, cell labels show
percentages instead of raw counts. Default is \code{FALSE}.}

\item{text_color}{Character. Color for cell label text (when
not highlighted). Default is \code{"orange"}.}

\item{item_labels}{An optional character vector of descriptive
labels for the items (y-axis). Must be the same length as
\code{ncol(data)}. If \code{NULL} (the default), column names
are used.}

\item{category_labels}{An optional character vector of labels
for the response categories (x-axis). Must be the same length
as the number of response categories spanning from the minimum
to the maximum observed value. If \code{NULL} (the default),
numeric category values are used.}
}
\value{
A \code{\link[ggplot2]{ggplot}} object.
}
\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. This is a
descriptive data visualization tool intended for use before
model fitting.
}
\details{
The plot displays items on the y-axis (in the same order as the
columns in \code{data}, from top to bottom) and response
categories on the x-axis. Cell shading represents the count
of responses (darker = more responses). Cell labels show either
raw counts or percentages.

Categories with zero responses are explicitly shown (as cells
with \code{n = 0}), which helps identify gaps in the response
distribution — one of the primary purposes of this plot.

\strong{Input requirements:}
\itemize{
\item All columns must be numeric (integer-valued).
\item The data frame must contain at least 2 columns (items)
and at least 1 row (person).
}
}
\examples{
library(ggplot2)
if (requireNamespace("eRm", quietly = TRUE))

# Basic tile plot
plot_tile(eRm::pcmdat2)

# With custom item labels
plot_tile(
  eRm::pcmdat2,
  item_labels = c("Mood", "Sleep", "Appetite", "Energy")
)

# With custom category labels and percentages
plot_tile(
  eRm::pcmdat2,
  category_labels = c("Never", "Sometimes", "Often"),
  percent = TRUE
)

# Adjust cutoff for highlighting
plot_tile(eRm::pcmdat2, cutoff = 20, highlight = TRUE)

}
