% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/person_parameters.R
\name{person_parameters}
\alias{person_parameters}
\title{Extract Person Parameters from a Bayesian Rasch Model}
\usage{
person_parameters(
  model,
  item_var = item,
  person_var = id,
  draws = FALSE,
  center = TRUE,
  theta_range = c(-7, 7)
)
}
\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 matrix of full posterior
draws (persons x draws) is included in the output. Default is
\code{FALSE}.}

\item{center}{Logical. If \code{TRUE} (the default), person
parameters and item difficulties are recentered so that the
mean item difficulty is zero, matching the convention in
frequentist CML Rasch estimation. If \code{FALSE}, raw brms
parameterisation is used.}

\item{theta_range}{A numeric vector of length 2 specifying the
range for the Newton-Raphson WLE search. Default is
\code{c(-7, 7)}.}
}
\value{
A list with the following elements:
\describe{
\item{person_estimates}{A \code{\link[tibble]{tibble}} with one
row per person containing: the person ID, \code{sum_score},
\code{eap} (posterior mean of person random effect),
\code{eap_se} (posterior SD), \code{wle} (Warm's weighted
likelihood estimate), and \code{wle_se} (asymptotic SE
of the WLE). Rows are ordered to match the original person
order in the model data (i.e., the order of first appearance
of each person ID).}
\item{score_table}{A \code{\link[tibble]{tibble}} mapping each
observed ordinal sum score to its mean EAP, mean EAP SE,
WLE, and WLE SE. Extreme scores (0 and maximum) receive
WLE estimates at the boundary of \code{theta_range} with
\code{NA} standard errors.}
\item{draws_matrix}{(Only if \code{draws = TRUE}) A numeric
matrix with rows = persons and columns = posterior draws.
Row names are person IDs. Rows are ordered to match the
original person order in the model data. Can be passed
directly to \code{\link{RMUreliability}}.}
}
}
\description{
Extracts person ability estimates from a fitted Bayesian Rasch
model. Returns both Bayesian EAP (expected a posteriori) estimates
with posterior SDs and frequentist WLE (Warm's weighted likelihood)
estimates with standard errors, plus a lookup table mapping ordinal
sum scores to both scales.
}
\details{
\strong{EAP estimates} are extracted as the posterior means of
the person random effects (\code{r_id[j, Intercept]}) from
\code{\link[brms]{as_draws_df}}, with the posterior SD serving
as the standard error. These are the standard Bayesian point
estimates and reflect shrinkage toward the population mean.

\strong{WLE estimates} (Warm, 1989) are computed from the
posterior mean item parameters using Newton-Raphson iteration
with adaptive step damping on the Warm-corrected likelihood.
WLE adds a bias correction term \eqn{J(\theta) / (2 I(\theta))}
to the score equations, where \eqn{I(\theta)} is the test
information and \eqn{J(\theta) = \sum_i \sum_c (c - E_i)^3 P_{ic}}
is the sum of third central moments. This produces estimates with
reduced finite-sample bias compared to MLE, especially at
extreme scores (Warm, 1989).

The Newton-Raphson algorithm uses adaptive step damping following
the approach in \pkg{iarm} (Mueller): the maximum allowed step
size shrinks by a factor of 1.05 each iteration, preventing
overshoot and ensuring convergence for near-extreme scores.

For extreme scores (sum score = 0 or maximum possible), the
WLE is not well-defined. These cases are assigned the boundary
values of \code{theta_range} with \code{NA} standard errors.

When \code{center = TRUE} (the default), item difficulty
parameters are shifted so their mean is zero, and EAP person
parameters are shifted by the same constant. WLE is computed
from the centered item parameters. This matches the convention
in frequentist CML Rasch estimation.

\strong{Row ordering:} Both \code{person_estimates} and
\code{draws_matrix} preserve the original person order from
the model data (order of first appearance of each person ID).
This allows direct row-binding with the source data without
re-matching.
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)

# --- Dichotomous Rasch Model (random items) ---

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
)

# Basic usage — rows match original person order
pp <- person_parameters(fit_rm)
pp$person_estimates
pp$score_table

# With full posterior draws (e.g., for RMUreliability)
pp_draws <- person_parameters(fit_rm, draws = TRUE)
RMUreliability(pp_draws$draws_matrix)

# --- Polytomous PCM (acat) ---

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
)

pp_pcm <- person_parameters(fit_pcm)
pp_pcm$score_table
}

}
\references{
Warm, T. A. (1989). Weighted likelihood estimation of ability
in item response theory. \emph{Psychometrika}, \emph{54}(3),
427--450. \doi{10.1007/BF02294627}

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}

Christensen, K. B., Kreiner, S. & Mesbah, M. (Eds.) (2013).
\emph{Rasch Models in Health}. Iste and Wiley, pp. 63--70.
}
\seealso{
\code{\link{RMUreliability}}, \code{\link{plot_targeting}},
\code{\link[brms]{ranef}}, \code{\link[brms]{as_draws_df}}.
}
