% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data_plots.R
\name{RMplotBar}
\alias{RMplotBar}
\title{Item Response Distribution Bar Chart}
\usage{
RMplotBar(
  data,
  item_labels = NULL,
  category_labels = NULL,
  ncol = 1L,
  label_wrap = 25L,
  text_y = 6,
  viridis_option = "A",
  viridis_end = 0.9,
  font = "sans"
)
}
\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 (facet strips). Must be the same length as
\code{ncol(data)}. If \code{NULL} (the default), column names are used.
Labels are displayed as \code{"column_name - label"}.}

\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.}

\item{ncol}{Integer. Number of columns in the faceted layout.
Default is \code{1L}.}

\item{label_wrap}{Integer. Number of characters per line in facet
strip labels before wrapping. Default is \code{25L}.}

\item{text_y}{Numeric. Vertical position (in percent units) for the
count labels on each bar. Adjust upward if bars are tall. Default
is \code{6}.}

\item{viridis_option}{Character. Viridis palette option for the
count-text colour. One of \code{"A"} through \code{"H"}. Default is \code{"A"}.}

\item{viridis_end}{Numeric in \eqn{[0, 1]}. End point of the viridis
colour scale for count text. Adjust if text is hard to read against
the bar colours. Default is \code{0.9}.}

\item{font}{Character. Font family for all text. Default is
\code{"sans"}.}
}
\value{
A \link[ggplot2:ggplot]{ggplot2::ggplot} object.
}
\description{
Creates a faceted bar chart showing the response distribution for each
item, with counts and percentages displayed on each bar. Each item gets
its own panel, with response categories on the x-axis and percentage of
responses on the y-axis. This is a descriptive data visualization tool
intended for use before model fitting.
}
\details{
Each item is displayed as a separate facet panel with the item label
in the strip on the left side. Bars are coloured by response category
using the viridis palette. Each bar shows the count (\code{n = X}) as text.

The plot caption reports the sample in the standard
\verb{n = X respondents (policy)} form; item-level \code{NA}s are retained --
each bar counts the non-missing responses for that item.

\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{
if (requireNamespace("eRm", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  data(pcmdat2, package = "eRm")

  # Basic response distribution plot
  RMplotBar(pcmdat2)

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

  # Two-column layout with wrapped labels
  RMplotBar(
    pcmdat2,
    item_labels = c(
      "General mood and emotional wellbeing",
      "Quality of sleep at night",
      "Appetite and eating habits",
      "Overall energy level during the day"
    ),
    ncol = 2, label_wrap = 20
  )

  # With custom category labels
  RMplotBar(
    pcmdat2,
    category_labels = c("Never", "Sometimes", "Often")
  )
}

}
\seealso{
\code{\link[=RMplotStackedbar]{RMplotStackedbar()}}, \code{\link[=RMplotTile]{RMplotTile()}}
}
