% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item_parameters.R
\name{item_parameters}
\alias{item_parameters}
\title{Extract Item Parameters from a Bayesian Rasch Model}
\usage{
item_parameters(
  model,
  item_var = item,
  person_var = id,
  draws = FALSE,
  center = TRUE,
  prob = 0.95
)
}
\arguments{
\item{model}{A fitted \code{\link[brms]{brmsfit}} object. Supported
parameterisations:
\describe{
\item{Polytomous ordinal (PCM)}{e.g., \code{family = acat} with
\code{thres(gr = item)}, producing item-specific thresholds.}
\item{Dichotomous Rasch (random items)}{e.g.,
\code{response ~ 1 + (1 | item) + (1 | id)} with
\code{family = bernoulli()}.}
\item{Dichotomous 1PL (fixed items)}{e.g.,
\code{response ~ 0 + item + (1 | id)} with
\code{family = bernoulli()}.}
}}

\item{item_var}{An unquoted variable name identifying the item
grouping variable in the model data. Default is \code{item}.}

\item{person_var}{An unquoted variable name identifying the person
grouping variable in the model data. Default is \code{id}.}

\item{draws}{Logical. If \code{TRUE}, a draws matrix of full
posterior draws is included in the output. Default is
\code{FALSE}.}

\item{center}{Logical. If \code{TRUE} (the default), item
parameters are shifted so that the grand mean of all threshold
locations is zero, matching the frequentist CML convention and
the centering used in \code{\link{plot_targeting}}.}

\item{prob}{Numeric in \eqn{(0, 1)}. Width of the highest density
continuous interval (HDCI) reported in the summary. Default is
0.95.}
}
\value{
A list with the following elements:
\describe{
\item{locations}{A \code{\link[tibble]{tibble}} in long format
with one row per item (dichotomous) or per item-threshold
(polytomous), containing \code{item}, \code{threshold}
(integer, always 1 for dichotomous), and \code{location}
(posterior mean on the logit scale).}
\item{locations_wide}{A \code{\link[tibble]{tibble}} in wide
format with one row per item, sorted by mean location. For
polytomous models, threshold columns are named \code{t1},
\code{t2}, etc., and a \code{location} column gives the mean
across thresholds. For dichotomous models, only \code{item}
and \code{location} columns are present.}
\item{summary}{A \code{\link[tibble]{tibble}} extending the long
\code{locations} with: \code{se} (posterior SD),
\code{hdci_lower} and \code{hdci_upper} (highest density
continuous interval bounds at the level specified by
\code{prob}), and \code{n_eff} (effective sample size for the
parameter).}
\item{item_information}{A \code{\link[tibble]{tibble}} with one
row per item containing: \code{item}, \code{location} (mean
item location, i.e. mean of thresholds for polytomous items),
\code{info_at_location} (Fisher information at the item's own
location), and \code{max_info} (maximum Fisher information
across theta). For Rasch dichotomous items, both are 0.25.
For polytomous items, information depends on the number and
spacing of thresholds.}
\item{threshold_order}{(Polytomous models only) A
\code{\link[tibble]{tibble}} with one row per item containing:
\code{item}, \code{n_thresholds}, \code{ordered} (logical:
are all thresholds in ascending order?), and
\code{prob_disordered} (posterior probability that at least
one pair of adjacent thresholds is disordered, i.e.
\eqn{\tau_{k+1} \le \tau_k}). \code{NULL} for dichotomous
models.}
\item{person_sd}{A \code{\link[tibble]{tibble}} with one row
containing: \code{mean}, \code{sd}, \code{hdci_lower},
\code{hdci_upper} — the posterior summary of the person-level
standard deviation parameter \eqn{\sigma_\theta}.}
\item{draws_matrix}{(Only if \code{draws = TRUE}) A numeric
matrix with rows = thresholds (named
\code{"item[threshold]"}) and columns = posterior draws. For
dichotomous models, row names are item labels only.}
}
}
\description{
Extracts item difficulty (threshold) parameters from a fitted
Bayesian Rasch model. Returns a simple location table in both long
and wide formats, a full summary with posterior SEs and HDCIs,
item-level information, threshold ordering diagnostics, and
optionally the full posterior draws matrix.
}
\details{
\strong{Dichotomous models} with random item effects
(\code{response ~ 1 + (1 | item) + (1 | id)}) parameterise item
difficulty as \eqn{\delta_i = -(b_0 + r_i)} where \eqn{b_0} is
the global intercept and \eqn{r_i} is the item random effect.
Models with fixed item effects (\code{response ~ 0 + item +
(1 | id)}) parameterise difficulty as \eqn{\delta_i = -b_i}.

\strong{Polytomous (acat/PCM) models} with grouped thresholds
(\code{thres(gr = item)}) directly estimate item-specific
threshold parameters. Each row in the long output represents one
threshold within one item; each row in the wide output represents
one item.

\strong{Item information} is computed from the posterior mean
item parameters using the standard Rasch/PCM information
formulae:
\describe{
\item{Dichotomous}{
\eqn{I_i(\theta) = P_i(\theta) Q_i(\theta)} where
\eqn{P_i = \text{logistic}(\theta - \delta_i)}.}
\item{Polytomous (PCM)}{
\eqn{I_i(\theta) = \sum_c (c - E_i)^2 P_{ic}(\theta)} where
\eqn{E_i = \sum_c c \cdot P_{ic}} is the expected score for
item \eqn{i}.}
}

\strong{Threshold ordering}: In the partial credit model,
disordered thresholds (\eqn{\tau_{k+1} \le \tau_k}) indicate that
the probability of responding in the intermediate category never
exceeds both adjacent categories — the category is empirically
"absorbed". This does not necessarily indicate misfit (see
Adams et al., 2012), but may suggest response categories should
be collapsed. The \code{prob_disordered} column reports the
posterior probability of at least one disordered pair per item,
providing a Bayesian alternative to post-hoc threshold checks.
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)

# --- 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 = 2, iter = 1000 # use more iter and cores
)

ip <- item_parameters(fit_pcm)

# Long format: one row per threshold
ip$locations

# Wide format: one row per item, easy to scan
ip$locations_wide

# Full summary with SE and HDCI
ip$summary

# Item information
ip$item_information

# Threshold ordering diagnostic
ip$threshold_order

# Person SD
ip$person_sd

# With full posterior draws
ip_draws <- item_parameters(fit_pcm, draws = TRUE)
dim(ip_draws$draws_matrix)

# --- Dichotomous Rasch ---

df_rm <- eRm::raschdat3 \%>\%
  as.data.frame() \%>\%
  rownames_to_column("id") \%>\%
  pivot_longer(!id, names_to = "item", values_to = "response")

fit_rm <- brm(
  response ~ 1 + (1 | item) + (1 | id),
  data   = df_rm,
  family = bernoulli(),
  chains = 4, cores = 2, iter = 1000 # use more iter and cores
)

ip_rm <- item_parameters(fit_rm)
# Wide and long are equivalent for dichotomous:
ip_rm$locations
ip_rm$locations_wide
ip_rm$summary
}

}
\references{
Adams, R. J., Wu, M. L., & Wilson, M. (2012). The Rasch rating
model and the disordered threshold controversy. \emph{Educational
and Psychological Measurement}, \emph{72}(4), 547--573.
\doi{10.1177/0013164411432166}

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{person_parameters}}, \code{\link{plot_targeting}},
\code{\link{plot_ipf}}, \code{\link{posterior_to_prior}}.
}
