% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dif_lr.R
\name{RMdifLR}
\alias{RMdifLR}
\title{DIF analysis via Andersen's likelihood-ratio test}
\usage{
RMdifLR(
  data,
  dif_var,
  model = c("auto", "PCM", "RM"),
  level = c("item", "threshold"),
  output = c("kable", "dataframe", "ggplot"),
  cutoff = 0.5,
  conf = 0.95,
  sort = FALSE
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses (non-negative
integers, 0-based). One column per item, one row per person. Person
IDs and grouping variables must not be included -- pass the grouping
variable separately via \code{dif_var}.}

\item{dif_var}{Vector of length \code{nrow(data)} (factor, character,
or numeric) defining the DIF grouping variable. Coerced to factor;
unused levels are dropped. Rows where \code{dif_var} is \code{NA} are
dropped with a message. Must result in at least 2 groups after
cleaning.}

\item{model}{One of \code{"auto"} (default), \code{"PCM"}, or
\code{"RM"}. \code{"auto"} fits \code{eRm::RM()} when the data are
dichotomous (max response = 1) and \code{eRm::PCM()} otherwise.
\code{"RM"} errors on polytomous data.}

\item{level}{One of \code{"item"} (default) or \code{"threshold"}.
\code{"item"} reports each item's mean threshold location per group;
\code{"threshold"} reports each individual threshold per group. For
dichotomous (RM) data the two views are equivalent (one threshold per
item).}

\item{output}{One of \code{"kable"} (default), \code{"dataframe"}, or
\code{"ggplot"}. The data.frame view always carries a
\code{Flagged} logical column; the kable view bolds flagged rows; the
ggplot view shows confidence intervals.}

\item{cutoff}{Numeric or \code{NULL}. Threshold (in logits) for the
\code{Flagged} column: a row is flagged when
\code{MaxDiff > cutoff}, where \code{MaxDiff} is the difference
between the largest and smallest per-group location for that item
(or threshold). Set to \code{NULL} to suppress flagging. Default
\code{0.5}.}

\item{conf}{Numeric in (0, 1). Confidence level used for the ggplot
error bars. Default \code{0.95}.}

\item{sort}{Logical. \code{kable} output only: sort rows by
\code{MaxDiff} (descending). Default \code{FALSE}.}
}
\value{
A data.frame, a \code{knitr_kable} object, or a \code{ggplot}
object, depending on \code{output}.

The data.frame has one row per item (\code{level = "item"}) or per
item x threshold (\code{level = "threshold"}), with columns
\code{Item} (and \code{Threshold} at threshold level), one numeric
column per group level, an \code{All} column for the unsplit fit,
\code{MaxDiff}, \code{Flagged} (when \code{cutoff} is non-\code{NULL}),
and matching \code{SE_*} columns.

The Andersen LR test result is attached as
\code{attr(result, "lr_test")} on the data.frame, in the kable
footnote, and in the ggplot caption (LR \eqn{\chi^2}, df, p-value).
}
\description{
Splits a Rasch model by an external grouping variable using
\code{eRm::LRtest()} and reports per-group item locations (or per-group
threshold locations) together with their standard errors. A single
function replaces the four legacy helpers (\code{RIdifTableLR},
\code{RIdifThreshTblLR}, \code{RIdifFigureLR}, \code{RIdifThreshFigLR}) by exposing the
two underlying axes -- \code{level} (item or threshold) and \code{output}
(data.frame, kable, or ggplot) -- as arguments. The same data
preparation pipeline feeds all six combinations.
}
\details{
The Partial Credit Model (PCM) is fitted by default for polytomous data
and the dichotomous Rasch Model (RM) is fitted when all responses are
0/1; this can be overridden via \code{model}.

For the data.frame and kable outputs, locations are reported on the
centred eRm parameterisation returned by \code{eRm::thresholds()}.
Per-group fits come from \code{eRm::LRtest(..., splitcr = dif_var)};
the unsplit fit (\code{All} column) is the model fitted to the full
dataset. The Andersen LR statistic, df, and p-value reported as the
\code{lr_test} attribute / caption come directly from
\code{LRtest()}'s return value.

\code{cell_spec()}-style HTML cell colouring used in the legacy
easyRasch package has been dropped in favour of a logical
\code{Flagged} column (and bold rendering in the kable output), so the
kable renders correctly in HTML, LaTeX, and pipe/markdown.
}
\examples{
\donttest{
if (requireNamespace("eRm", quietly = TRUE)) {
  set.seed(1)
  data("pcmdat2", package = "eRm")
  grp <- factor(sample(c("A", "B"), nrow(pcmdat2), replace = TRUE))

  # Default: kable of per-group item locations
  RMdifLR(pcmdat2, dif_var = grp)

  # ggplot panel of item locations with 95\% CIs
  RMdifLR(pcmdat2, dif_var = grp, output = "ggplot")

  # Threshold-level kable, sorted by MaxDiff
  RMdifLR(pcmdat2, dif_var = grp, level = "threshold", sort = TRUE)

  # Tidy data.frame for downstream use
  df <- RMdifLR(pcmdat2, dif_var = grp, output = "dataframe")
  attr(df, "lr_test")
  df[df$Flagged, ]
}
}

}
