R/mcdat.generate.R

In NPCDTools: The Nonparametric Classification Methods for Cognitive Diagnosis

#' @title Generation of MC Responses
#'
#' @description This function generates MC responses conforming to the MC-DINA model with relaxed MC Q-matrix.
#'
#' @param mcQ A \eqn{(\sum_{j=1}^J H_j^\ast)\times (K+2)} Q-matrix for MC items. The first two columns are item ID and option ID of the coded options.
#' @param N The number of examinees
#' @param H The number of maximal attributes required by the items. H takes values 3, 4, 5, or 6.
#' @param att.structure The structure of attribute profiles. Possible options are \code{"unif"} and \code{"mvn"} representing discrete uniform distribution 
#' and multivariate normal threshold model.
#' @param cor.att If \code{att.structure = "mvn"}, \code{cor.att} is used to specify the correlation between attributes.
#' @param lambda A \eqn{J}-dimensional vector, where the \eqn{j}th entry represents the probability of a match between an examinee's ideal response 
#' and his/her observed response to item \eqn{j}.
#'
#' @return The function returns
#' \describe{
#' \item{dat}{A \eqn{N\times J} matrix storing the generated responses}
#' \item{att}{Examinees' attribute profiles (\eqn{N\times K}) used to generate the responses}
#' \item{prob.persons}{A list storing the probabilities that the examinees are attracted by the options of the items}
#' }
#'
#' @export
#'
mcdat.generate = function(mcQ, N, H, att.structure = "unif", cor.att = 0.5, lambda = rep(0.85, J)){
  J = length(unique(mcQ[,1]))
  K = ncol(mcQ)-2
  
  att = att.generate(K, N, att.structure, cor.att)
  prob = prob.generate(mcQ, H, att, lambda)

  p.fun = function(p) sample(1:H, size = 1, prob = p)
  
  dat = matrix(0, N, J)
  for (i in 1:N) dat[i,] = apply(prob[[i]], 1, p.fun)
  
  out = list(
    dat          = dat,
    att          = att,
    prob.persons = prob
  )
  class(out) = "mcdat"
  return(out)
}
  
#' @export
print.mcdat = function(x, ...){
  N = nrow(x$dat)
  J = ncol(x$dat)
  K = ncol(x$att)
  
  cat("MC-DINA generated data\n")
  cat("----------------------\n")

  
  cat("Components (access with $):\n")
  cat("  $dat          : ", N, "x", J, "matrix of students' responses\n")
  cat("  $att          : ", N, "x", K, "matrix of attribute profiles\n")
  cat("  $prob.persons : ", "option-attraction probabilities per examinee\n\n")
  
  
  invisible(x)
}