R/S3coef.R

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

#' @title S3 Methods: coef
#'
#' @description
#' Extract estimated model coefficients (item, statement, or block
#' parameters) from fitted \pkg{ForceChoice} model objects. This provides a
#' standard R interface for retrieving parameter estimates, standard errors,
#' and convergence diagnostics in a consistent format across all eight model
#' families.
#'
#' @param object An object of one of the following classes:
#'   \itemize{
#'     \item \code{"MIRT"} --- Multidimensional IRT model.
#'     \item \code{"MGPCM"} --- Multidimensional Generalized Partial Credit Model.
#'     \item \code{"MGGUM"} --- Multidimensional Generalized Graded Unfolding Model.
#'     \item \code{"FCMIRT"} --- Forced-Choice Multidimensional IRT model.
#'     \item \code{"FCDCM"} --- Forced-Choice Diagnostic Classification Model.
#'     \item \code{"FCGDINA"} --- Forced-Choice GDINA model.
#'     \item \code{"FCGGUM"} --- Forced-Choice Generalized Graded Unfolding Model.
#'     \item \code{"TIRT"} --- Thurstonian IRT for Forced-Choice.
#'   }
#' @param type Character string specifying which parameters to extract:
#'   \code{"par"} (default) for item/statement parameters, \code{"theta"}
#'   for person trait estimates, \code{"Corr"} for factor correlations, or
#'   \code{"all"} for a list with all three.
#' @param ... Additional arguments (currently ignored).
#'
#' @return
#' \describe{
#'   \item{\code{type = "par"}}{A matrix of item/statement/block parameter
#'     estimates. Rows index items/statements/blocks and columns index
#'     parameter types. Column names indicate the parameter (e.g.,
#'     \code{"a1"}, \code{"b"}, \code{"d0"}, \code{"tau1"}, \code{"eta0"}).}
#'   \item{\code{type = "theta"}}{An \eqn{N \times D} matrix of person
#'     parameter (latent trait) estimates.}
#'   \item{\code{type = "Corr"}}{A \eqn{D \times D} inter-trait correlation
#'     matrix.}
#'   \item{\code{type = "all"}}{A named list with components \code{par},
#'     \code{theta}, and \code{Corr}.}
#' }
#'
#' @details
#' For \code{FCDCM} objects, \code{type = "par"} returns a list with
#' components \code{delta} (higher-order parameters, \eqn{D \times 2}) and
#' \code{par} (block \eqn{\eta} parameters, \eqn{B \times 2}), reflecting
#' the hierarchical structure of the model.
#'
#' @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)
#' )
#'
#' coef(fit)                  # item parameter estimates
#' coef(fit, type = "theta")  # person trait estimates
#' coef(fit, type = "Corr")   # factor correlation matrix
#' coef(fit, type = "all")    # everything in a list
#'
#' @name coef
NULL


# ===========================================================================
# coef.MIRT
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{MIRT} objects.
#'   Returns \eqn{I \times (D+3)} matrix with columns a1..aD, b, c, d.
#' @method coef MIRT
#' @export
coef.MIRT <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}

# ===========================================================================
# coef.MGPCM
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{MGPCM} objects.
#'   Returns \eqn{I \times (D+K_{\max})} matrix with columns a1..aD, d0..d(K-1).
#' @method coef MGPCM
#' @export
coef.MGPCM <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}

# ===========================================================================
# coef.MGGUM
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{MGGUM} objects.
#'   Returns matrix with columns a1..aD, delta1..deltaD, tau0..tau(K-1).
#' @method coef MGGUM
#' @export
coef.MGGUM <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}

# ===========================================================================
# coef.FCMIRT
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{FCMIRT} objects.
#'   Returns statement parameter matrix with columns a1..aD, b, c, d.
#' @method coef FCMIRT
#' @export
coef.FCMIRT <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}

# ===========================================================================
# coef.FCDCM
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{FCDCM} objects.
#'   Returns a list with \code{delta} (\eqn{D \times 2} higher-order
#'   parameters) and \code{par} (\eqn{B \times 2} block \eqn{\eta}
#'   parameters). \code{type = "theta"} returns the higher-order trait,
#'   and \code{type = "Corr"} returns a scalar 1.
#' @method coef FCDCM
#' @export
coef.FCDCM <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = list(delta = object$delta$est, par = object$par$est),
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(delta = object$delta$est,
                 par   = object$par$est,
                 theta = object$theta$est,
                 Corr  = object$Corr$est)
  )
}

# ===========================================================================
# coef.FCGDINA
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{FCGDINA} objects.
#'   \code{type = "par"} returns CDM delta parameters,
#'   \code{type = "theta"} returns posterior attribute mastery probabilities,
#'   \code{type = "Corr"} returns \code{NA} (no continuous latent trait).
#' @method coef FCGDINA
#' @export
coef.FCGDINA <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  D <- ncol(object$Q.matrix)
  Corr.na <- matrix(NA_real_, D, D)
  diag(Corr.na) <- NA_real_
  switch(type,
    par   = object$delta$est,
    theta = object$alpha$est,
    Corr  = Corr.na,
    all   = list(par = object$delta$est,
                 theta = object$alpha$est,
                 Corr = Corr.na,
                 pi = object$pi)
  )
}

# ===========================================================================
# coef.FCGGUM
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{FCGGUM} objects.
#'   Returns matrix with columns a1..aD, delta1..deltaD, tau0..tau(K-1).
#' @method coef FCGGUM
#' @export
coef.FCGGUM <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}

# ===========================================================================
# coef.TIRT
# ===========================================================================

#' @describeIn coef Extract coefficients from \code{TIRT} objects.
#'   Returns \eqn{I \times (D+1)} matrix with columns lambda1..lambdaD, psi2.
#' @method coef TIRT
#' @export
coef.TIRT <- function(object, type = c("par", "theta", "Corr", "all"), ...) {
  type <- match.arg(type)
  switch(type,
    par   = object$par$est,
    theta = object$theta$est,
    Corr  = object$Corr$est,
    all   = list(par = object$par$est,
                 theta = object$theta$est,
                 Corr = object$Corr$est)
  )
}