extract: S3 Methods: extract

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

S3 Methods: extract

Description

A generic S3 extractor function designed to retrieve internal components from fitted model objects produced by the ForceChoice package. This function provides a consistent interface across all eight model classes, allowing users to access estimated parameters, fit statistics, latent trait estimates, convergence diagnostics, and model configuration data without directly manipulating the internal list structure.

Usage

## S3 method for class 'MIRT'
extract(object, what, ...)

## S3 method for class 'MGPCM'
extract(object, what, ...)

## S3 method for class 'MGGUM'
extract(object, what, ...)

## S3 method for class 'FCMIRT'
extract(object, what, ...)

## S3 method for class 'FCDCM'
extract(object, what, ...)

## S3 method for class 'FCGDINA'
extract(object, what, ...)

## S3 method for class 'FCGGUM'
extract(object, what, ...)

## S3 method for class 'TIRT'
extract(object, what, ...)

Arguments

object	An object of one of the following classes: "MIRT" — Multidimensional IRT model. "MGPCM" — Multidimensional Generalized Partial Credit Model. "MGGUM" — Multidimensional Generalized Graded Unfolding Model. "FCMIRT" — Forced-Choice Multidimensional IRT model. "FCDCM" — Forced-Choice Diagnostic Classification Model. "FCGDINA" — Forced-Choice GDINA model. "FCGGUM" — Forced-Choice Generalized Graded Unfolding Model. "TIRT" — Thurstonian IRT for Forced-Choice.
what	A character string specifying the name of the component to extract. Valid choices depend on the class of object. See Details section for full listings.
...	Additional arguments passed to methods (currently ignored).

Details

This function supports extraction from the eight ForceChoice model classes. Below are the available components for each:

MIRT, MGPCM, MGGUM

Traditional (single-stimulus) models. Available components:

par

List (est, se, Rhat, free) of item parameter arrays.

theta

List (est, se, Rhat) of N \times D person parameter matrices.

Corr

List (est, se, Rhat) of D \times D inter-trait correlation matrices.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method ("stan" or "iStEM").

Q.matrix

The I \times D Q-matrix.

length.poly

Vector of category counts per item (MGPCM, MGGUM only).

stan.obj

The stanfit object (Stan only).

MCMC.obj

The MCMC extract list (Stan only).

iStEM

List of iStEM diagnostics (iStEM only).

call

The matched call.

arguments

List of arguments used for fitting.

FCMIRT, FCGGUM

Forced-choice models. In addition to the traditional-model components listed above, the following are available:

block.items

List of item indices in each block.

response

The N \times B forced-choice response matrix.

patterns

List of permissible ranking patterns per block.

patterns.total

List of all possible ranking patterns per block.

fc.type

Character vector of forced-choice formats ("RANK", "MOLE", "PICK").

FCDCM

Forced-Choice DCM. Available components:

par

List (est, se, Rhat, free) of block \eta parameter matrices (B \times 2).

delta

List (est, se, Rhat) of higher-order \delta parameters (D \times 2).

theta

List (est, se, Rhat) of N \times 1 higher-order trait estimates.

alpha

Posterior mean attribute profile (N \times D).

alpha.patterns

Full enumeration of 2^D attribute mastery patterns.

zeta.patterns

Condensation outputs for each pattern.

dcm.type

DCM condensation rule ("DINA" or "DINO").

response

The N \times B binary block response matrix.

block.items

List of two-statement blocks.

patterns

List of binary response patterns per block.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method.

Q.matrix

The I \times D Q-matrix.

stan.obj, MCMC.obj, iStEM, EM

Estimation backend objects.

call

The matched call.

arguments

List of arguments used for fitting.

FCGDINA

Forced-Choice GDINA. Available components:

delta

List (est, se, Rhat) of item-level CDM delta parameters.

alpha

Posterior attribute summaries, including posterior class probabilities when available.

alpha.patterns

Full enumeration of 2^D attribute mastery patterns.

design.matrix.list

Per-item CDM design matrices.

response, block.items, patterns, patterns.total, fc.type

Forced-choice data structures.

TIRT

Thurstonian IRT. Available components:

par

List (est, se, Rhat, free) of statement-level parameter matrices (I \times (D+1)).

theta

List (est, se, Rhat) of N \times D person parameter matrices.

gamma

List (est, se, Rhat, free) of pairwise \gamma parameters.

gamma.matrix

List (est, se, Rhat) of I \times I skew-symmetric \gamma matrices.

Corr

List (est, se, Rhat) of D \times D inter-trait correlation matrices.

pairs.matrix

Matrix of pairwise comparison indices.

pairs.value

Person-specific pair data (MOLE/PICK).

response

The N \times I_{pairs} pairwise response matrix.

block.items

List of item indices in each block.

fc.type

Character vector of forced-choice formats.

Q.matrix

The statement-level Q-matrix.

logLik

Marginal log-likelihood (class "logLik").

npar

Number of free parameters.

method

Estimation method.

stan.obj, MCMC.obj, iStEM

Estimation backend objects.

call

The matched call.

arguments

List of arguments used for fitting.

Value

The requested component. Return type varies depending on what and the class of object. If an invalid what is provided, an informative error is thrown listing valid options.

Methods (by class)

• extract(MIRT): Extract components from MIRT objects.

• extract(MGPCM): Extract components from MGPCM objects.

• extract(MGGUM): Extract components from MGGUM objects.

• extract(FCMIRT): Extract components from FCMIRT objects.

• extract(FCDCM): Extract components from FCDCM objects.

• extract(FCGDINA): Extract components from FCGDINA objects.

• extract(FCGGUM): Extract components from FCGGUM objects.

• extract(TIRT): Extract components from TIRT objects.

Examples

sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)

extract(fit, "par")       # item parameter estimates
extract(fit, "theta")     # person trait estimates
extract(fit, "Corr")      # factor correlation matrix
extract(fit, "npar")      # number of free parameters
extract(fit, "logLik")    # marginal log-likelihood
extract(fit, "iStEM")     # iStEM convergence diagnostics

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