irtc: One-Stop Item Response Model Estimation

In IRTC: Marginal Maximum Likelihood Estimation for Item Response Models

One-Stop Item Response Model Estimation

Description

Reads data from a file or R object, cleans it, optionally scores raw multiple-choice responses against an answer key, checks it, estimates the requested item response model and enriches the result with classical item statistics, item fit and plain-language quality ratings.

Designed for non-specialists and automated callers; professional users keep full control because all additional arguments are passed unchanged to irtc.mml (for "1PL", "PCM", "PCM2", "RSM") or irtc.mml.2pl (for "2PL", "GPCM").

Usage

irtc(data, model, key = NULL, rules = NULL, q = NULL,
    on_mismatch = c("warn", "error"),
    rare_categories = c("collapse", "prior"), id = NULL, weights = NULL,
    sheet = 1, missing_codes = c(-9, -99, 99, 999), check = TRUE,
    quality = TRUE, verbose = TRUE, ...)

Arguments

data	A file path (.xlsx, .xls, .csv, .tsv, .txt, .dat, .sav, .por, .dta, .sas7bdat, .xpt), a data frame, a matrix, or an object returned by irtc_read.
model	Required. One of "1PL" (alias "Rasch"), "2PL", "PCM", "PCM2", "RSM", "GPCM". Case-insensitive.
key	An optional answer key for raw responses: a named vector or a key-file path (optionally with a partial-answer column); see irtc_score.
rules	An optional partial-credit scoring table or a path to one; see irtc_score.
q	An optional Q (item-by-dimension) matrix: a file path, data frame, matrix, or an object from irtc_read_q. The Q matrix is aligned with the data via irtc_align_q and passed to the estimation as Q; its dimension names label the person-level output. If Q is also supplied through ..., the explicit Q wins and a warning (W419) is raised.
on_mismatch	How to handle items that differ between the Q matrix and the data; see irtc_align_q.
rare_categories	How to handle score categories nobody reached (nobody fully correct / partially correct / wrong). "collapse" (default): merge unobserved categories into their lower neighbour; the mapping is logged (W425) and annotated in the item output (categories_unobserved, categories_collapsed, declared vs observed maximum score). "prior": keep the observed category structure; thresholds of in-range empty categories get a N(0, 4) prior (models "1PL", "PCM") or are fixed at the prior mean 0 (models "2PL", "GPCM", whose estimation core does not evaluate priors); such thresholds are marked prior_dominated in the output. Categories above the observed maximum have no parameter in either mode and are reported as a reduced maximum score. Items answered by nobody are removed (W410) but keep an annotated row in irtc_results.
id	An optional person identifier column (name or index); passed to irtc_read.
weights	An optional sampling weight column (name or index); passed to irtc_read. Common weight column names are also detected automatically. The weights are used as pweights in the estimation; if pweights is also supplied through ..., the explicit pweights wins and a warning (W418) is raised.
sheet	Excel sheet to read (number or name).
missing_codes	Numeric values recoded to NA during cleaning; see irtc_read.
check	Logical: stop with a structured error if irtc_check_data finds any error-level issue?
quality	Logical: attach CTT statistics, item fit and quality ratings to the result?
verbose	Logical: print estimation progress?
...	Further arguments passed to irtc.mml or irtc.mml.2pl (e.g. group, pweights, Q, control).

Details

Items without any observed responses or without variance are removed before estimation (with a warning of class irtc_warning_estimation). All errors raised by the usability layer are structured conditions with fields code, reason and fix; see the package file inst/llms.txt for the full list of codes.

The language of user-facing output is controlled by options(irtc.lang = "zh") (default) or "en".

Value

An object of class irtc (see irtc.mml) with an additional list component usability containing model, data_log (cleaning log), check (the irtc_check_data result), removed_items, ctt, itemfit and quality.

See Also

irtc_read, irtc_check_data, plain_summary, irtc_excel, irtc_report, irtc_results

Examples

set.seed(1)
theta <- rnorm(150)
resp <- as.data.frame(sapply(seq(-1, 1, length.out = 5), function(b) {
    as.numeric(runif(150) < plogis(theta - b))
}))
colnames(resp) <- paste0("I", 1:5)

mod <- irtc(resp, model = "1PL", verbose = FALSE)
plain_summary(mod, lang = "en")
mod$usability$quality

IRTC documentation built on July 24, 2026, 5:07 p.m.