irtc_read_q: Read a Q Matrix from a File and Align It with the Response...

In IRTC: Marginal Maximum Likelihood Estimation for Item Response Models

Read a Q Matrix from a File and Align It with the Response Data

Description

irtc_read_q reads a Q (item-by-dimension) matrix from any file format supported by irtc_read (Excel, delimited text, SPSS/Stata/SAS) or from a data frame / matrix. The dimension column headers become the dimension names used in all downstream person-level output (ability and standard-error headers). An optional partial-credit column declares which items are scored in multiple levels, and optionally their maximum scores.

irtc_align_q compares the Q-matrix items with the response-data items. By default mismatches raise warnings (W420, W421) and the analysis continues with the shared items; on_mismatch = "error" turns any mismatch into an error (E422).

Usage

irtc_read_q(x, sheet = 1)

irtc_align_q(data, q, on_mismatch = c("warn", "error"))

## S3 method for class 'irtc_qmatrix'
print(x, lang = irtc_lang(), ...)

Arguments

x	A file path, data frame, or numeric matrix with item rownames. For the print method: an irtc_qmatrix object.
sheet	Excel sheet to read (number or name).
data	An irtc_data object (from irtc_read), data frame or matrix of item responses.
q	An irtc_qmatrix object, or anything accepted by irtc_read_q.
on_mismatch	"warn" (default): report item mismatches as warnings and continue with the shared items. "error": stop on any mismatch.
lang	Output language, "zh" or "en".
...	Ignored.

Details

Expected table layout for irtc_read_q:

• An item-ID column named item, item_id, \zh题目\u9898\u76ee, \zh题号\u9898\u53f7 (etc.); if no such name is found, the first non-numeric column is used.

• One or more numeric dimension columns; each header is a dimension name (e.g. \zh代数\u4ee3\u6570, algebra). Values are usually 0/1 loadings. Empty cells count as 0. Every item must load on at least one dimension.

• Optionally one partial-credit column named partial, max_score, \zh分部计分\u5206\u90e8\u8ba1\u5206, \zh满分\u6ee1\u5206 (etc.). Values may be 0/1, TRUE/FALSE, yes/no, \zh是\u662f/\zh否\u5426, or integer maximum scores (a value >= 2 declares a partial-credit item and records its maximum score).

Value

irtc_read_q returns an object of class irtc_qmatrix: a list with components Q (numeric item-by-dimension matrix with dimnames), partial (named logical vector), max_score (named integer vector, NA when not declared), log and source.

irtc_align_q returns a list with components data (the input data restricted to the shared items), q (the aligned irtc_qmatrix, rows in data column order), common, q_only and data_only (character vectors of item names).

See Also

irtc, irtc_read

Examples

qdf <- data.frame(item = c("I1", "I2", "I3"),
    algebra = c(1, 1, 0), geometry = c(0, 0, 1),
    partial = c(0, 1, 0))
qm <- irtc_read_q(qdf)
print(qm, lang = "en")

resp <- data.frame(I1 = c(0, 1), I2 = c(2, 0), I4 = c(1, 1))
al <- suppressWarnings(irtc_align_q(resp, qm))
al$q_only
al$data_only

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