% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item_parameters.R
\name{RMitemParameters}
\alias{RMitemParameters}
\title{Item Parameters for a Rasch / Partial Credit Model}
\usage{
RMitemParameters(
  data,
  estimator = c("CML", "MML"),
  format = c("long", "wide"),
  se = TRUE,
  ci_level = 0.95,
  center = TRUE,
  output = c("kable", "dataframe", "file"),
  filename = NULL
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses. Items must be
scored starting at 0 (non-negative integers). Missing values (\code{NA})
are allowed; both estimators handle them.}

\item{estimator}{Character. \code{"CML"} (default) estimates item
parameters with \code{\link[psychotools:pcmodel]{psychotools::pcmodel()}} (a dichotomous item is a
2-category PCM); \code{"MML"} uses \code{\link[mirt:mirt]{mirt::mirt()}} with
\code{itemtype = "Rasch"}. CML is preferred for
Rasch measurement; MML can be more robust when data are sparse.
When \code{estimator = "CML"} and sparse response categories are
detected, a warning suggests switching to MML.}

\item{format}{Character. \code{"long"} (default) returns one row per item
(dichotomous) or per item-threshold (polytomous); \code{"wide"} returns
one row per item with threshold columns \code{t1}, \code{t2}, ... plus a mean
\code{location} column.}

\item{se}{Logical. If \code{TRUE} (default), standard-error and
confidence-interval columns are added.}

\item{ci_level}{Numeric in (0, 1). Confidence level for the Wald
interval (\verb{estimate +/- z * SE}). Default \code{0.95}.}

\item{center}{Logical. If \code{TRUE} (default), all thresholds are shifted
so their grand mean is zero, the usual Rasch identification. CML
estimates are already centred; the shift mainly affects the MML
path, keeping the two estimators on a common scale.}

\item{output}{Character. \code{"kable"} (default) for a formatted
\code{\link[knitr:kable]{knitr::kable()}} table, \code{"dataframe"} for the underlying
data.frame, or \code{"file"} to write that data.frame to a CSV at
\code{filename} (the data.frame is also returned invisibly).}

\item{filename}{Character. Path to the CSV file to write when
\code{output = "file"}. Required in that case; ignored otherwise.}
}
\value{
For \code{output = "dataframe"}, a data.frame. In \strong{long} format the
columns are \code{item}, \code{threshold} (integer; \code{1} for dichotomous items),
\code{location}, and -- when \code{se = TRUE} -- \code{se}, \code{ci_lower}, \code{ci_upper}.
In \strong{wide} format the columns are \code{item}, the threshold locations
(\code{t1}, \code{t2}, ... or \code{location} for dichotomous items), and a mean
\code{location}; when \code{se = TRUE}, matching \code{se_t1}, \code{se_t2}, ... columns
are appended. For \code{output = "kable"}, the same content as a
\code{knitr_kable} object.
}
\description{
Estimates item difficulty (dichotomous) or item-category threshold
(polytomous) parameters and returns them in long or wide format, with
optional standard errors and Wald confidence intervals. Item
parameters are estimated by conditional maximum likelihood (CML, via
\pkg{psychotools}) by default, with marginal maximum likelihood (MML, via
\pkg{mirt}) available for sparse data where CML can be unstable.
}
\details{
Items are detected as dichotomous (maximum score 1) or polytomous
(maximum score > 1), and the Rasch or Partial Credit model is chosen
accordingly. Thresholds are reported as Andrich thresholds (the
person locations at which adjacent response categories are equally
probable) on the logit difficulty scale, matching \code{\link[=RMtargeting]{RMtargeting()}}.

\strong{Standard errors.} For the CML path, threshold SEs are the
square roots of the diagonal of the threshold-parameter covariance from
\code{psychotools::threshpar(vcov = TRUE)}. For the MML path, SEs come from
the \pkg{mirt} parameter covariance, propagated by the delta method
through the linear threshold map.
Confidence intervals are Wald intervals and are symmetric on the
logit scale.
}
\examples{
\donttest{
set.seed(1)
poly <- as.data.frame(
  matrix(sample(0:2, 250 * 5, replace = TRUE), nrow = 250, ncol = 5)
)
colnames(poly) <- paste0("Item", 1:5)

# Default: long-format kable with SE and 95\% CI
RMitemParameters(poly)

# Wide format, point estimates only
RMitemParameters(poly, format = "wide", se = FALSE, output = "dataframe")

# Dichotomous data
dich <- as.data.frame(
  matrix(sample(0:1, 250 * 6, replace = TRUE), nrow = 250, ncol = 6)
)
colnames(dich) <- paste0("Item", 1:6)
RMitemParameters(dich, output = "dataframe")

# Write the parameter table to a CSV (also returned invisibly)
RMitemParameters(poly, output = "file",
                 filename = tempfile(fileext = ".csv"))
}
}
\references{
Andrich, D. (1978). A rating formulation for ordered response
categories. \emph{Psychometrika, 43}(4), 561-573.
\doi{10.1007/BF02293814}

Mair, P., & Hatzinger, R. (2007). Extended Rasch modeling: The eRm
package for the application of IRT models in R. \emph{Journal of
Statistical Software, 20}(9), 1-20. \doi{10.18637/jss.v020.i09}
}
\seealso{
\code{\link[=RMpersonParameters]{RMpersonParameters()}}, \code{\link[=RMscoreSE]{RMscoreSE()}}, \code{\link[=RMtargeting]{RMtargeting()}}
}
