% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brms_plots.R
\name{plot_ipf}
\alias{plot_ipf}
\title{Item Category Probability Function Curves for Polytomous IRT Models}
\usage{
plot_ipf(
  model,
  item_var = item,
  person_var = id,
  items = NULL,
  theta_range = c(-4, 4),
  n_points = 100,
  ncol = NULL,
  line_size = 0.8,
  ribbon_alpha = 0.15,
  prob = 0.95,
  category_labels = NULL,
  palette = NULL
)
}
\arguments{
\item{model}{A fitted \code{\link[brms]{brmsfit}} object from a
polytomous IRT model (e.g., \code{family = acat} for a partial
credit model or \code{family = cumulative} for a graded response
model).}

\item{item_var}{An unquoted variable name identifying the item
grouping variable in the model data (e.g., \code{item}).}

\item{person_var}{An unquoted variable name identifying the person
grouping variable in the model data (e.g., \code{id}).}

\item{items}{An optional character vector of item names to plot.
If \code{NULL} (the default), all items in the model are plotted.}

\item{theta_range}{A numeric vector of length 2 specifying the range
of the latent variable (theta) for the x-axis. Default is
\code{c(-4, 4)}.}

\item{n_points}{Integer. Number of evenly spaced theta values at
which to evaluate the category probabilities. Default is 100.}

\item{ncol}{Integer. Number of columns in the faceted plot layout.
If \code{NULL} (the default), an appropriate number is chosen
automatically.}

\item{line_size}{Numeric. Line width for the probability curves.
Default is 0.8.}

\item{ribbon_alpha}{Numeric in \eqn{[0, 1]}. Transparency of the
credible interval ribbons. Default is 0.15. Set to 0 to hide
ribbons.}

\item{prob}{Numeric in \eqn{(0, 1)}. Width of the credible interval
for the ribbons. Default is 0.95.}

\item{category_labels}{An optional character vector of labels for
the response categories. If \code{NULL} (the default), categories
are labelled as integers starting from 1.}

\item{palette}{An optional character vector of colors, one per
response category. If \code{NULL} (the default), the
\code{viridis} discrete scale from \pkg{ggplot2} is used.}
}
\value{
A \code{\link[ggplot2]{ggplot}} object. The plot can be
further customised using standard \pkg{ggplot2} functions.
}
\description{
Plots item category probability functions (ICPFs) for polytomous
Bayesian IRT models fitted with \pkg{brms}. For each item, the
probability of endorsing each response category is plotted as a
function of the latent variable (theta), with separate colored
curves per category. All items are displayed in a combined faceted
plot.
}
\details{
The function computes category probabilities directly from the
posterior draws of the item threshold parameters. For the brms
\code{acat} (adjacent category / partial credit) family with
logit link, the density is:
\deqn{P(Y = y | \eta) = \frac{\exp\bigl(\sum_{k=1}^{y}(\eta -
  \tau_k)\bigr)}{\sum_{k=0}^{K} \exp\bigl(\sum_{j=1}^{k}(\eta -
  \tau_j)\bigr)}}
where \eqn{\eta} is the linear predictor (i.e., theta for a Rasch
model with no additional fixed effects) and \eqn{\tau_k} are the
item thresholds. Analogous formulas are used for the
\code{cumulative}, \code{sratio}, and \code{cratio} families.

Posterior uncertainty in the thresholds propagates into credible
interval ribbons around the category probability curves — a
Bayesian advantage over point-estimate-based plots.
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)
library(ggplot2)

# --- Partial Credit Model ---

df_pcm <- eRm::pcmdat2 \%>\%
  mutate(across(everything(), ~ .x + 1)) \%>\%
  rownames_to_column("id") \%>\%
  pivot_longer(!id, names_to = "item", values_to = "response")

fit_pcm <- brm(
  response | thres(gr = item) ~ 1 + (1 | id),
  data   = df_pcm,
  family = acat,
  chains = 4,
  cores  = 1, # use more cores if you have
  iter   = 500 # use at least 2000 
)

# Plot all items
plot_ipf(fit_pcm, item_var = item, person_var = id)

# Plot a subset of items
plot_ipf(fit_pcm, item_var = item, person_var = id,
         items = c("I1", "I2", "I3"))

# Customise appearance
plot_ipf(fit_pcm, item_var = item, person_var = id,
         theta_range = c(-6, 6), ncol = 3, prob = 0.90) +
  theme_minimal() +
  labs(title = "Item Category Probability Functions")
}

}
\references{
Bürkner, P.-C. (2021). Bayesian Item Response Modeling in R with
brms and Stan. \emph{Journal of Statistical Software}, \emph{100},
1--54. \doi{10.18637/jss.v100.i05}
}
\seealso{
\code{\link[brms]{posterior_epred}},
\code{\link[brms]{conditional_effects}},
}
