% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/21_DistractorAnalysis.R
\name{DistractorAnalysis}
\alias{DistractorAnalysis}
\alias{DistractorAnalysis.LRArated}
\alias{DistractorAnalysis.ratedBiclustering}
\alias{print.DistractorAnalysis}
\alias{plot.DistractorAnalysis}
\title{Distractor Analysis}
\usage{
DistractorAnalysis(x, ...)

\method{DistractorAnalysis}{LRArated}(x, ...)

\method{DistractorAnalysis}{ratedBiclustering}(x, ...)

\method{print}{DistractorAnalysis}(x, items = NULL, ranks = NULL, digits = 4, ...)

\method{plot}{DistractorAnalysis}(x, type = "Distractor", items = NULL, ranks = NULL, nc = 1, nr = 1, ...)
}
\arguments{
\item{x}{A result object from a rated model (class \code{LRArated} or
\code{ratedBiclustering}).}

\item{...}{Additional arguments (currently unused).}

\item{items}{Integer vector of item indices to display. NULL for all items.}

\item{ranks}{Integer vector of rank/class indices to display. NULL for all ranks.}

\item{digits}{Number of digits for rounding. Default is 4.}

\item{type}{Plot type. Currently only "Distractor" is supported.}

\item{nc}{Number of columns in the plot grid.}

\item{nr}{Number of rows in the plot grid.}
}
\value{
An object of class \code{c("exametrika", "DistractorAnalysis")} containing:
\describe{
\item{freq_table}{List of frequency matrices (nrank x maxQ), one per item.}
\item{prop_table}{List of proportion matrices (nrank x maxQ), one per item.}
\item{chisq_table}{Matrix (nitems x nrank) of chi-square statistics.}
\item{pvalue_table}{Matrix (nitems x nrank) of p-values.}
\item{cramersv_table}{Matrix (nitems x nrank) of Cramer's V effect sizes.}
\item{CA}{Correct answer vector.}
\item{n_rank}{Number of ranks/classes.}
\item{maxQ}{Number of response categories.}
\item{nitems}{Number of items.}
\item{ItemLabel}{Item label vector.}
\item{n_field}{Number of fields (Biclustering only).}
\item{FieldEstimated}{Field assignment vector (Biclustering only).}
\item{field_items}{List of item indices per field (Biclustering only).}
}
}
\description{
Performs distractor analysis for rated (multiple-choice) models.
For each item and rank/class, computes observed category frequency tables,
chi-square tests against chance level (uniform distribution), and
Cramer's V as an effect size measure.

This function works with results from \code{\link{LRA}} (rated data) and
\code{\link{Biclustering}} / \code{\link{Biclustering_IRM}} (rated data).
}
\examples{
\donttest{
# LRA.rated example
result_lra <- LRA(J21S300, nrank = 5, mic = TRUE)
da <- DistractorAnalysis(result_lra)
print(da)
print(da, items = 1:3)
print(da, ranks = c(1, 5))
plot(da)
plot(da, items = 1:6, nc = 3, nr = 2)

# Biclustering.rated example
result_bic <- Biclustering(J21S300, ncls = 5, nfld = 3, method = "R")
da_bic <- DistractorAnalysis(result_bic)
print(da_bic, items = 1:7)
plot(da_bic, items = 1:6, nc = 3, nr = 2)
}

}
