% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conditional_infit_mi.R
\name{RMitemInfitMI}
\alias{RMitemInfitMI}
\title{Conditional Item Infit MSQ for Multiply Imputed Data}
\usage{
RMitemInfitMI(mids_object, cutoff = NULL, output = "kable", sort)
}
\arguments{
\item{mids_object}{A \code{mids} object (multiply imputed dataset) as returned by
\code{mice::mice()}. Each completed dataset must contain only the item response
columns to be analysed (i.e., no ID or grouping variables). Items must be
scored starting at 0 (non-negative integers).}

\item{cutoff}{Optional. Default \code{NULL} (no cutoff applied). Can be:
\itemize{
\item The return value of \code{\link{RMitemInfitCutoff}} or
\code{\link{RMitemInfitCutoffMI}} (a list with \verb{$item_cutoffs}): the
data.frame is extracted automatically and metadata is included in the
kable caption.
\item The \verb{$item_cutoffs} data.frame directly: must have columns \code{Item},
\code{infit_low}, and \code{infit_high}.
When provided, adds columns \code{Infit_low}, \code{Infit_high}, and \code{Flagged} to
the result. \code{Flagged} is a character column labelling the misfit
direction: \code{"overfit"} (pooled infit below the range), \code{"underfit"}
(above), or \code{""} (within range).
}}

\item{output}{Character string controlling the return value. Either
\code{"kable"} (default) for a formatted \code{knitr::kable()} table, or
\code{"dataframe"} for the underlying data.frame.}

\item{sort}{Optional character string. When \code{sort = "infit"}, rows are
sorted by \code{Infit_MSQ} in descending order before output.}
}
\value{
\itemize{
\item If \code{output = "kable"}: a \code{knitr_kable} object (plain text table via
\code{format = "pipe"}) with columns "Item", "Infit MSQ", "Infit SE",
"Relative location", and a caption noting the number of imputations and
complete cases. When \code{cutoff} is provided, columns "Infit low",
"Infit high", and "Flagged" are also included.
\item If \code{output = "dataframe"}: a data.frame with columns \code{Item},
\code{Infit_MSQ}, \code{Infit_SE}, and \code{Relative_location}. When \code{cutoff} is
provided, columns \code{Infit_low}, \code{Infit_high}, and \code{Flagged} are also
included (inserted after \code{Infit_SE}, before \code{Relative_location}).
\code{Flagged} is a character column (\code{"overfit"} / \code{"underfit"} / \code{""}),
not the previous logical.
}
}
\description{
Extends \code{\link{RMitemInfit}} to work with multiply imputed datasets
produced by the \code{mice} package. Computes conditional infit MSQ on each
imputed dataset and pools the results using Rubin's rules.
}
\details{
For each of the \code{m} imputed datasets, the function:
\enumerate{
\item Fits a Rasch model by CML via \code{psychotools::pcmodel()} (a
dichotomous item is a 2-category partial credit model), consistent with
\code{\link{RMitemInfit}} and the rest of the package.
\item Computes conditional infit MSQ and its standard error via
\code{iarm::out_infit()}.
\item Computes item locations (mean of the grand-mean-centred CML
Andrich thresholds) and the mean WLE person location.
}

The per-imputation estimates are then pooled using Rubin's rules:
\describe{
\item{Pooled MSQ}{The mean of the \code{m} infit MSQ point estimates.}
\item{Within-imputation variance}{The mean of the \code{m} squared standard
errors.}
\item{Between-imputation variance}{The sample variance of the \code{m} point
estimates.}
\item{Total variance}{Within + (1 + 1/m) * Between.}
\item{Pooled SE}{The square root of the total variance.}
}

Relative item location is the mean of per-imputation relative locations
(item location minus sample mean person location).

\strong{Caveat on the pooled SE.} The within-imputation variance is the
squared conditional infit SE from \code{iarm::out_infit()}. Müller (2020) showed
that this asymptotic SE is an unreliable measure of uncertainty for the
conditional infit statistic; Rubin's pooled SE inherits that limitation, so
the \code{Infit_SE}/\verb{Infit SE} column should be read as an approximate indication
of imputation-related variability rather than a trustworthy inferential
standard error. For item misfit decisions, prefer the simulation-based
cutoffs from \code{\link{RMitemInfitCutoffMI}}.

Imputed datasets that cause model convergence failures are dropped with a
warning. If all imputations fail, the function stops with an error. At
least two successful imputations are required to estimate between-imputation
variance.

The \code{mice} and \code{iarm} packages must be installed (they are in Suggests, not
Imports).
}
\examples{
\donttest{
if (requireNamespace("mice", quietly = TRUE) &&
    requireNamespace("iarm", quietly = TRUE) &&
    requireNamespace("ggdist", quietly = TRUE)) {
  # Create example data with ~10\% MCAR missingness
  set.seed(42)
  mat <- matrix(sample(0:1, 200 * 8, replace = TRUE), nrow = 200, ncol = 8)
  mat[sample(length(mat), round(0.10 * length(mat)))] <- NA
  sim_data <- as.data.frame(mat)
  colnames(sim_data) <- paste0("Item", 1:8)

  # mice's ordinal method (`polr`) requires the items to be ordered
  # factors, so code them as such before imputing. RMitemInfitMI()
  # converts the completed factors back to numeric internally.
  sim_data[] <- lapply(sim_data, function(x) factor(x, ordered = TRUE))

  # Impute (use more imputations, e.g. m = 5+, in real analyses)
  imp <- mice::mice(sim_data, m = 2, method = "polr", seed = 123,
                    printFlag = FALSE)

  # Pooled infit table (no cutoffs)
  RMitemInfitMI(imp)

  # With simulation-based cutoffs
  # (use more iterations, e.g. 250+, in real analyses)
  cutoff_mi <- RMitemInfitCutoffMI(imp, iterations = 50, parallel = FALSE,
                                seed = 42)
  RMitemInfitMI(imp, cutoff = cutoff_mi)

  # As data.frame
  df <- RMitemInfitMI(imp, cutoff = cutoff_mi, output = "dataframe")
}
}
}
\references{
Müller, M. (2020). Item fit statistics for Rasch analysis: Can we trust
them? \emph{Journal of Statistical Distributions and Applications}, 7(5).
\doi{10.1186/s40488-020-00108-7}
}
\seealso{
\code{\link{RMitemInfit}}, \code{\link{RMitemInfitCutoffMI}}
}
