% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimation.R
\name{pcml_pc}
\alias{pcml_pc}
\title{Estimate Rasch thresholds via the Andrich principal-components reparameterisation}
\usage{
pcml_pc(X, n_components = 4, maxit = 60, tol = 1e-08)
}
\arguments{
\item{X}{Persons-by-items integer score matrix (categories from 0).
Missing values are handled by pairwise deletion.}

\item{n_components}{Maximum number of components per item: 1 (location
only) up to 4 (location, spread, skewness, kurtosis; the highest
derived by Pedler 1987). Capped per item at its own number of
thresholds, and further wherever a component would be collinear with
lower-order ones for that item's threshold count (kurtosis is
unidentified, and dropped, at exactly 4 thresholds).}

\item{maxit, tol}{Newton-Raphson iteration cap and convergence tolerance.}
}
\value{
A list with the threshold table \code{thr} (columns \code{id},
  \code{item}, \code{k}, \code{tau}, \code{se}), the component table
  \code{components} (one row per item, with \code{location},
  \code{spread}, \code{skewness}, \code{kurtosis} and their standard
  errors, \code{NA} where an item's rank does not support that
  component), the threshold covariance matrix \code{cov_tau}, the
  pairwise conditional log-likelihood, the iteration count, a convergence
  flag, and the max-score vector \code{m}.
}
\description{
An optional alternative to \code{\link{pcml}}'s free-threshold estimation,
useful when some response categories are sparsely populated. Each item's
thresholds are re-expressed as up to four orthogonal polynomial
components in the category score: location, spread, skewness, and
kurtosis (Andrich 1978, 1985; Pedler 1987). Location is always estimated;
spread, skewness, and kurtosis are added in turn as an item's number of
thresholds and \code{n_components} allow. Estimation uses the same
pairwise conditional likelihood as \code{pcml} (Andrich and Luo 2003), so
it inherits the same missing-data handling and sandwich standard errors.
The component family stops at the quartic (kurtosis) term, so the
reparameterisation is exact, matching \code{pcml}'s free partial credit
thresholds and log-likelihood, only while every item has at most 3
thresholds (4 categories); from 4 thresholds on \code{pcml_pc} is
necessarily a reduced-rank smoothing of the thresholds to a polynomial
trend across categories, however large \code{n_components} is set,
trading flexibility for the stability that comes from pooling information
across all of an item's categories -- useful when a category has low or
zero frequency.
}
\examples{
set.seed(1)
d <- seq(-1.5, 1.5, length.out = 6)
X <- matrix(rbinom(400 * 6, 1, plogis(outer(rnorm(400), d, "-"))), 400, 6)
colnames(X) <- paste0("I", 1:6)
pcml_pc(X)$components
}
