% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item_hierarchy.R
\name{RMitemHierarchy}
\alias{RMitemHierarchy}
\title{Item-Threshold Hierarchy Plot}
\usage{
RMitemHierarchy(
  data,
  show_numbers = TRUE,
  sem_multiplier = 1.405,
  item_labels = NULL,
  output = c("ggplot", "dataframe")
)
}
\arguments{
\item{data}{A data.frame or matrix of polytomous item responses
(non-negative integers, 0-based, max value > 1). One column per
item, one row per person.}

\item{show_numbers}{Logical. When \code{TRUE} (default), prints the
numerical item location and threshold values next to the points on
the plot. When \code{FALSE}, only the threshold labels (\code{T1}, \code{T2}, ...)
are shown.}

\item{sem_multiplier}{Numeric multiplier for the threshold SE used to
draw the error bars. Default \code{1.405} (84\% CI). Common alternatives:
\code{1.96} (95\% CI), \code{2.576} (99\% CI).}

\item{item_labels}{Optional character vector of length \code{ncol(data)}
providing descriptive labels for items. Default \code{NULL} uses the
column names of \code{data}. Labels are appended to the column names on
the y-axis (\code{name - label}) and wrapped at 36 characters via base-R
\code{strwrap()}.}

\item{output}{One of \code{"ggplot"} (default) -- a faceted hierarchy
figure -- or \code{"dataframe"} -- the long-format underlying data with
one row per (item × threshold).}
}
\value{
Either a \code{ggplot} (default) or a data.frame with columns
\code{Item}, \code{ItemLabel}, \code{Threshold}, \code{ThresholdLocation},
\code{ThresholdSE}, and \code{ItemLocation} (the per-item mean of the centred
thresholds).
}
\description{
Visualises item and threshold locations on the logit scale for a
Partial Credit Model. Items are sorted by their (mean-threshold)
location; each item shows its location as a black diamond and its
individual thresholds as coloured dots with confidence-interval error
bars.
}
\details{
Threshold locations are centred at the grand mean of all thresholds
across items, so the dashed reference line at 0 represents the mean
threshold location across the scale.

Confidence intervals around thresholds are 84\% by default
(\code{sem_multiplier = 1.405}), following Payton, Greenstone, & Schenker
(2003) -- non-overlap of 84\% intervals approximately corresponds to a
two-sample significance test at \eqn{\alpha = 0.05}. Use
\code{sem_multiplier = 1.96} for 95\% intervals.

\strong{Polytomous only.} Dichotomous items have a single threshold
that coincides with the item location; the hierarchy plot is
visually degenerate in that case. For dichotomous data use
\code{\link[=RMtargeting]{RMtargeting()}} or \code{\link[=RMscoreSE]{RMscoreSE()}} instead.

\strong{Centring convention.} The CML PCM thresholds (estimated via
\code{psychotools::pcmodel()}) are shifted so that their grand mean is zero;
each item's location is then the mean of its centred thresholds.
The dashed horizontal reference line on the plot marks this zero --
i.e., the average threshold across all items.
}
\examples{
\donttest{
if (requireNamespace("eRm", quietly = TRUE)) {
  data("pcmdat2", package = "eRm")
  RMitemHierarchy(pcmdat2)

  # 95\% CI instead of 84\%
  RMitemHierarchy(pcmdat2, sem_multiplier = 1.96)

  # Underlying data.frame
  RMitemHierarchy(pcmdat2, output = "dataframe")
}
}

}
\references{
Payton, M. E., Greenstone, M. H., & Schenker, N. (2003). Overlapping
confidence intervals or standard error intervals: What do they mean
in terms of statistical significance? \emph{Journal of Insect Science,
3}(34), 1-6. \doi{10.1093/jis/3.1.34}
}
\seealso{
\code{\link[=RMtargeting]{RMtargeting()}}, \code{\link[=RMscoreSE]{RMscoreSE()}}, \code{\link[=RMitemICCPlot]{RMitemICCPlot()}}
}
