grmCAT: MTB Graded Response Model Engine

In akaat/MTBfx: Functions to support Mobile Toolbox analysis

MTB Graded Response Model Engine

Description

This function is a wrapper to simulate the graded response model engine programmed within MobileToolbox. It utilizes matrixInfoGRM, selectMPWI, and calcEAP funtions for item selection and scoring.

Usage

grmCAT(
  ipar,
  resp,
  minTheta = -6,
  maxTheta = 6,
  nQpts = 121,
  prevTheta = NULL,
  prevSD = NULL,
  muEAP = 0,
  sdEAP = 3,
  scoreCumulativeDiffuse = TRUE,
  start_item = 0,
  minNI = 4,
  maxSD = 0.3,
  maxNI = 8,
  deltaSD = 0.01,
  bestAt = NULL,
  bestStop = "LO",
  verbose = F
)

Arguments

ipar	An item parameter matrix in slope/threshold format. Each item is on a separate line. The column names should be "a" and "CB1" through "CB#" for the slope and relevant thresholds. There should also be a column called "NCAT" to indicate the number of response categories available for each item.
resp	Response matrix (number of rows = number of participants and number of columns = number of items)
minTheta	Minimum theta value (PROMIS default is -4)
maxTheta	Maximum theta value (PROMIS default is 4)
nQpts	number of quadrature points, with min minTheta and max maxTheta
prevTheta	estimated theta from prior CAT administration
prevSD	estimated SD from prior CAT administration
muEAP	Estimated A Posterior mean. Defaults to NULL.
sdEAP	Estimated A Posterior SD. Defaults to NULL.
scoreCumulativeDiffuse	Logical to indicate whether the theta grid should be modified prior to administering the first item based on the final score estimate from the previous administration. Defaults to TRUE.
start_item	First item to start the CAT engine.
minNI	Minimum number of items to administer. Defaults to 4.
maxSD	Maximum SD. Defaults to 0.3.
maxNI	Maximum number of items to administer. Defaults to 8.
deltaSD	Mininum change for SD.
bestAt	This indicates how many items have to be administered before the Best Health stopping rule is checked. This can override the _minNI_ parameter. NOTE: Setting this to any value greater than the _maxNI_ parameter will turn off the Best Health rule.
bestStop	An indicator for whether the Best Health is the minimum (e.g., for symptom banks; indicated with “LO”) or the maximum (e.g. for function banks; indicated with “HI”).
verbose	A logical value indicating whether or not to print interim information related to the computer adaptive testing progress. Default is FALSE.

Value

This function returns a list with five elements. The first two elements are scalar elements with the final theta estimate and the standard deviation of the score elements.The third element is a dataframe with the item administration history. The first row is the prior. The second row through the final are the items administered, the chosen response category score, and the theta/sd history. The fourth and fifth elements are the probability differences array and the item information matrix, both of which are calculated by the the matrixInfoGRM function.

See Also

Other GRM_CAT functions: calcEAP(), matrixInfoGRM(), selectMPWI()

Examples

# define item parameter bank; number of rows is the number of columns
# a = item slope; CB1 to CB# = category bins/thresholds for response; NCAT = number of categories for item

ipar <- data.frame(a = c(2.99, 3.53,  3.10),
                  CB1 = c(-1.18, -2.79,  -2.12),
                  CB2 = c(-0.499, -1.85,  -1.27),
                  CB3 = c(0.17, -1.19,  -0.52),
                  CB4 = c(0.653, -0.551,  0.036),
                  NCAT = 5)
#simulate responses
set.seed(22416)
# 20 participants and their responses from the three items
resp <- round(matrix(stats::runif(20*3, 1, 5), 20, 3))

# Currently grmCAT is NOT vectorized and only 1 participant can be run at a time (unless using apply)

# run
grmCAT_output <- grmCAT(ipar, resp[,1],minTheta=-6,maxTheta=6,nQpts=121,prevTheta=NULL,
prevSD=NULL,muEAP=0,sdEAP=3,scoreCumulativeDiffuse=TRUE,
start_item=0,minNI=4,maxSD=0.3,maxNI=8,deltaSD=0.01)

# set scoreCumulativeDiffuse = T and prevTheta = 1
grmCAT_sCD_true <- grmCAT(ipar, resp[,1],minTheta=-6,maxTheta=6,nQpts=121,prevTheta=1,
prevSD=NULL,muEAP=0,sdEAP=3,scoreCumulativeDiffuse=TRUE,
start_item=0,minNI=4,maxSD=0.3,maxNI=8,deltaSD=0.01)

grmCAT_sCD_false <- grmCAT(ipar, resp[,1],minTheta=-6,maxTheta=6,nQpts=121,prevTheta=1,
prevSD=NULL,muEAP=0,sdEAP=3,scoreCumulativeDiffuse=FALSE,
start_item=0,minNI=4,maxSD=0.3,maxNI=8,deltaSD=0.01)

# changing the scoreCumulativeDiffuse option does not change item selection with only three items
# theta estimates should generally be very close, if not identical
 grmCAT_sCD_true$finalTheta; grmCAT_sCD_false$finalTheta

# or with apply
#' allResp <- apply(resp,1, function(y) grmCAT(ipar, resp=y))


 #### Using the PROMIS Pediatric Strength Impact item bank
 set.seed(542)
# 5 participants with random responses to 10 of the items in the bank
data(iparPedImp)
respSI <- round(matrix(stats::runif(10*5, 1, 5), 5, 10))
grm_out1 <- apply(respSI,1,function(y) grmCAT(ipar=iparPedImp[,2:7], resp=y,
minTheta=-4, maxTheta=4, nQpts=81,minNI=5,maxNI=12)) # PROMIS Peds defaults

table(sapply(grm_out1, function(y) nrow(y$scoreHistory)-1)) # all participants got 5 items
table(sapply(grm_out1, function(y) y$scoreHistory$itemAdminHistory))

akaat/MTBfx documentation built on June 6, 2023, 11:43 p.m.