forced_choice_data_conversion: Forced-Choice Data Conversion Formats

In ForceChoice: Forced-Choice Modeling Based on Item Response Theory and Cognitive Diagnostic Models

Forced-Choice Data Conversion Formats

Description

Documents the three data objects used by the forced-choice conversion helpers: human-readable data, block definitions block.items, and model-ready response matrices. This overview is intended as the starting point before using get.response.from.data, get.data.from.response, the TIRT-specific converters, or the FCDCM-specific converters.

Details

The package uses two layers of forced-choice representation:

data

An N \times B matrix or data frame that is easy to read and edit. Rows are persons and columns are forced-choice blocks. A cell records the observed ordering with item labels separated by ">". For example, "3>4>5" means item 3 was ranked above item 4, which was ranked above item 5.

block.items

A list of length B. Element b gives the item labels appearing in column b of data. This object is the bridge between column order in the data file and item rows in model parameter matrices such as Q.matrix.

response

The compact numeric representation consumed by model fitting code. Its meaning depends on the model family. For FCGGUM, FCMIRT, and FCGDINA, response is an N \times B matrix of 1-based pattern indices. For TIRT, response is an N \times P matrix of pairwise binary outcomes. For FCDCM, response is an N \times B binary matrix for two-item blocks.

Choosing a Converter

FCGGUM, FCMIRT, and FCGDINA

Use get.response.from.data to convert character strings to pattern indices, and get.data.from.response for the inverse conversion.

TIRT

Use get.response.from.data.TIRT and get.data.from.response.TIRT. TIRT expands each block to pairwise comparisons, so its response columns are pairs rather than block-level pattern numbers.

FCDCM

Use get.response.from.data.FCDCM and get.data.from.response.FCDCM. Each block has exactly two statements, so response = 1 means the first statement in block.items[[b]] was preferred and response = 0 means the second statement was preferred.

Recovering block.items

Use get.block.items.from.data for generic multi-item forced-choice data and get.block.items.from.data.FCDCM for FCDCM pair data. Recovery is only possible for item labels that actually appear in the observed strings.

Core Conventions

• The bth element of block.items always corresponds to the bth column of data or response.

• fc.type = "RANK" expects a complete ranking such as "3>4>5" for a three-item block.

• fc.type = "MOLE" expects a most-least string such as "3>5": item 3 is most preferred and item 5 is least preferred.

• fc.type = "PICK" expects a single most-preferred item such as "3".

• Generic FC pattern-index responses are 1-based. They are row numbers in the deterministic pattern matrix generated internally; see generate_fc_permutation_patterns for the public pattern generator.

• TIRT data should use consecutive item labels across blocks, for example list(1:2, 3:5, 6:8). This is the format returned by sim.data.TIRT and expected by the TIRT conversion routines.

See Also

get.block.items.from.data, get.response.from.data, get.data.from.response, get.response.from.data.TIRT, get.data.from.response.TIRT, get.response.from.data.FCDCM, get.data.from.response.FCDCM

Examples

# Generic FC conversion: response is a block-level pattern index.
block.items <- list(1:2, 3:5)
dat <- data.frame(
  block.1 = c("1>2", "2>1"),
  block.2 = c("3>4>5", "5>4>3"),
  stringsAsFactors = FALSE
)
resp <- get.response.from.data(dat, block.items, fc.type = "RANK")
resp
get.data.from.response(resp, block.items, fc.type = "RANK")

# TIRT conversion: response is pairwise 0/1 data.
tirt <- get.response.from.data.TIRT(dat, block.items, fc.type = "RANK")
tirt$response
get.data.from.response.TIRT(
  tirt$response, block.items, fc.type = "RANK",
  pairs.value = tirt$pairs.value
)

# FCDCM conversion: response is binary within each two-item block.
fcdcm.items <- list(c(1L, 3L), c(2L, 4L))
fcdcm.dat <- data.frame(
  block.1 = c("1>3", "3>1"),
  block.2 = c("2>4", "4>2"),
  stringsAsFactors = FALSE
)
fcdcm.resp <- get.response.from.data.FCDCM(fcdcm.dat, fcdcm.items)
fcdcm.resp$response
get.data.from.response.FCDCM(fcdcm.resp$response, fcdcm.items)

ForceChoice documentation built on Sept. 13, 2026, 1:06 a.m.