dichEngine: MTB Dichotomous Engine

In akaat/MTBfx: Functions to support Mobile Toolbox analysis

MTB Dichotomous Engine

Description

This function is a wrapper to simulate the dichotomous engine programmed within MobileToolbox. It utilizes MI_xPL and TIF_xPL functions for item selection and the MLE_xPL function for scoring. The dichotomous engine includes functionality for using experimental items (every 5th item, provided experimental items are available), exposure control with the Sympson-Hetter or Modified Davey-Parshall method, excluding items administered on a previous run (for retest scenarios), and exporting interim steps to the console, if requested.

Usage

dichEngine(
  iparFull,
  uFull,
  calib,
  lastAdmin,
  targetProb = 0.5,
  minNI = 20,
  maxNI = 35,
  maxSE = 0.4,
  nonML_se = 99,
  stepVal = 0.75,
  minTheta = -10,
  maxTheta = 10,
  exp.cont,
  startTheta = 0,
  maxCycles = 100,
  critScore = 5e-04,
  seedval = 12345,
  verbose = F
)

Arguments

iparFull	A matrix with rows for items and three columns. The first column is the slope, the second is the intercept (not the threshold), and the third is the guessing parameter (on the original scale, not on the logit scale).
uFull	A vector of response strings, coded 0 for incorrect and 1 for correct. The length of this vector must be equal to the number of items in the item bank.
calib	A vector of length nItems indicating whether an item is experimental (=0) or calibrated (=1). Only calibrated items are utilized in scoring. Experimental (or uncalibrated) items are administered every 5 items as available.
lastAdmin	A logical vector of length nItems indicating whether an item was administered (=TRUE) during the previous test session or if it was unadministered (=FALSE) and thus available for the current test session. If this is not provided, it defaults to all FALSE (i.e., no items were administered last time and thus all items are avialable this time).
targetProb	The target probability for a correct answer. Admissible values are from 0.01 to 0.99. The optimally-targeted items is at 0.50 (50 or something similar, in which case the respondent is more likely to get the correct answer.
minNI	Minimum number of items to administer. Defaults to 20.
maxNI	Maximum number of items to administer. Defaults to 35.
maxSE	Maximum SE for variable-length CATs. Defaults to 0.4 (or approximately a reliability of 0.85)
nonML_se	The standard error to report when the maximum likelihood score estimate is undefined. Note that the MLE_xPL function returns Inf in these cases, and it is overridden only for reporting purposes. The default value for this is 99.
stepVal	In cases when the MLE score is undefined, this parameter defines how far the theta estimate should be incremented (positively if all correct, negatively if all incorrect) for the next item. Default is 0.75 logits.
minTheta	Minimum allowable theta. Defaults to -10.
maxTheta	Maximum allowable theta. Defaults to +10.
exp.cont	This is a symmetric exposure control matrix of dimensions nItems by nItems. Acceptable values are between 0 and 1. If it is not provided, the default is to create a matrix of all 1's, indicating no exposure control. If all off-diagonal values are equal to 1 but the diagonal is between 0 and 1, this is equal to the Sympson-Hetter method for exposure control, or what has been referred to as unconditional exposure control. If the off-diagonals are also between 0 and 1, the lowest off-diagonal for an administered item is multiplied by the diagonal value to get a conditional exposure control value. This is a modification of the Davey-Parshall method.
startTheta	The theta value at which item selection for this person should begin. Defaults to 0.
maxCycles	Maximum number of cycles for the Newton Raphson method for MLE scoring.
critScore	Convergence criterion for the Newton Raphson method for MLE scoring.
seedval	Seed value for the random number generator used for exposure control.
verbose	A logical value indicating whether or not to print interim information related to the computer adaptive testing progress. Default is FALSE.

Value

dichotomousEngine returns a list of length 7 with various information about how the engine progressed through the simulation. The first element is Theta, which is the final score for this simulee.

The second element is SEM, which is the standard error associated with the final theta for this simulee.

The third element is the interimScores matrix. It includes information about the theta estimate and standard error used to initialize the engine (row 1) and after each item.

The fourth element is the itemConsideration dataframe. This includes information on which item was considered, what the exposure control value was for that item, conditioned upon all of the items already administered, the random number sampled at that time used to determine whether or not to administer that item, and a TRUE/FALSE indicator for whether the considered item was administered to the examinee or removed from consideration for the remainder of this administration.

The adminInfo element is next, which includes only the items admnistered during the consideration step. It lists the item identifier, the response (correct/incorrect coded 1/0, respectively), and whether or not the item was experimental.

The sixth element is an integer for the number of items given during this administration.

And the final element is restating the seed value used to initialize the RNG for exposure control.

See Also

Other dichotomous functions: MLE_xPL(), TIF_xPL(), maxInfo_xPL()

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