% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data_plots.R
\name{plot_stackedbars}
\alias{plot_stackedbars}
\title{Stacked Bar Chart of Item Response Distributions}
\usage{
plot_stackedbars(
  data,
  item_labels = NULL,
  category_labels = NULL,
  show_n = TRUE,
  show_percent = FALSE,
  text_color = "sienna1",
  text_size = 3,
  min_label_n = 0,
  viridis_option = "D",
  viridis_end = 0.99,
  title = "Item responses"
)
}
\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{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 (legend). Must be the same length
as the number of response categories spanning from the minimum
to the maximum observed value, ordered from lowest to highest
category. If \code{NULL} (the default), numeric category
values are used.}

\item{show_n}{Logical. If \code{TRUE} (the default), the count
of responses is displayed as a text label inside each bar
segment.}

\item{show_percent}{Logical. If \code{TRUE}, the percentage of
responses is displayed instead of (or in addition to) counts.
Default is \code{FALSE}.}

\item{text_color}{Character. Color for the count/percentage
labels. Default is \code{"sienna1"}.}

\item{text_size}{Numeric. Size of the count/percentage labels.
Default is 3.}

\item{min_label_n}{Integer. Minimum count required for a label
to be displayed within a bar segment. Segments with fewer
responses are left unlabelled to avoid clutter. Default is 0
(all segments labelled).}

\item{viridis_option}{Character. Viridis palette option. One of
\code{"A"} through \code{"H"}. Default is \code{"D"}.}

\item{viridis_end}{Numeric in \eqn{[0, 1]}. End point of the
viridis color scale. Default is 0.99.}

\item{title}{Character. Plot title. Default is
\code{"Item responses"}.}
}
\value{
A \code{\link[ggplot2]{ggplot}} object.
}
\description{
Creates a horizontal stacked bar chart showing the response
distribution for all items. Each bar represents one item, with
segments colored by response category. Counts are displayed as
text labels within each segment. This is a descriptive data
visualization tool intended for use before model fitting.
}
\details{
Items are displayed on the y-axis in the same order as the
columns in \code{data} (first column at the top). Each bar is
divided into segments representing response categories, with
the lowest category on the left and the highest on the right.
The total bar length equals the number of non-missing responses
for that item.

Categories with zero responses still appear in the legend but
produce no visible bar segment, which helps identify gaps in
the response distribution.

\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 stacked bar chart
plot_stackedbars(eRm::pcmdat2)

# With custom item and category labels
plot_stackedbars(
  eRm::pcmdat2,
  item_labels = c("Mood", "Sleep", "Appetite", "Energy"),
  category_labels = c("Never", "Sometimes", "Often")
)

# Show percentages, suppress small segments
plot_stackedbars(
  eRm::pcmdat2,
  show_percent = TRUE,
  show_n       = FALSE,
  min_label_n  = 5
)

}
