% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dif.R
\name{dif}
\alias{dif}
\title{Differential Item Functioning (Mantel-Haenszel and Logistic Regression)}
\usage{
dif(data, group, focal = NULL, match = NULL, purify = FALSE)
}
\arguments{
\item{data}{A data frame of dichotomous (0/1) item responses (rows = persons,
columns = items).}

\item{group}{A vector of length equal to the number of rows in \code{data}
giving the group membership of each person. It must have exactly two
distinct non-missing values.}

\item{focal}{Optional. The value of \code{group} that identifies the focal
group. If \code{NULL} (default), the second value (in sorted order) is used
as the focal group and the first as the reference group.}

\item{match}{Optional numeric vector of matching scores (length equal to the
number of rows in \code{data}). If \code{NULL} (default), the total number-
correct score across all items is used.}

\item{purify}{Logical. If \code{TRUE}, the matching total score is computed
as the rest score (total minus the studied item) separately for each item,
which avoids contaminating the match with the item under study (default
\code{FALSE}).}
}
\value{
A data frame with one row per item and the columns:
\itemize{
\item \code{item}: the item name.
\item \code{MH_chisq}, \code{MH_p}: the Mantel-Haenszel chi-square (with
continuity correction) and its p-value.
\item \code{MH_OR}: the Mantel-Haenszel common odds ratio.
\item \code{MH_delta}: the ETS delta effect size, \eqn{-2.35 \ln(OR)}.
\item \code{ETS_class}: the ETS DIF classification, \code{"A"} (negligible),
\code{"B"} (moderate), or \code{"C"} (large).
\item \code{LR_chisq}, \code{LR_p}: the 2-degree-of-freedom logistic
regression test for combined (uniform + non-uniform) DIF.
\item \code{LR_uniform_p}: p-value for uniform DIF (group main effect).
\item \code{LR_nonuniform_p}: p-value for non-uniform DIF (group-by-match
interaction).
}
}
\description{
Detects Differential Item Functioning (DIF) for dichotomous items, that is,
items that behave differently for two groups of examinees (for example, a
reference and a focal group) after matching on ability. Two widely used
approaches are provided: the Mantel-Haenszel (1959) procedure, with the ETS
delta effect size and A/B/C flagging scheme (Holland & Thayer, 1988), and the
logistic regression approach (Swaminathan & Rogers, 1990), which separates
uniform and non-uniform DIF.
}
\examples{
  set.seed(123)
  sim <- sim_irt(n_people = 600,
                 item_structure = list(list(model = "2PL", n_items = 10)))
  resp <- sim$resp

  # Create two groups and plant DIF in item 3 (harder for group "B")
  grp <- rep(c("A", "B"), each = 300)
  flip <- grp == "B" & resp[[3]] == 1
  resp[[3]][flip] <- rbinom(sum(flip), 1, 0.6)

  dif_res <- dif(resp, group = grp)
  dif_res
}
\references{
Holland, P. W., & Thayer, D. T. (1988). Differential item performance and the
Mantel-Haenszel procedure. In H. Wainer & H. I. Braun (Eds.), \emph{Test
validity} (pp. 129-145). Erlbaum.

Swaminathan, H., & Rogers, H. J. (1990). Detecting differential item
functioning using logistic regression procedures. \emph{Journal of
Educational Measurement, 27}(4), 361-370.
}
