% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mc.R
\name{distractor_rescore}
\alias{distractor_rescore}
\title{Propose polytomous option scores from the distractor evidence}
\usage{
distractor_rescore(fit, items = NULL, min_n = 20, z = 1.96)
}
\arguments{
\item{fit}{A fitted object from \code{\link{rasch}} run with a \code{key}.}

\item{items}{Optional subset of keyed item names.}

\item{min_n}{Minimum takers for a distractor to be considered.}

\item{z}{Required separation, in standard errors, between a credited
distractor and the uncredited ones.}
}
\value{
A list of class \code{"rasch_rescore"}: \code{option_scores}, a
  data frame (\code{item}, \code{option}, \code{score}) ready for
  \code{rasch(key = )} and covering every observed option of the
  examined items, and \code{evidence}, the distractor analysis with the
  proposed scores and the separation z per option.
}
\description{
Multiple-choice items can be rescored polytomously so
that a distractor carrying information about the trait receives partial
credit (Andrich and Styles 2011). This function proposes such a scoring
from the rest-measure distractor analysis: within each keyed item, a
distractor qualifies for credit when it attracts at least \code{min_n}
takers, its takers' mean rest location exceeds that of the uncredited
distractors by more than \code{z} standard errors of the difference,
and it remains below the keyed option. Qualifying distractors are
ranked by mean location and scored 1, 2, ... below the keyed option's
top score. The result is a proposal for substantive review, not an
automatic decision: inspect \code{\link{plot_distractors}} and the item
content, edit as needed, then refit with
\code{rasch(raw_data, key = proposal$option_scores)}.
}
\examples{
set.seed(1); Np <- 600
th <- rnorm(Np)
raw <- sapply(seq(-0.5, 0.5, length.out = 4), function(d) {
  x <- vapply(th, function(b) sample(0:2, 1,
    prob = item_moments(b, c(d - 0.7, d + 0.7))$P), 0L)
  c("D", "B", "A")[x + 1]   # B is an informative distractor
})
colnames(raw) <- paste0("M", 1:4)
fit <- rasch(raw, key = setNames(rep("A", 4), colnames(raw)))
pr <- distractor_rescore(fit)
pr$option_scores
}
\references{
Andrich, D. and Styles, I. (2011). Distractors with
  information in multiple choice items: A rationale based on the Rasch
  model. Journal of Applied Measurement, 12, 67-95.
}
