startItems {catR}

Selection of the first items

Description

This command selects the first items of the adaptive test, either randomly or on the basis of their information function.

Usage

startItems(itemBank, model = NULL, fixItems = NULL, seed = NULL, nrItems = 1, 
 	 theta = 0, D = 1, randomesque = 1, random.seed = NULL, startSelect = "MFI",
 	 nAvailable = NULL, cbControl = NULL, cbGroup = NULL, random.cb=NULL) 
 

Arguments

itemBank

numeric: a suitable matrix of item parameters. See Details.

model

either NULL (default) for dichotomous models, or any suitable acronym for polytomous models. Possible values are "GRM", "MGRM", "PCM", "GPCM", "RSM" and "NRM". See Details.

fixItems

either a vector of integer values or NULL (default). See Details.

seed

either a numeric value, NA or NULL (default). Ignored if fixItems is not NULL. See Details.

nrItems

numeric: the number of starting items to be randomly selected (default is 1). Can be equal to zero to avoid initial selection of items (see Details). Used only if fixItems is NULL and seed is not NULL.

theta

numeric: a vector of the initial ability levels for selecting the first items (default is the single value 0). Ignored if either fixItems or seed is not NULL. See Details.

D

numeric: the metric constant. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric (Haley, 1952). Ignored if model is not NULL and if startSelect is not "MFI".

randomesque

integer: the number of 'randomesque' items to be picked up optimally for each value of theta vector, before random selection of a single one. Ignored if either fixItems or seed is not NULL. See Details.

random.seed

either NULL (default) or a numeric value to fix the random seed of randomesque selection of the items. Ignored if either fixItems or seed is not NULL.

startSelect

character: the criterion for selecting the first items. Possible values are "bOpt", "thOpt", "progressive", "proportional", and "MFI" (default). See Details.

nAvailable

either a boolean vector indicating which items (denoted by 1's) are available at the start of the test and which (denoted by 0's) are not, or NULL (default). See Details.

cbControl

either a list of accurate format to control for content balancing, or NULL. See Details.

cbGroup

either a factor vector of accurate format to control for content balancing, or NULL. See Details.

random.cb

either NULL (default) or a numeric value to fix the selection of subgroups of items for random sampling the starting items. See Details.

Details

This function permits to select the first item(s) of the test. It works with both dichotomous and polytomous item banks.

Dichotomous IRT models are considered whenever model is set to NULL (default value). In this case, it must be a matrix with one row per item and four columns, with the values of the discrimination, the difficulty, the pseudo-guessing and the inattention parameters (in this order). These are the parameters of the four-parameter logistic (4PL) model (Barton and Lord, 1981).

Polytomous IRT models are specified by their respective acronym: "GRM" for Graded Response Model, "MGRM" for Modified Graded Response Model, "PCM" for Partical Credit Model, "GPCM" for Generalized Partial Credit Model, "RSM" for Rating Scale Model and "NRM" for Nominal Response Model. The it still holds one row per item, end the number of columns and their content depends on the model. See genPolyMatrix for further information and illustrative examples of suitable polytomous item banks.

The number of starting items is given by the length of fixItems argument, the nrItems argument (in case of random selection) or by the length of theta argument (in case of optimal selection), with default value 1 in all cases. It can be set to zero; in this case, only NULL values are returned in the output list and the CAT process will start without starting items.

The first item(s) of the adaptive test can be selected by one of the following methods.

1. By specifying the item(s) to be administered. The argument fixItems then holds the item number(s) as listed in the item bank. Setting fixItems to NULL (default value) disables this method.

2. By selecting it (them) randomly into the item bank. The argument seed permits to fix the random selection by specifying the random seed number and the number of selected items is fixed by the nrItems argument. Setting seed to NA disables the random seed (though items are still picked up randomly in the bank); in other words, successive runs of startItems with seed=NA may lead to different item(s) selection. Setting seed to NULL (default value) disables this selection method.

3. By selecting the item(s) according to an initial sequence of ability values set by the theta argument. In this case, five criteria can be used, specified through the startSelect argument:

   1. "MFI" (default): one selects the most informative item(s) for the given initial ability value(s);

   2. "bOpt": one selects the item(s) whose difficulty level is as close as possible to the inital ability value(s);

   3. "thOpt": one selects the item(s) with the ability value where they get their maximum Fisher information is as close as possible to the inital ability value(s) (see Magis, 2013, for further details);

   4. "progressive" for the progressive method (see nextItem);

   5. "proportional" for the proportional method (see nextItem).

   If the "progressive" or "proportional" methods are selected, this will force the values of fixItems to NULL, seed to NULL, and nrItems to 1. Thus, a single item will be selected randomly.

The third method above will be used if and only if both fixItems and seed arguments are fixed to NULL. Otherwise, one of the first two methods will be used (see also testList for details about debugging misspecifications of the starting arguments).

The sequence of initial ability estimates is specified by the argument theta. For each component of theta one item will be picked up optimally according to the chosen startSelect argument. however, it is possible to perform randomesque selection at this stage by setting the randomesque argument to an integer value larger than one. In this case, the randomesque most optimal items are chosen per value of theta, and the final starting item is chosen randomly among the randomesque items. By default, only one item is picked up per ability level (and is therefore the most optimal one).

Only part of the full item bank can be made available for the selection of the first item(s), while others can be dropped out from this first step. This is fixed by the nAvailable argument, which is a vector with as many components as items in the bank and with zeros and ones only. Values 1 code for available items, values 0 for non-available items. By default, nAvailable is NULL and all items are available. Note that nrItems should never be larger than the number of available items (i.e. sum(nAvailable)). Otherwise an error message is returned.

Finally, in case of random selection of the first item(s), it is possible to force this selection to approximately match the content balancing control options set by arguments cbControl and cbGroup. Detailed description of these arguments (and their accurate format) are described in nextItem function. Note that cbControl should be tested with the test.cbList function prior to using startItems.

In practice, when fixing both the number of items to select (through nrItems) and the proportions of items per subgroups (through cbControl$props), the selection is made in two steps. First, the number of items per each subgroup is determined in order to reach closest distribution to the theoretical one. Second, within each subgroup the required number of items are randomly drawn (this draw can be fixed with the seed argument; fixing it to NA withdraws this option).

In the first step, it is possible that several subgroups are equally proable for selection; in this case the selection of the subgroups can be fixed by the argument random.cb. Otherwise the subgroups are sampled without any random seed control.

Value

A list with five arguments:

items

the selected items (identified by their number in the item bank) or NULL (if nrItems is 0).

par

the matrix of item parameters of the selected items (one row per item) or NULL (if nrItems is 0).

thStart

the sequence of starting ability values used for selecting the items or NA (if not applicable) or NULL (if nrItems is 0).

startSelect

the value of the startSelect argument or NA (if not applicable) or NULL (if nrItems is 0).

names

either a vector with the names of the selected item(s) or NULL (if the item bank has no item names).

Note

Currently only the "MFI" value for startSelect is allowed for polytomous IRT models (i.e., when model is not NULL). Otherwise an error message is returned.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[e-mail]

Juan Ramon Barrada
Department of Psychology and Sociology, Universidad Zaragoza, Spain
[e-mail]

References

Barton, M.A., and Lord, F.M. (1981). An upper asymptote for the three-parameter logistic item-response model. Research Bulletin 81-20. Princeton, NJ: Educational Testing Service.

Haley, D.C. (1952). Estimation of the dosage mortality relationship when the dose is subject to error. Technical report no 15. Palo Alto, CA: Applied Mathematics and Statistics Laboratory, Stanford University.

Magis, D. (2013). A note on the item information function of the four-parameter logistic model. Applied Psychological Measurement, 37, 304-315. doi: 10.1177/0146621613475471

Magis, D. and Barrada, J. R. (2017). Computerized Adaptive Testing with R: Recent Updates of the Package catR. Journal of Statistical Software, Code Snippets, 76(1), 1-18. doi: 10.18637/jss.v076.c01

Magis, D., and Raiche, G. (2012). Random Generation of Response Patterns under Computerized Adaptive Testing with the R Package catR. Journal of Statistical Software, 48 (8), 1-31. doi: 10.18637/jss.v048.i08

See Also

testList, genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Item bank creation with 'tcals' item parameters
 bank <- as.matrix(tcals[,1:4])
 
 # Random selection of 4 starting items
 startItems(bank, seed = 1, nrItems = 4)

 # Random selection of 4 starting items without fixing the seed
 startItems(bank, seed = NA, nrItems = 4)
 startItems(bank, seed = NA, nrItems = 4) # may provide a different result!

 ## With content balancing control
 prov <- breakBank(tcals)
 cbGroup <- prov$cbGroup

 # Creation of the 'cbList' list with arbitrary proportions
 cbList <- list(names = c("Audio1", "Audio2", "Written1", "Written2", "Written3"), 
        props = c(0.1, 0.2, 0.2, 0.2, 0.3))

 startItems(bank, seed = 1, nrItems = 3, cbControl = cbList, cbGroup = cbGroup)
 startItems(bank, seed = NA, nrItems = 3, cbControl = cbList, cbGroup = cbGroup,
            random.cb = 1)

 # Selection of the first 5 starting items
 startItems(bank, fixItems = 1:5)

 # Selecting 1 starting item, initial ability estimate is 0
 startItems(bank) 

 # Selecting 3 starting items for ability levels -1, 0 and 2
 startItems(bank, theta = c(-1, 0, 2)) 

 # Same with 5 randomesque items per theta value
 startItems(bank, theta = c(-1, 0, 2), randomesque = 5)

 # 5 randomesque items per theta value, with fixed random seed number
 startItems(bank, theta = c(-1, 0, 2), randomesque = 5, random.seed = 1) 

 # Idem but with 'bOpt' criterion
 startItems(bank, theta = c(-1, 0, 2), startSelect = "bOpt")

 # Selecting only the first 10 items as available items
 avail <- c(rep(1, 10), rep(0, nrow(bank)-10))
 startItems(bank, theta = c(-1, 0, 2), nAvailable = avail) 

## Not run: 
 # Selecting too many items among available ones
 startItems(bank, nrItems = 11, theta = 2, halfRange = 3, nAvailable = avail) 

## End(Not run)

## Polytomous models ##

 # Generation of an item bank under GRM with 100 items and at most 4 categories
 m.GRM <- genPolyMatrix(100, 4, "GRM")
 m.GRM <- as.matrix(m.GRM)

 # Random selection of 4 starting items
 startItems(m.GRM, model = "GRM", seed = 1, nrItems = 4)

 # Selection of the first 5 starting items
 startItems(m.GRM, model = "GRM", fixItems = 1:5)

 # Selecting 3 starting items for theta values -1, 0 and 2
 startItems(m.GRM, model = "GRM", theta = c(-1, 0, 2))

## Not run: 

 # Idem but with 'bOpt' criterion
 startItems(m.GRM, model = "GRM", nrItems = 3, theta = 1, halfRange = 2, 
            startSelect = "bOpt")
 
## End(Not run)

 # Selecting only the first 10 items as available items
 avail <- c(rep(1, 10), rep(0, nrow(m.GRM)-10))
 startItems(m.GRM, model = "GRM", theta = c(-1, 0, 2), 
            nAvailable = avail) 

## Not run: 

 # Selecting too many items among available ones
 startItems(m.GRM, model = "GRM", theta = seq(from = -2, to = 2, length = 11), 
            nAvailable = avail) 

## End(Not run)

 # Loading the cat_pav data
 data(cat_pav)
 cat_pav <- as.matrix(cat_pav)

 # Random selection of 4 starting items
 startItems(cat_pav, model = "GPCM", seed = 1, nrItems = 4)

 # Selection of the first 5 starting items
 startItems(cat_pav, model = "GPCM", fixItems = 1:5)

 # Selecting 3 starting items for theta values -1, 0 and 2
 startItems(cat_pav, model = "GPCM", theta = c(-1, 0, 2)) 

## Not run: 

 # Idem but with 'bOpt' criterion
 startItems(cat_pav, model = "GPCM", theta = c(-1, 0, 2), startSelect = "bOpt")
 
## End(Not run)

 # Selecting only the first 10 items as available items
 avail <- c(rep(1, 10), rep(0, nrow(cat_pav)-10))
 startItems(cat_pav, model = "GPCM", theta = c(-1, 0, 2), nAvailable = avail) 

## Not run: 

 # Selecting too many items among available ones
 startItems(cat_pav, model = "GPCM", theta = seq(from = -2, to = 2, length = 11), 
            nAvailable = avail) 
 
## End(Not run)