Package 'catR'

Item membership assessment for a-stratified sampling

Description

This command allocates each item from the bank into its specified stratum, defined by increasing discrimination parameters for a-stratified sampling.

Usage

aStratified(itemBank, K, model = NULL)

Arguments

itemBank	a matrix or data frame of item parameters. Must refer to either nay dichotomous IRT model or to polytomous GRM, MGRM or GPCM models. See Details.
K	either a single integer value specifying the number of strata, or an integer vector of required numbers of items per strata.
model	either NULL (default) for dichotomous models, or any suitable acronym for allowed polytomous models. Possible values are "GRM", "MGRM" and "GPCM". See Details.

Details

a-stratified sampling (Chang and Ying, 1999) is a content balancing technique that splits the item bank into several strata, the latter being set by increasing discrimination (a) parameters. The first stratum holds the least discriminative items, the second stratum the second set of least discriminative items etc., and the last stratum the most discriminative items. Content balancing item selection is then performed with equiprobable item selection across the strata.

The specification of the strata can be done in two ways, through the K argument. First, K can take any positive integer value (larger than one and smaller than the number of items): it specifies then the number of strata to create. Each stratum will hold approximately the same number of items, and in case the ratio between the number of items in the bank and K is not an integer value, then the last stratum will hold more items than the other ones. Second, K can be a vector of integer values that specify the number of items per strata. In this second case, the first stratum will hold as many items as the first component of K, the second startum as many items as the second component of K, and so on. Note that the sum of K shoudl coincide with the number of items in the bank.

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 and "GPCM" for Generalized Partial Credit Model. Other polytomous IRT models are not allowed for this function and an error message will be returned if the input item bank does not follow one of the three aforementioned models. 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 output is a vector with character values "Group1" for the first startum, "Group2" for the second stratum etc. It has the same length as the number of items in the itemBank matrix and permits one-to-one identification of the items in each stratum.

Value

A vector with as many components as the number of items in the bank, with values Group1 to GroupG where G is the number of strata (i.e. either K) or the length of vector K).

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Chang, H.-H., and Ying, Z. (1999). A-stratified multistage computerized adaptive testing. Applied Psychological Measurement, 23, 211-222. doi:10.1177/01466219922031338

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

genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])

 # Creation of five strata with equal length (17 items each)
 aStratified(tcals, 5)

 # Creation of four strata with prespecified lengths 
 res <- aStratified(tcals, K = c(20, 25, 10, 30))
 table(res) # as expected


## Polytomous models ##

 # GRM with 100 items
 mat <- genPolyMatrix(100, 4, model = "GRM")

 # Creation of four strata with equal length (25 items each)
 aStratified(mat, 5, model = "GRM")

---

Breaking the item bank in item parameters and group membership (for content balancing)

Description

This command "breaks" the item bank in two parts, the item parameters as a numeric matrix, and the group membership of the items as a vector of factor levels. These two elements can be used separately for content balancing purposes, among others.

Usage

breakBank(itemBank)

Arguments

itemBank

a matrix or data frame with item parameters in the first columns and group membership in the last column.

Details

The breakBank function is useful to split the original item bank in two parts, one holding the item parameters only, and one containing the names of item group membership. The former can then directly be plugged in adequate functions such as thetaEst.

The function works with both dichotomous and polytomous IRT item banks. In both cases, the group membership must be located as the last column of the matrix or data frame.

Note that there is no check that the input is correct (that is, the group membership is located in the last column), as breakBank is mostly devoted to be used at the early stages of the randomCAT function.

Value

A list with two arguments:

itemPar	a numeric matrix with the item parameters.
cbGroup	a vector with factor names of item membership, with one name per item in itemPar element of the output list.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

References

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

randomCAT

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Breaking 'tcals'
 breakBank(tcals)


## Polytomous models ##

 # 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))

 # NRM with 100 items
 mat <- genPolyMatrix(100, 4, model = "NRM", cbControl = cbList)

 # Breaking 'mat'
 breakBank(mat)

---

Items parameters of the CAT_PAV data set (with item names)

Description

The CAT-PAV questionnaire (D.O. Santos, 2017) was developed to propose a computer-adaptive assessment of productive and contextualized academic English vocabulary, piloted with students at Iowa State University (USA). Items are presented as two sentences drawn from the academic subset of the COCA corpus, with one common missing word to be identified by test takers. In case of an incorrect first answer, synonyms are exhibited as a hint. Th item is scored 2 if a correct answer was provided from first attempt, 1 if a correct answer was provided after the hint being shown, and 0 in case of an incorrect answer after the hint was shown.

Format

A matrix with 96 rows and three columns, respectively holding the discrimination, first threshold and second threshold under a GPCM calibration of the items of CAT-PAV study. Item names are available as row names, each item name corresponding to the word being tested by the item.

Source

The original items of CAT-PAV were developed by D.O. Santos (2017), field tested at Iowa State University and calibrated using the Jmetrik software (Meyer, 2015).

References

Meyer, P. (2015). Jmetrik (version 4.0.3) [Computer software]. Psychomeasurement Systems, LLC.

D.O. Santos, V. (2017). A computer-adaptive test of of productive and contextualized academic vocabulary breadth in English (CAT-PAV): Development and validation. Graduate Theses and Dissertations, 16292. Ames, IA: Iowa State University. http://lib.dr.iastate.edu/etd/16292

---

Checking whether the stopping rule is satisfied

Description

This command tests whether one of the specified stopping rules is satisfied in order to stop the CAT.

Usage

checkStopRule(th, se, N, it = NULL, model = NULL, D = 1, stop)

Arguments

th	numeric: the current ability estimate.
se	numeric: the current standard error estimate.
N	numeric: the current number of administered items.
it	the matrix of parameters of currently available items (default is NULL). Ignored if element $rule of stop list does not hold the value "minInfo". 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". Ignored if element $rule of stop list does not hold the value "minInfo". 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 or if element $rule of stop list does not hold the value "minInfo".
stop	a list with valuable element names and contents to set the stopping rule, as an input of the randomCAT or simulateRespondents functions.

Details

The checkStopRule function checks whether at least one of the stopping rules was satisfied at the current step of the CAT test process. It mainly serves as an internal application forrandomCAT function.

The stop list must be supplied accordingly to the requested list in the randomCAT() and in the simulateRespondents() functions.

Three input values must be supplied: th as the current ability estimate; se as the current standard error value related to th estimate; and N as the current test length (i.e., number of administered items). In addition, if the stop$rule vector holds the option "minInfo", three additional input value smust be supplied: it with the item parameters or all available items in the bank (i.e., previously administered items should not be set as input); model to specify the type of IRT model, either dichotomous or polytomous (see Pi fir further details); and possibly the scaling constant D set to one by default.

All stopping rules are being assessed and if at least one of them is satisfied, the output list will hold the vector of rules's nmaes that were satisfied through the rule argument). If none of the stopping rules were satisfied, this rule output argument is simply NULL.

Value

A list with two arguments:

decision	a logical value indicating whether at least one of the stopping rules was satisfied (TRUE) or not (FALSE).
rule	either a vector with the names of the stopping rules that were satisfied, or NULL if decision is FALSE.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

References

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. 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

randomCAT, simulateRespondents, Pi

Examples

# Creation of a 'stop' list with two possible rules
 stop <- list(rule = c("length", "precision"), thr = c(20, 0.3))

# Example of successful 'length' rule
 checkStopRule(th = 0.35, se = 0.41, N = 20, stop = stop)

# Example of successful 'precision' rule
 checkStopRule(th = 0.35, se = 0.29, N = 15, stop = stop)

# Example of jointly successful 'length' and 'precision' rules
 checkStopRule(th = 0.35, se = 0.29, N = 20, stop = stop)

# Example without sucessfull rule
 checkStopRule(th = 0.35, se = 0.31, N = 18, stop = stop) 

# Creation of a short bank of available items under 2PL
 it <- genDichoMatrix(items = 5, model = "2PL", seed = 1)

# Computation of maximum information at ability level 0.35
maxI <- max(Ii(0.35, it)$Ii)

# Creation of a 'stop' list with four possible rules and too large threshold for 'minInfo'
 stop <- list(rule = c("length", "precision", "classification", "minInfo"), 
              thr = c(20, 0.3, 1, maxI-0.01), alpha = 0.05)

# Example with sucessfull 'classification' rule only
 checkStopRule(th = 0.35, se = 0.31, N = 18, it = it, stop = stop) 

# Creation of a 'stop' list with four possible rules and too large threshold for 'minInfo'
 stop <- list(rule = c("length", "precision", "classification", "minInfo"), 
              thr = c(20, 0.3, 1, maxI+0.01), alpha = 0.05)

# Example with sucessfull 'minInfo' rule only
 checkStopRule(th = 0.35, se = 0.55, N = 18, it = it, stop = stop)

---

EAP ability estimation (dichotomous and polytomous IRT models)

Description

This command returns the EAP (expected a posteriori) ability estimate for a given response pattern and a given matrix of item parameters, either under the 4PL model or any suitable polytomous IRT model.

Usage

eapEst(it, x, model = NULL, D = 1, priorDist = "norm", priorPar = c(0, 1), 
 	lower = -4, upper = 4, nqp = 33)

Arguments

it	numeric: a suitable matrix of item parameters. See Details.
x	numeric: a vector of item responses.
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.
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.
priorDist	character: specifies the prior distribution. Possible values are "norm" (default), "unif" and "Jeffreys".
priorPar	numeric: vector of two components specifying the prior parameters (default is c(0,1)). Ignored if priorDist="Jeffreys". See Details.
lower	numeric: the lower bound for numercal integration (default is -4).
upper	numeric: the upper bound for numercal integration (default is 4).
nqp	numeric: the number of quadrature points (default is 33).

Details

The EAP (expected a posteriori) ability estimator (Bock and Mislevy, 1982) is obtained by computing the average of the posterior distribution of ability, the latter being set as the prior distribution times the likelihood function.

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.

Three prior distributions are available: the normal distribution, the uniform distribution and Jeffreys' prior distribution (Jeffreys, 1939, 1946). The prior distribution is specified by the argument priorPar, with values "norm", "unif" and "Jeffreys", respectively.

The argument priorPar determines either the prior mean and standard deviation of the normal prior distribution (if priorDist="norm"), or the range for defining the prior uniform distribution (if priorDist="unif"). This argument is ignored if priorDist="Jeffreys".

The required integrals are approximated by numerical adaptive quadrature. This is achieved by using the integrate.catR function. Arguments lower, upper and nqp define respectively the lower and upper bounds for numerical integration, and the number of quadrature points. By default, the numerical integration runs with 33 quadrature points on the range [-4; 4], that is, a sequence of values from -4 to 4 by steps of 0.25.

Value

The estimated EAP ability level.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Bock, R. D., and Mislevy, R. J. (1982). Adaptive EAP estimation of ability in a microcomputer environment. Applied Psychological Measurement, 6, 431-444. doi:10.1177/014662168200600405

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.

Jeffreys, H. (1939). Theory of probability. Oxford, UK: Oxford University Press.

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society of London. Series A, Mathematical and Physical Sciences, 186, 453-461.

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

thetaEst, genPolyMatrix, integrate.catR

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])
 
 # Creation of a response pattern (tcals item parameters,
 # true ability level 0)
 set.seed(1)
 x <- genPattern(0, tcals)

 # EAP estimation, standard normal prior distribution
 eapEst(tcals, x)

 # EAP estimation, uniform prior distribution upon range [-2,2]
 eapEst(tcals, x, priorDist = "unif", priorPar = c(-2, 2))

 # EAP estimation, Jeffreys' prior distribution  
 eapEst(tcals, x, priorDist = "Jeffreys")

 # Changing the integration settings
 eapEst(tcals, x, nqp = 100)


## 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)

 # Creation of a response pattern (true ability level 0)
 set.seed(1)
 x <- genPattern(0, m.GRM, model = "GRM")

 # EAP estimation, standard normal prior distribution
 eapEst(m.GRM, x, model = "GRM")

 # EAP estimation, uniform prior distribution upon range [-2,2]
 eapEst(m.GRM, x, model = "GRM", priorDist = "unif", priorPar = c(-2, 2))

 # EAP estimation, Jeffreys' prior distribution  
 eapEst(m.GRM, x, model = "GRM", priorDist = "Jeffreys")


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

 # Creation of a response pattern (true ability level 0)
 set.seed(1)
 x <- genPattern(0, cat_pav, model = "GPCM")

 # EAP estimation, standard normal prior distribution
 eapEst(cat_pav, x, model = "GPCM")

 # EAP estimation, uniform prior distribution upon range [-2,2]
 eapEst(cat_pav, x, model = "GPCM", priorDist = "unif", priorPar = c(-2, 2))

 # EAP estimation, Jeffreys' prior distribution  
 eapEst(cat_pav, x, model = "GPCM", priorDist = "Jeffreys")

---

Standard error of EAP ability estimation (dichotomous and polytomous IRT models)

Description

This command returns the estimated standard error of the ability estimate, for a given response pattern and a given matrix of item parameters, either under the 4PL model or any suitable polytomous IRT model.

Usage

eapSem(thEst, it, x, model = NULL, D = 1, priorDist = "norm", 
 	priorPar = c(0, 1), lower = -4, upper = 4, nqp = 33)

Arguments

thEst	numeric: the EAP ability estimate.
it	numeric: a suitable matrix of item parameters. See Details.
x	numeric: a vector of item responses.
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.
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.
priorDist	character: specifies the prior distribution. Possible values are "norm" (default), "unif" and "Jeffreys".
priorPar	numeric: vector of two components specifying the prior parameters (default is c(0,1)). Ignored if priorDist="Jeffreys". See Details.
lower	numeric: the lower bound for numercal integration (default is -4).
upper	numeric: the upper bound for numercal integration (default is 4).
nqp	numeric: the number of quadrature points (default is 33).

Details

This command computes the standard error of the EAP (expected a posteriori) ability estimator (Bock and Mislevy, 1982).

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.

Three prior distributions are available: the normal distribution, the uniform distribution and Jeffreys' prior distribution (Jeffreys, 1939, 1946). The prior distribution is specified by the argument priorPar, with values "norm", "unif" and "Jeffreys", respectively.

The argument priorPar determines either the prior mean and standard deviation of the normal prior distribution (if priorDist="norm"), or the range for defining the prior uniform distribution (if priorDist="unif"). This argument is ignored if priorDist="Jeffreys".

The required integrals are approximated by numerical adaptive quadrature. This is achieved by using the integrate.catR function. Arguments lower, upper and nqp define respectively the lower and upper bounds for numerical integration, and the number of quadrature points. By default, the numerical integration runs with 33 quadrature points on the range [-4; 4], that is, a sequence of values from -4 to 4 by steps of 0.25.

Note that in the current version, the EAP ability estimate must be specified through the thEst argument.

Value

The estimated standard error of the EAP ability level.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Bock, R. D., and Mislevy, R. J. (1982). Adaptive EAP estimation of ability in a microcomputer environment. Applied Psychological Measurement, 6, 431-444. doi:10.1177/014662168200600405

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.

Jeffreys, H. (1939). Theory of probability. Oxford, UK: Oxford University Press.

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society of London. Series A, Mathematical and Physical Sciences, 186, 453-461.

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

thetaEst, genPolyMatrix, integrate.catR

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])

 # Creation of a response pattern (tcals item parameters,
 # true ability level 0)
 set.seed(1)
 x <- genPattern(0, tcals)

 # EAP estimation, standard normal prior distribution
 th <- eapEst(tcals, x)
 c(th, eapSem(th, tcals, x))

 # EAP estimation, uniform prior distribution upon range [-2,2]
 th <- eapEst(tcals, x, priorDist = "unif", priorPar = c(-2, 2))
 c(th, eapSem(th, tcals, x, priorDist = "unif", priorPar=c(-2, 2)))

 # EAP estimation, Jeffreys' prior distribution  
 th <- eapEst(tcals, x, priorDist = "Jeffreys")
 c(th, eapSem(th, tcals, x, priorDist = "Jeffreys"))

## 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)

 # Creation of a response pattern (true ability level 0)
 set.seed(1)
 x <- genPattern(0, m.GRM, model = "GRM")

 # EAP estimation, standard normal prior distribution
 th <- eapEst(m.GRM, x, model = "GRM")
 c(th, eapSem(th, m.GRM, x, model = "GRM"))

 # EAP estimation, uniform prior distribution upon range [-2,2]
 th <- eapEst(m.GRM, x, model = "GRM", priorDist = "unif", priorPar = c(-2, 2))
 c(th, eapSem(th, m.GRM, x, model = "GRM", priorDist = "unif", priorPar = c(-2, 2)))

 # EAP estimation, Jeffreys' prior distribution  
 th <- eapEst(m.GRM, x, model = "GRM", priorDist = "Jeffreys")
 c(th, eapSem(th, m.GRM, x, model = "GRM", priorDist = "Jeffreys"))


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

 # Creation of a response pattern (true ability level 0)
 set.seed(1)
 x <- genPattern(0, cat_pav, model = "GPCM")

 # EAP estimation, standard normal prior distribution
 th <- eapEst(cat_pav, x, model = "GPCM")
 c(th, eapSem(th, cat_pav, x, model = "GPCM"))

 # EAP estimation, uniform prior distribution upon range [-2,2]
 th <- eapEst(cat_pav, x, model = "GPCM", priorDist = "unif", priorPar = c(-2, 2))
 c(th, eapSem(th, cat_pav, x, model = "GPCM", priorDist = "unif", priorPar = c(-2, 2)))

 # EAP estimation, Jeffreys' prior distribution  
 th <- eapEst(cat_pav, x, model = "GPCM", priorDist = "Jeffreys")
 c(th, eapSem(th, cat_pav, x, model = "GPCM", priorDist = "Jeffreys"))
 
## End(Not run)

---

Expected Posterior Variance (EPV)

Description

This command returns the expected posterior variance (EPV) for a given item under dichotomous and polytomous IRT models, as used for Minimum Expected Posterior Variance (MEPV) criterion.

Usage

EPV(itemBank, item, x, theta, it.given, model = NULL, priorDist = "norm", 
 	priorPar = c(0, 1), D = 1, parInt = c(-4, 4, 33))

Arguments

itemBank	numeric: a suitable matrix of item parameters. See Details.
item	numeric: the item (referred to as its rank in the item bank) for which the expected posterior variance must be computed.
x	numeric: a vector of item responses, coded as 0 or 1 only (for dichotomous items) or from 0 to the number of response categories minus one (for polytomous items).
theta	numeric: the provisional ability estimate.
it.given	numeric: a suitable matrix of item parameters for previously administered items. The number of rows of it.given must be equal to the length of x.
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.
priorDist	character: specifies the prior distribution. Possible values are "norm" (default) and "unif".
priorPar	numeric: vector of two components specifying the prior parameters (default is c(0,1)) of the prior ability distribution.
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.
parInt	numeric: vector of three components, defining the sequence of ability values for computing the posterior variance. See Details.

Details

The EPV can be used as a rule for selecting the next item in the CAT process (Choi and Swartz, 2009; Owen, 1975; van der Linden, 1998). This command serves as a subroutine for the nextItem function.

Dichotomous IRT models are considered whenever model is set to NULL (default value). In this case, itemBank 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 itemBank 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.

Under polytomous IRT models, let k be the number of administered items, and set $x_1, ..., x_k$ as the provisional response pattern (where each response $x_l$ takes values in $\{0, 1, ..., g_l\}$). Set $\hat{\theta}_k$ as the provisional ability estimate (with the first k responses) and let j be the item of interest (not previously administered). Set also $P_{jt}(\theta)$ as the probability of answering response category t to item j for a given ability level $\theta$ (thus $t \in \{0, ..., g_j\}$). Finally, set $Var(\theta | x_1, ..., x_k, t)$ as the posterior variance of $\theta$, given the provisional response pattern (updated by response $t$). Then, the EPV for item j equals

$EPV_j = \sum_{t=0}^{g_j} P_{jt}(\hat{\theta}_k)\,Var(\theta | x_1, ..., x_k, t)$

.

In case of dichotomous IRT models, all $g_l$ values reduce to 1, so that item responses $x_l$ equal either 0 or 1. Set simply $P_j(\theta)$ as the probability of answering item j correctly for a given ability level $\theta$, and set $Q_j(\theta)=1-P_j(\theta)$. Finally, set $Var(\theta | x_1, ..., x_k, 0)$ and $Var(\theta | x_1, ..., x_k, 1)$ as the posterior variances of $\theta$, given the provisional response pattern (updated by response 0 and 1 respectively). Then, the EPV for item j reduces to

$EPV_j = P_j(\hat{\theta}_k)\,Var(\theta | x_1, ..., x_k, 1) + Q_j(\hat{\theta}_k)\,Var(\theta | x_1, ..., x_k, 0)$

.

The posterior variances $Var(\theta | x_1, ..., x_k, x_j)$ (where $x_j$ takes value 0 or 1 for dichotomous models, and 0, 1, ..., or $g_j$ for polytomous models) is computed as the squared standard error of the EAP estimate of ability, using the response pattern $(x_1, ..., x_k, x_j)$. This is done by a joint use of the eapEst and eapSem functions.

The prior distribution is set up by the arguments priorDist and priorPar, with the by-default standard normal distribution. The range of integration is defined by the parInt argument, with by default, the sequence from -4 to 4 and of length 33 (or, by steps of 0.25). See the function eapEst for further details.

The provisional response pattern and the related item parameters are provided by the arguments x and it.given respectively. The target item (for which the maximum information computed) is given by its number in the item bank, through the item argument.

Note that the provisional response pattern x can also be set to NULL (which is useful when the number nrItems of starting items is set to zero). In this case, it.given must be a matrix with zero rows, such as e.g., itemBank[NULL,].

Value

The expected posterior variance for the selected item.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Choi, S. W., and Swartz, R. J. (2009). Comparison of CAT item selection criteria for polytomous items. Applied Psychological Measurement, 32, 419-440. doi:10.1177/0146621608327801

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. 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

Owen, R. J. (1975). A Bayesian sequential procedure for quantal response in the context of adaptive mental testing. Journal of the American Statistical Association, 70, 351-356. doi:10.1080/01621459.1975.10479871

van der Linden, W. J. (1998). Bayesian item selection criteria for adaptive testing. Psychometrika, 63, 201-216. doi:10.1007/BF02294775

See Also

nextItem, eapEst, eapSem, genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 bank <- as.matrix(tcals[,1:4])
 
 # Selection of two arbitrary items (15 and 20) of the
 # 'tcals' data set
 it.given <- bank[c(15,20),]

 # Creation of a response pattern
 x <- c(0, 1)

 # EPV for item 1, provisional ability level 0
 EPV(bank, 1, x, 0, it.given)

 # With prior standard deviation 2
 EPV(bank, 1, x, 0, it.given, priorPar = c(0,2))


## 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)

 # Selection of two arbitrary items (15 and 20) 
 it.given <- m.GRM[c(15,20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GRM")

 # EPV for item 1, provisional ability level 0
 EPV(m.GRM, 1, x, 0, it.given, model = "GRM")

 # With prior standard deviation 2
 EPV(m.GRM, 1, x, 0, it.given, model = "GRM", priorPar = c(0, 2))


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

 # Selection of two arbitrary items (15 and 20) 
 it.given <- cat_pav[c(15, 20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GPCM")

 # EPV for item 1, provisional ability level 0
 EPV(cat_pav, 1, x, 0, it.given, model = "GPCM")

 # With prior standard deviation 2
 EPV(cat_pav, 1, x, 0, it.given, model = "GPCM", priorPar = c(0, 2))

---

Full distribution of ability estimator (dichotomous models only)

Description

This command returns the full distribution of the selected ability estimator, that is, the set of all possible ability estimates and related probabilities, for a given matrix of item parameters and ability estimate (or true value).

Usage

fullDist(th, it, method = "BM", priorDist = "norm", priorPar = c(0,1), 
 	weight = "Huber", tuCo  = 1, range = c(-4 ,4), parInt = c(-4, 4, 33))

Arguments

th	numeric: the ability estimate of interest (can be a vector of estimates too).
it	numeric: a suitable matrix of item parameters. See Details.
method	character: the ability estimator. Possible values are "BM" (default), "ML", "WL", "EAP" and "ROB". See Details.
priorDist	character: specifies the prior distribution. Possible values are "norm" (default), "unif" and "Jeffreys". Ignored if method is neither "BM" nor "EAP". See Details.
priorPar	numeric: vector of two components specifying the prior parameters (default is c(0,1)) of the prior ability distribution. Ignored if method is neither "BM" nor "EAP", or if priorDist="Jeffreys". See Details.
weight	character: the type of weight function for the robust estimator. Possible values are "Huber" (default) and "Tukey". Ignored if method is not "ROB" or if model is not NULL. See Details.
tuCo	numeric: the value of the tuning constant for the weight function (default is 1, suitable with "Huber" weight). Ignored if method is not "ROB" or if model is not NULL. See Details.
range	numeric: vector of two components specifying the range wherein the ability estimate must be looked for (default is c(-4,4)). Ignored if method=="EAP".
parInt	numeric: vector of three components, holding respectively the values of the arguments lower, upper and nqp of the eapEst command. Default vector is (-4, 4, 33). Ignored if method is not "EAP".

Details

The computation of the full distribution of an ability estimator is required to determine the exact standard error of ability, compared to the asympotic SE (ASE) displayed by former versions of the semTheta function. This distribution is computed as follows.

First, all possible response patterns (for the given test length fixed by the number of items specified by it argument) are generated through the internal dataGen function. Second, ability estimation is performed with each generated pattern, and the corresponding pattern probability is computed using the set of item parameters it and the predefined ability level th of interest. These to components are eventually returned as the full distribution.

In case of the Rasch (1PL) model, this long process can be shortened as the total test score is a proxy for ability estimation. Hence, with $n$ items, only $(n+1)$ patterns must be created, one for each test score from zero to $n$. Related probabilities can be derived using the Lord-Wingersky algorithm (1984) that is implemented internally through the LW() function.

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).

Five ability estimators are available: the maximum likelihood (ML) estimator (Lord, 1980), the Bayes modal (BM) estimator (Birnbaum, 1969), the expected a posteriori (EAP) estimator (Bock and Mislevy, 1982), the weighted likelihood (WL) estimator (Warm, 1989) and the robust estimator (Schuster & Yuan, 2011). The selected estimator is specified by the method argument, with values "ML", "BM", "EAP", "WL" and "ROB" respectively.

For the BM and EAP estimators, three prior distributions are available: the normal distribution, the uniform distribution and the Jeffreys' prior distribution (Jeffreys, 1939, 1946). The prior distribution is specified by the argument priorPar, with values "norm", "unif" and "Jeffreys", respectively. The priorPar argument is ignored if method="ML" or method="WL".

The argument priorPar determines either: the prior mean and standard deviation of the normal prior distribution (if priorDist="norm"), or the range for defining the prior uniform distribution (if priorDist="unif"). This argument is ignored if priorDist="Jeffreys".

The eapPar argument sets the range and the number of quadrature points for numerical integration in the EAP process. By default, it takes the vector value (-4, 4, 33), that is, 33 quadrature points on the range [-4; 4] (or, by steps of 0.25). See eapEst for further details.

Robust estimation requires an appropriate weight function that depends on an accurate tuning constant. Suggested functions are the Huber weight (Schuester and Yuan, 2011) and the Tukey weight (Mosteller and Tukey, 1977). Both can be set by the weight argument, with respective values "Huber" and "Tukey". Default function is Huber. Moreover, the tuCo argument specifies the tuning constant for the weight function. Default value is 1 and suggested for Huber weight (also by default), and value 4 is suggested for Tukey weight (Schuester and Yuan, 2011).

The ability level of interest (that is, for which the probability distribution must be computed) is specified by theth argument. Note that it can hold a vector of ability levels too; in this case, the probability distribution is computed for each component of th.

Value

A matrix with $(t+1)$ columns (where $t$ is the length of vector th), the first column holding all observable ability estimates and columns 2 to $(t+1)$ with related probabilities of the corresponding components of th.

Note

Under the Rasch (1PL) model, the computation of the full distribution is very efficient even for a large test: due to the Lord-Wingersky algorithm, only $(n+1)$ patterns (where $n$ is the number of items) must be created, one for each possible test score. But for other models, $2^n$ patterns must be generated and used for ability estimation, which can become computationally intensive with long tests. Therefore it is recommended not to make use of this function with more than ten items (except under the Rasch model).

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

Lianne Ippel
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Birnbaum, A. (1969). Statistical theory for logistic mental test models with a prior distribution of ability. Journal of Mathematical Psychology, 6, 258-276. doi:10.1016/0022-2496(69)90005-4

Bock, R. D., and Mislevy, R. J. (1982). Adaptive EAP estimation of ability in a microcomputer environment. Applied Psychological Measurement, 6, 431-444. doi:10.1177/014662168200600405

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.

Jeffreys, H. (1939). Theory of probability. Oxford, UK: Oxford University Press.

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society of London. Series A, Mathematical and Physical Sciences, 186, 453-461.

Lord, F.M. (1980). Applications of item response theory to practical testing problems. Hillsdale, NJ: Lawrence Erlbaum.

Lord, F. M., and Wingersky, M. S. (1984). Comparison of IRT true-score and equipercentile observed-score equatings. Applied Psychological Measurement, 8, 453-461. doi:10.1177/014662168400800409

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

Mosteller, F., and Tukey, J. (1977). Exploratory data analysis and regression. Reading, MA: Addison-Wesley.

Schuester, C., and Yuan, K.-H. (2011). Robust estimation of latent ability in item response models. Journal of Educational and Behavioral Statistics, 36, 720)735.doi:10.3102/1076998610396890

Warm, T.A. (1989). Weighted likelihood estimation of ability in item response models. Psychometrika, 54, 427-450. doi:10.1007/BF02294627

See Also

semTheta, thetaEst,

Examples

## Dichotomous models ##

 # Generation of ten items under 1PL model
 it <- genDichoMatrix(10, model = "1PL")
 
 # Full distribution of ML estimator for ability level zero
 fullDist(0, it, method = "ML")

 # Idem with BM estimator (probabilities don't change, only estimated abilities)
 fullDist(0, it, method = "BM")

 # Idem with ability level 1 (only probabilities change)
 fullDist(1, it, method = "BM")

 # Distributions with two ability levels 1 and 0.5
 fullDist(c(1, 0.5), it, method = "BM")

 # Generation of ten items under 2PL model
 it2 <- genDichoMatrix(10, model = "2PL")
 
 # Full distribution of ML estimator for ability level zero
 fullDist(0, it2, method = "ML")

---

Global-discrimination index (GDI) and posterior global-discrimination index (GDIP) for item selection

Description

This command returns the value of the global-discrimination index (GDI) and posterior global-discrimination index (GDIP) for a given item, an item bank and a set of previously administered items.

Usage

GDI(itemBank, item, x, it.given, model = NULL, lower = -4, upper = 4, nqp = 33, 
 	type = "GDI", priorDist="norm", priorPar = c(0, 1), D = 1, X = NULL, 
 	lik = NULL)

Arguments

itemBank	numeric: a suitable matrix of item parameters. See Details.
item	numeric: the item (referred to as its rank in the item bank) for which the GDI or GDIP must be computed.
x	numeric: a vector of item responses, coded as 0 or 1 only (for dichotomous items) or from 0 to the number of response categories minus one (for polytomous items).
it.given	numeric: 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). The number of rows of it must be equal to the length of x.
model	now only NULL (default) for dichotomous models is allowed.
lower	numeric: the lower bound for numercal integration (default is -4).
upper	numeric: the upper bound for numercal integration (default is 4).
nqp	numeric: the number of quadrature points (default is 33).
type	character: the type of index to be computed. Possible values are "GDI" (default) and "GDIP". See Details.
priorDist	character: the prior ability distribution. Possible values are "norm" (default) for the normal distribution, and "unif" for the uniform distribution. Ignored if type is "GDI".
priorPar	numeric: a vector of two components with the prior parameters. If priorDist is "norm", then priorPar contains the mean and the standard deviation of the normal distribution. If priorDist is "unif", then priorPar contains the bounds of the uniform distribution. The default values are 0 and 1 respectively. Ignored if type is "GDI".
D	numeric: the metric constant. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric (Haley, 1952).
X	either a vector of numeric values or NULL (default). See Details.
lik	either a vector of numeric values or NULL (default). See Details.

Details

Global-discrimination index can be used as a rule for selecting the next item in the CAT process (Kaplan, de la Torre, and Barrada, 2015). This command serves as a subroutine for the nextItem function.

Dichotomous IRT models are considered whenever model is set to NULL (default value). In this case, itemBank 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).

Currently both GDI and GDIP are not implemented for polytomous IRT models.

The integrals within GDI and GDIP are approximated by the integrate.catR function. The range of integration is set up by the arguments lower, upper and nqp, giving respectively the lower bound, the upper bound and the number of quadrature points. The default range goes from -4 to 4 with length 33 (that is, by steps of 0.25).

To speed up the computation, both the range of integration of values $\theta$ and the values of the likelihood function $L(\theta)$ can be directly provided to the function through the arguments X and lik. If X is set to NULL (default), the sequence of ability values for integration is determined by the arguments lower, upper and nqp as explained above. If lik is NULL (default), it is also internally computed from an implementation of the likelihood function.

The provisional response pattern and the related item parameters are provided by the arguments x and it.given respectively. The target item (for which the KL information is computed) is given by its rank number in the item bank, through the item argument.

The argument type defines the type of KL information to be computed. The default value, "GDI", computes the GDI indexinformation, while the posterior GDI index is obtained with type="GDIP". For the latter, the priorDist and priorPar arguments fix the prior ability distribution. The normal distribution is set up by priorDist="norm" and then, priorPar contains the mean and the standard deviation of the normal distribution. If priorDist is "unif", then the uniform distribution is considered, and priorPar fixes the lower and upper bounds of that uniform distribution. By default, the standard normal prior distribution is assumed. These arguments are ignored whenever method is "GDI".

Value

The required GDI or GDIP value for the selected item.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

Juan Ramon Barrada
Department of Psychology and Sociology, Universidad Zaragoza, Spain
[email protected]

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.

Kaplan, M., de la Torre, J., and Barrada, J. R. (2015). New item selection methods for cognitive diagnosis computerized adaptive testing. Applied Psychological Measurement, 39, 167-188. doi:10.1177/0146621614554650

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

integrate.catR, nextItem, genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 bank <- as.matrix(tcals[,1:4])
 
 # Selection of two arbitrary items (15 and 20) of the
 # 'tcals' data set
 it.given <- bank[c(15, 20),]

 # Creation of a response pattern
 x <- c(0, 1)

 # GDI for item 1
 GDI(bank, 1, x, it.given)

 # GDIP for item 1
 GDI(bank, 1, x, it.given, type = "GDIP")

 # GDIP for item 1, different integration range
 GDI(bank, 1, x, it.given, type = "GDIP", lower = -2, upper = 2, nqp = 20)

 # GDIP for item 1, uniform prior distribution on the range [-2,2]
 GDI(bank, 1, x, it.given, type = "GDIP", priorDist = "unif", 
    priorPar = c(-2, 2))

 # Computation of likelihood function beforehand
 L <- function(th, r, param) 
  prod(Pi(th, param)$Pi^r * (1 - Pi(th,param)$Pi)^(1 - r))
 xx <- seq(from = -4, to = 4, length = 33)
 y <- sapply(xx, L, x, it.given) 
 GDI(bank, 1, x, it.given, X = xx, lik = y)

---

Item bank generation (dichotomous models)

Description

This command generates an item bank from prespecified parent distributions for use with dichotomous IRT models. Subgroups of items can also be specified for content balancing purposes.

Usage

genDichoMatrix(items = 100, cbControl = NULL, model = "4PL", 
  aPrior = c("norm", 1, 0.2), bPrior = c("norm", 0, 1), 
  cPrior = c("unif", 0, 0.25), dPrior = c("unif", 0.75, 1), seed = 1)

Arguments

items	integer: the number of items to include in the generated item bank.
cbControl	either a list to define subgroups for content balancing or NULL (default). See Details.
model	character: the name of the logistic IRT model, with possible values "1PL", "2PL", "3PL" or "4PL" (default).
aPrior	vector of three components, specifying the prior distribution and item parameters for generating the item discrimination levels. See Details.
bPrior	vector of three components, specifying the prior distribution and item parameters for generating the item difficulty levels. See Details.
cPrior	vector of three components, specifying the prior distribution and item parameters for generating the item lower asymptote levels. See Details.
dPrior	vector of three components, specifying the prior distribution and item parameters for generating the item upper asymptote levels. See Details.
seed	numeric: the random seed number for the generation of item parameters (default is 1). See set.seed for further details.

Details

This function permits to generate an item bank under dichotomous IRT models that is compatible for use with randomCAT.

The number of items to be included in the bank is specified by the items argument. Corresponding item parameters are drawn from distributions to be specified by arguments aPrior, bPrior, cPrior and dPrior for respective parameters $a_i$, $b_i$, $c_i$ and $d_i$ (Barton and Lord, 1981). Each of these arguments is of length 3, the first component containing the name of the distribution and the last two components coding the distribution parameters.

Possible distributions are:

• the normal distribution $N(\mu, \sigma^2)$, available for parameters $a_i$ and $b_i$. It is specified by "norm" as first argument while the latter two arguments contain the values of $\mu$ and $\sigma$ respectively.

• the log-normal distribution $\log N(\mu, \sigma^2)$, available for parameter $a_i$ only. It is specified by "lnorm" as first argument while the latter two arguments contain the values of $\mu$ and $\sigma$ respectively.

• the uniform distribution $U([a,b])$, available for all parameters. It is specified by "unif" as first argument while the latter two arguments contain the values of $a$ and $b$ respectively. Note that taking $a$ and $b$ equal to a common value, say $t$, makes all parameters to be equal to $t$.

• the Beta distribution $Beta(\alpha, \beta)$, available for parameters $c_i$ and $d_i$. It is specified by "beta" as first argument while the latter two arguments contain the values of $\alpha$ and $\beta$ respectively.

Inattention parameters $d_i$ are fixed to 1 if model is not "4PL"; pseudo-guessing parameters $c_i$ are fixed to zero if model is either "1PL" or "2PL"; and discrimination parameters $a_i$ are fixed to 1 if model="1PL". The random generation of item parameters can be controlled by the seed argument.

If required, the distribution of the items across subgroups with specified names can be performed. To do so, the cbControl argument must be supplied with a list of two arguments: (a) the first argument is called $names and contains the different names of the subgroups of items; (b) the second argument is called $props and contains a vector of numeric values, of the same length of names element, with only positive numbers but not necessarily summing to one. For instance, if props is set as c(1, 2, 2) and items to 100, then the three subgroups will hold respectively 20, 40 and 40 items.

Several constraints apply to the arguments of the cbControl list. First, both arguments of cbControl must be of the same length. Second, as already explained, cbControl$props must either sum to 1 (in case of proportions) or to items (in case of integer values). Finally, if proportions are provided to cbControl$props, one can ensure that when multiplied by items they return integer values (so that they can sum up to items).

The random generation of item parameters and the random allocation of items to subgroups of items are both under control by the seed argument.

The output is a data frame with at least four arguments, with names a, b, c and d for respectively the discrimination $a_i$, the difficulty $b_i$, the lower asymptote $c_i$ and the upper asymptote $d_i$ parameters. A fifth argument contains optionally the subgroup names that have been randomly assigned to the generated items, in the proportions specified by the $props argument of the cbControl list.

Value

A data frame with four or five arguments:

a	the generated item discrimination parameters.
b	the generated item difficulty parameters.
c	the generated item lower asymptote parameters.
d	the generated item upper asymptote parameters.
Group	(optional) the distribution of subgroup names across items. Ignored if cbControl is NULL.

Note

The current version of genItemBank is only designed for dichotomous IRT models. Future extensions will hopefully provide the same tool for polytomous IRT models.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

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

nextItem, randomCAT

Examples

# Item bank generation with 500 items
 genDichoMatrix(items = 500)

 # Item bank generation with 100 items, 2PL model and log-normal distribution with 
 # parameters (0, 0.1225) for discriminations
 genDichoMatrix(items = 100, model = "2PL", aPrior = c("lnorm", 0, 0.1225))

 # A completely identical method as for previous example
 genDichoMatrix(items = 100, aPrior = c("lnorm", 0, 0.1225), 
  cPrior = c("unif", 0, 0), dPrior = c("unif", 1, 1))

 # Item bank generation with prespecified content balancing control options 
 cbList <- list(names = c("Group1", "Group2", "Group3", "Group4"), 
        props = c(0.2,0.4,0.3,0.1))
 genDichoMatrix(items = 100, cbControl = cbList)

 # With proportions that do not sum to one
 cbList <- list(names = c("Group1", "Group2", "Group3", "Group4"), props=c(2, 4, 3, 1))
 genDichoMatrix(items = 100, cbControl = cbList)

---

Random generation of item response patterns under dichotomous and polytomous IRT models

Description

This command generates item responses patterns for a given matrix of item parameters of any specified dichotomous or polytomous IRT model and a given (set of) ability value(s).

Usage

genPattern(th, it, model = NULL, D = 1, seed = NULL)

Arguments

th	numeric: a vector of true underlynig ability values (can be a singlre value too).
it	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.
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.
seed	either the random seed value or NULL (default). See Details.

Details

This function permits to randomly generate item responses for a set of given ability levels, specified by the argument thr, and for a given matrix of item parameters, specified by the argument it. Both dichotomous and polytomous IRT models can be considered and item responses are generated accordingly.

For dichotomous models, item responses are generated from Bernoulli draws, using the rbinom function. For polytomous models they are generated from darws from a multinomial distribution, using the rmultinom function. In both cases, success probabilities are obtained from the Pi function.

Note that for polytomous models, item responses are coded as 0 (for the first response category), 1 (for the second category), ..., until $g_j$ (for the last category), in agreement with the notations used in the help files of, e.g., the genPolyMatrix function.

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 random pattern generation can be fixed by setting seed to some numeric value. By default, seed is NULL and the random seed is not fixed.

Value

If th holds a single value, output is a vector with the item responses in the order of appearance of the items in the it matrix. If th is a vector of numeric values, output is a response matrix with one row per th value and one column per item.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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. 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

rbinom and rmultinom for random draws; genPolyMatrix, Pi

Examples

## Dichotomous models ##
 
 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])
 
 # Generation of a response pattern for ability level 0
 genPattern(th = 0, tcals)

 # Generation of 10 response patterns for ability levels randomly drawn from N(0,1)
 genPattern(th = rnorm(10), tcals)

 # Generation of a single response for the first item only
 genPattern(th = 0, tcals[1,])

## 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)

 # Generation of a response pattern for ability level 0
 genPattern(0, m.GRM, model = "GRM")

 # Generation of 10 response patterns for ability levels randomly drawn from N(0,1)
 genPattern(rnorm(10), m.GRM, model = "GRM")

 # Generation of a single response for the first item only
 genPattern(0, m.GRM[1,], model = "GRM")

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

 # Generation of a response pattern for ability level 0
 genPattern(0, cat_pav, model = "GPCM")

 # Generation of a single response for the first item only
 genPattern(0, cat_pav[1,], model = "GPCM")

---

Item bank generation (polytomous models)

Description

This command generates an item bank from prespecified parent distributions for use with polytomous IRT models. Subgroups of items can also be specified for content balancing purposes.

Usage

genPolyMatrix(items = 100, nrCat = 3, model = "GRM", seed = 1, same.nrCat = FALSE,
 	cbControl = NULL)

Arguments

items	integer: the number of items to generate (default is 100).
nrCat	integer: the (maximum) number of response categories to generate (default is 3).
model	character: the type of polytomous IRT model. Possible values are "GRM" (default), "MGRM", "PCM", "GPCM" and "NRM". See Details.
seed	numeric: the random seed for item parameter generation (default is 1).
same.nrCat	logical: should all items have the same number of response categories? (default is FALSE. Ignored if model is either "MGRM" or "RSM". See Details.
cbControl	either a list of accurate format to control for content balancing, or NULL. See Details.

Details

The genPolyMatrix permits to quickly generate a polytomous item bank in suitable format for further use in e.g. computing item response probabilities with the Pi.

The six polytomous IRT models that are supported are:

1. the Graded Response Model (GRM; Samejima, 1969);

2. the Modified Graded Response Model (MGRM; Muraki, 1990);

3. the Partial Credit Model (PCM; Masters, 1982);

4. the Generalized Partial Credit Model (GPCM; Muraki, 1992);

5. the Rating Scale Model (RSM; Andrich, 1978);

6. the Nominal Response Model (NRM; Bock, 1972).

Each model is specified through the model argument, with its accronym surrounded by double quotes (i.e. "GRM" for GRM, "PCM" for PCM, etc.). The default value is "GRM".

For any item $j$, set $(0, ..., g_j)$ as the $g_j+1$ possible response categories. The maximum number of response categories can differ across items under the GRM, PCM, GPCM and NRM, but they are obviously equal across items under the MGRM and RSM. In the latter, set $g$ as the (same) number of response categories for all items. It is possible however to require all items to have the same number of response categories, by fixing the same.nrCat argument to TRUE.

In case of GRM, PCM, GPCM or NRM with same.nrCat being FALSE, the number of response categories $g_j+1$ per item is drawn from a Poisson distribution with parameter nrCat, and this number is restricted to the interval [2; nrCat]. This ensure at least two response categories and at most nrCat categories. In all other cases, each $g_j+1$ is trivially fixed to $g+1 =$ nrCat.

Denote further $P_{jk}(\theta)$ as the probability of answering response category $k \in \{0, ..., g_j\}$ of item $j$. For GRM and MGRM, response probabilities $P_{jk}(\theta)$ are defined through cumulative probabilities, while for PCM, GPCM, RSM and NRM they are directly computed.

For GRM and MGRM, set $P_{jk}^*(\theta)$ as the (cumulative) probability of asnwering response category $k$ or "above", that is $P_{jk}^*(\theta) = Pr(X_j \geq k | \theta)$ where $X_j$ is the item response. It follows obviously that for any $\theta$, $P_{j0}^*(\theta) = 1$ and $P_{jk}^*(\theta) = 0$ when $k>g_j$. Furthermore, response category probabilities are found back by the relationship $P_{jk}(\theta)= P_{jk}^*(\theta)-P_{j,k+1}^*(\theta)$. Then, the GRM is defined by (Samejima, 1969)

$P_{jk}^*(\theta)=\frac{\exp\,[\alpha_j\,(\theta-\beta_{jk})]}{1+\exp\,[\alpha_j\,(\theta-\beta_{jk})]}$

and the MGRM by (Muraki, 1990)

$P_{jk}^*(\theta)=\frac{\exp\,[\alpha_j\,(\theta-b_j+c_k)]}{1+\exp\,[\alpha_j\,(\theta-b_j+c_k)]}.$

The PCM, GPCM, RSM and NRM are defined as "divide-by-total" models (Embretson and Reise, 2000). The PCM has following response category probability (Masters, 1982):

$P_{jk}(\theta)=\frac{\exp\,\sum_{t=0}^k (\theta-\delta_{jt})}{\sum_{r=0}^{g_j}\,\exp\, \sum_{t=0}^r (\theta-\delta_{jt})}\quad \mbox{with} \quad \sum_{t=0}^0 (\theta-\delta_{jt})=0.$

The GPCM has following response category probability (Muraki, 1992):

$P_{jk}(\theta)=\frac{\exp\,\sum_{t=0}^k \alpha_j\,(\theta-\delta_{jt})}{\sum_{r=0}^{g_j}\,\exp\, \sum_{t=0}^r \alpha_j\,(\theta-\delta_{jt})}\quad \mbox{with} \quad \sum_{t=0}^0 \alpha_j\,(\theta-\delta_{jt})=0.$

The RSM has following response category probability (Andrich, 1978):

$P_{jk}(\theta)=\frac{\exp\,\sum_{t=0}^k [\theta-(\lambda_j+\delta_t)]}{\sum_{r=0}^{g_j}\,\exp\, \sum_{t=0}^r [\theta-(\lambda_j+\delta_t)]}\quad \mbox{with} \quad \sum_{t=0}^0 [\theta-(\lambda_j+\delta_t)]=0.$

Finally, the NRM has following response category probability (Bock, 1972):

$P_{jk}(\theta)=\frac{\exp (\alpha_{jk}\,\theta+c_{jk})}{\sum_{r=0}^{g_j} \exp (\alpha_{jr}\,\theta+c_{jr})}\quad \mbox{with} \quad \alpha_{j0}\,\theta+c_{j0}=0.$

The following parent distributions are considered to generate the different item parameters. The $\alpha_j$ parameters of GRM, MGRM and GPCM, as well as the $\alpha_{jk}$ parameters of the NRM, are drawn from a log-normal distribution with mean 0 and standard deviation 0.1225. All other parameters are drawn from a standard normal distribution. Moreover, the $\beta_{jk}$ parameters of the GRM and the $c_k$ parameters of the MGRM are sorted respectively in increasing and decreasing order of $k$, to ensure decreasing trend in the cumulative $P_{jk}^*(\theta)$ probabilities.

The output is a matrix with one row per item and as many columns as required to hold all item parameters. In case of missing response categories, the corresponding parameters are replaced by NA values. Column names refer to the corresponding model parameters. See Details for further explanations and Examples for illustrative examples.

Finally, the output matrix can contain an additional vector with the names of the subgroups to be used for content balancing purposes. To do so, the argument cbControl (with default value is NULL) must contain a list of two elements: (a) the names element with the names of the subgroups, and (b) the props elements with proportions of items per subgroup (of the same length of names element, with only positive numbers but not necessarily summing to one). The cbControl argument is similar to the one in nextItem and randomCAT functions to control for content balancing. The output matrix contains then an additional column, with the names of the subgroups randomly allocated to each item by using random multinomial draws with the probabilities given by cbControl$props.

Value

A matrix with items rows and as many columns as required for the considered IRT model:

• $\max_j \,g_j+1$ columns, holding parameters $(\alpha_j, \beta_{j1}, ..., \beta_{j,g_j})$ if model is "GRM";

• $g+2$ columns, holding parameters $(\alpha_j, b_j, c_1, ..., c_g)$ if model is "MGRM";

• $\max_j \,g_j$ columns, holding parameters $(\delta_{j1}, ..., \delta_{j,g_j})$ if model is "PCM";

• $\max_j \,g_j+1$ columns, holding parameters $(\alpha_j, \delta_{j1}, ..., \delta_{j,g_j})$ if model is "GPCM";

• $g+1$ columns, holding parameters $(\lambda_j, \delta_1, ..., \delta_g)$ if model is "RSM";

• $2\,\max_j\, g_j$ columns, holding parameters $(\alpha_{j1}, c_{j1}, \alpha_{j2}, c_{j2}, ..., \alpha_{j,g_j}, c_{j, g_j})$ if model is "NRM".

If cbControl is not NULL, the output matrix contains an additional colum for item membership is included.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

References

Andrich, D. (1978). A rating formulation for ordered response categories. Psychometrika, 43, 561-573. doi:10.1007/BF02293814

Bock, R. D. (1972). Estimating item parameters and latent ability when responses are scored in two or more nominal categories. Psychometrika, 37, 29-51. doi:10.1007/BF02291411

Embretson, S. E., and Reise, S. P. (2000). Item response theory for psychologists. Mahwah, NJ: Lawrence Erlbaum Associates.

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

Masters, G. N. (1982). A Rasch model for partial credit scoring. Psychometrika, 47, 149-174. doi:10.1007/BF02296272

Muraki, E. (1990). Fitting a polytomous item response model to Likert-type data. Applied Psychological Measurement, 14, 59-71. doi:10.1177/014662169001400106

Muraki, E. (1992). A generalized partial credit model: Application of an EM algorithm. Applied Psychological Measurement, 16, 19-176. doi:10.1177/014662169201600206

Samejima, F. (1969). Estimation of latent ability using a response pattern of graded scores. Psychometrika Monograph (vol. 17).

See Also

Pi

Examples

# All generated item banks have 10 items and at most four response categories

 # GRM 
 genPolyMatrix(10, 4, model = "GRM")

 # GRM with same number of response categories
 genPolyMatrix(10, 4, model = "GRM", same.nrCat = TRUE)

 # MGRM 
 genPolyMatrix(10, 4, model = "MGRM")

 # MGRM with same number of response categories
 genPolyMatrix(10, 4, model = "MGRM", same.nrCat = TRUE) # same result

 # PCM 
 genPolyMatrix(10, 4, model = "PCM")

 # PCM with same number of response categories
 genPolyMatrix(10, 4, model = "PCM", same.nrCat = TRUE) 

 # GPCM 
 genPolyMatrix(10, 4, model = "GPCM")

 # GPCM with same number of response categories
 genPolyMatrix(10, 4, model = "GPCM", same.nrCat = TRUE) 

 # RSM 
 genPolyMatrix(10, 4, model = "RSM")

 # RSM with same number of response categories
 genPolyMatrix(10, 4, model = "RSM", same.nrCat = TRUE) # same result

 # NRM 
 genPolyMatrix(10, 4, model = "NRM")

 # NRM with same number of response categories
 genPolyMatrix(10, 4, model = "NRM", same.nrCat = TRUE)  

## Content balancing

 # 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))

 # NRM with 100 items
 genPolyMatrix(100, 4, model = "NRM", cbControl = cbList)

---

Item information functions, first and second derivatives (dichotomous and polytomous models)

Description

This command returns the Fisher information functions for a given ability value and a given matrix of item parameters under either the 4PL model or any suitable polytomous model. Numerical values of the first and second derivatives of the item information functions are also returned.

Usage

Ii(th, it, model = NULL, D = 1)

Arguments

th	numeric: the ability value.
it	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.
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.

Details

The first and second derivatives are computed algebraically, either from the four-parameter logistic (4PL) model (Barton and Lord, 1981) or from the corresponding polytomous model. These derivatives are necessary for both the estimation of ability and the computation of related standard errors.

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.

Value

A list with three arguments:

Ii	the vector with item informations (one value per item).
dIi	the vector with first derivatives of the item information functions (one value per item).
d2Ii	the vector with second derivatives of the item information functions (one value per item).

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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. 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

Pi, thetaEst, genPolyMatrix

Examples

## Dichotomous models ##
 
 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])
 
 # Item information functions and derivatives
 # (various th and D values)
 Ii(th = 0, tcals)
 Ii(th = 0, tcals, D = 1.702)
 Ii(th = 1, tcals)

## 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)

 # Computation of item information and derivatives for ability level 0
 Ii(0, m.GRM, model = "GRM")

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

 # Computation of item information and derivatives for ability level 1
 Ii(1, cat_pav, model = "GPCM")

---

Numerical integration by linear interpolation (for catR internal use)

Description

This command computes the integral of function f(x) by providing values of x and f(x), similarly to the integrate.xy function of the R package sfsmisc.

Usage

integrate.catR(x, y)

Arguments

x	numeric: a vector of x values for numerical integration.
y	numeric: a vector of numerical values corresponding to f(x) values.

Details

This function was written to compute "cheap" numerical integration by providing sequences of x values and corresponding computed values f(x). It works similarly as the integrate.xy function when use.spline=FALSE is required. It was developed internally to eventually remove dependency of catR package to package sfsmisc.

Value

The approximated integral.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

References

Maechler, M. et al. (2012). sfsmisc: Utilities from Seminar fuer Statistik ETH Zurich. R package version 1.0-23. http://CRAN.R-project.org/package=sfsmisc

See Also

KL and the integrate.xy function in package sfsmisc

Examples

# Loading the 'tcals' parameters 
 x <- seq(from = -4, to = 4, length = 33)
 y <- exp(x)
 integrate.catR(x, y) # 54.86381

## Not run: 
 # Comparison with integrate.xy
 require(sfsmisc)
 integrate.xy(x, y, use.spline = FALSE) # 54.86381
 integrate.xy(x, y) # 54.58058
 
## End(Not run)

---

Function $J(\theta)$ for weighted likelihood estimation (dichotomous and polytomous IRT models)

Description

This command returns the $J(\theta)$ function that is necessary to obtain the weighted likelihood estimation of ability with dichotomous and polytomous IRT models, as well as its asymptotic standard error.

Usage

Ji(th, it, model = NULL, D = 1)

Arguments

th	numeric: the ability value.
it	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.
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.

Details

The $J(\theta)$ fucntion is defined by (Samejima, 1998):

$J(\theta)=\sum_{j=1}^n \,\sum_{k=0}^{g_j} \frac{P_{jk}'(\theta)\,P_{jk}''(\theta)}{P_{jk}(\theta)}$

where $n$ is the number of items; $g_j$ the number of response categories for item j ($j=1, ..., n$); $P_{jk}(\theta)$ the response category probabilities and $P_{jk}'(\theta)$ and $P_{jk}''(\theta)$ the first and second derivatives with respect to $\theta$. In case of dichotomous IRT models, this reduces to (Warm, 1989):

$J(\theta)=\sum_{j=1}^n \frac{P_j'(\theta)\,P_j''(\theta)}{P_j(\theta)\,Q_j(\theta)}$

with $Q_j(\theta)=1-P_j(\theta)$.

This function is useful to compute the weighted likelihood estimates of ability with dichotomous and polytomous IRT models as well as their related asymptotic standard errors.

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.

Value

A list with two arguments:

Ji	the vector with $J(\theta)$ values (one value per item).
dJi	the vector with first derivatives of the $J(\theta)$ values (one value per item).

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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. 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

Samejima, F. (1998, April). Expansion of Warm's weighted likelihood estimator of ability for the three-parameter logistic model to generate discrete responses. PPaper presented at the annual meeting of the National Council on Measurement in Education, San Diego, CA.

Warm, T.A. (1989). Weighted likelihood estimation of ability in item response models. Psychometrika, 54, 427-450. doi:10.1007/BF02294627

See Also

thetaEst, semTheta, genPolyMatrix

Examples

## Dichotomous models ##
 
 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 tcals <- as.matrix(tcals[,1:4])
 
 # Various J functions and derivatives
 # (various th and D values)
 Ji(th = 0, tcals)
 Ji(th = 0, tcals, D = 1.702)
 Ji(th = 1, tcals)

## 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)

 # Computation of J function and derivatives for ability level 0
 Ji(0, m.GRM, model = "GRM")

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

 # Computation of J function and derivatives for ability level 1
 Ji(1, cat_pav, model = "GPCM")

---

Kullback-Leibler (KL) and posterior Kullback-Leibler (KLP) values for item selection

Description

This command returns the value of the Kullback-Leibler (KL) or posterior Kullback-Leibler (KLP) for a given item, an item bank and a set of previously administered items.

Usage

KL(itemBank, item, x, it.given, model = NULL, theta = NULL, lower = -4, 
  upper = 4, nqp = 33, type = "KL", priorDist = "norm", priorPar = c(0, 1), 
  D = 1, X = NULL, lik = NULL)

Arguments

itemBank	numeric: a suitable matrix of item parameters. See Details.
item	numeric: the item (referred to as its rank in the item bank) for which the KL or KLP must be computed.
x	numeric: a vector of item responses, coded as 0 or 1 only (for dichotomous items) or from 0 to the number of response categories minus one (for polytomous items).
it.given	numeric: 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). The number of rows of it must be equal to the length of x.
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.
theta	either a numeric value for provisional ability estimate or NULL. See Details.
lower	numeric: the lower bound for numercal integration (default is -4).
upper	numeric: the upper bound for numercal integration (default is 4).
nqp	numeric: the number of quadrature points (default is 33).
type	character: the type of information to be computed. Possible values are "KL" (default) and "KLP". See Details.
priorDist	character: the prior ability distribution. Possible values are "norm" (default) for the normal distribution, and "unif" for the uniform distribution. Ignored if type is "KL".
priorPar	numeric: a vector of two components with the prior parameters. If priorDist is "norm", then priorPar contains the mean and the standard deviation of the normal distribution. If priorDist is "unif", then priorPar contains the bounds of the uniform distribution. The default values are 0 and 1 respectively. Ignored if type is "KL".
D	numeric: the metric constant. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric (Haley, 1952).
X	either a vector of numeric values or NULL (default). See Details.
lik	either a vector of numeric values or NULL (default). See Details.

Details

Kullback-Leibler information can be used as a rule for selecting the next item in the CAT process (Barrada, Olea, Ponsoda and Abad, 2010; Chang and Ying, 1996), both with dichotomous and polytomous IRT models. This command serves as a subroutine for the nextItem function.

Dichotomous IRT models are considered whenever model is set to NULL (default value). In this case, itemBank 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 itemBank 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.

Under polytomous IRT models, let k be the number of administered items, and set $x_1, ..., x_k$ as the provisional response pattern (where each response $x_l$ takes values in $\{0, 1, ..., g_l\}$). Set $\hat{\theta}_k$ as the provisional ability estimate (with the first k responses) and let j be the item of interest (not previously administered). Set also $L(\theta | x_1, ..., x_k)$ as the likelihood function of the first $k$ items and evaluated at $\theta$. Set finally $P_{jt}(\theta)$ as the probability of answering response category t to item j for a given ability level $\theta$. Then, Kullack-Leibler (KL) information is defined as

$KL_j(\theta || \hat{\theta}_k) = \sum_{t=0}^{g_j} \,P_{jt}(\hat{\theta}_k) \,\log \left( \frac{P_{jt}(\hat{\theta}_k)}{P_{jt}(\theta)}\right).$

In case of dichotomous IRT models, all $g_l$ values reduce to 1, so that item responses $x_l$ equal either 0 or 1. Set simply $P_j(\theta)$ as the probability of answering item j correctly for a given ability level $\theta$. Then, KL information reduces to

$KL_j(\theta || \hat{\theta}) = P_j(\hat{\theta}) \,\log \left( \frac{P_j(\hat{\theta}_k)}{P_j(\theta)}\right) + [1-P_j(\hat{\theta}_k)] \,\log \left( \frac{1-P_j(\hat{\theta}_k)}{1-P_j(\theta)}\right).$

The quantity that is returned by this KL function is either: the likelihood function weighted by Kullback-Leibler information (the KL value):

$KL_j(\hat{\theta}_k) = \int KL_j(\theta || \hat{\theta}_k) \, L(\theta | x_1, ..., x_k) \,d\theta$

or the posterior function weighted by Kullback-Leibler information (the KLP value):

$KLP_j(\hat{\theta}) = \int KL_j(\theta || \hat{\theta}_k) \, \pi(\theta) \,L(\theta | x_1, ..., x_k) \,d\theta$

where $\pi(\theta)$ is the prior distribution of the ability level.

These integrals are approximated by the integrate.catR function. The range of integration is set up by the arguments lower, upper and nqp, giving respectively the lower bound, the upper bound and the number of quadrature points. The default range goes from -4 to 4 with length 33 (that is, by steps of 0.25).

To speed up the computation, both the range of integration of values $\theta$ and the values of the likelihood function $L(\theta)$ can be directly provided to the function through the arguments X and lik. If X is set to NULL (default), the sequence of ability values for integration is determined by the arguments lower, upper and nqp as explained above. If lik is NULL (default), it is also internally computed from an implementation of the likelihood function.

The provisional response pattern and the related item parameters are provided by the arguments x and it.given respectively. The target item (for which the KL information is computed) is given by its rank number in the item bank, through the item argument.

An ability level estimate must be provided to compute KL and KLP information values. Either the value is specified through the theta argument, or it is left equal to NULL (default). In this case, ability estimate is computed internally by maximum likelihood, using the thetaEst function with arguments it.given and x.

Note that the provisional response pattern x can also be set to NULL (which is useful when the number nrItems of starting items is set to zero). In this case, it.given must be a matrix with zero rows, such as e.g., itemBank[NULL,]. In this very specific configuration, the likelihood function $L(\theta | x_1, ..., x_k)$ reduces to the constant value 1 on the whole $\theta$ range (that is, a uniform likelihood).

The argument type defines the type of KL information to be computed. The default value, "KL", computes the usual Kullback-Leibler information, while the posterior Kullback-Leibler value is obtained with type="KLP". For the latter, the priorDist and priorPar arguments fix the prior ability distribution. The normal distribution is set up by priorDist="norm" and then, priorPar contains the mean and the standard deviation of the normal distribution. If priorDist is "unif", then the uniform distribution is considered, and priorPar fixes the lower and upper bounds of that uniform distribution. By default, the standard normal prior distribution is assumed. These arguments are ignored whenever method is "KL".

Value

The required KL or KLP value for the selected item.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

Juan Ramon Barrada
Department of Psychology and Sociology, Universidad Zaragoza, Spain
[email protected]

References

Barrada, J. R., Olea, J., Ponsoda, V., and Abad, F. J. (2010). A method for the comparison of item selection rules in computerized adaptive testing. Applied Psychological Measurement, 20, 213-229. doi:10.1177/0146621610370152

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.

Chang, H.-H., and Ying, Z. (1996). A global information approach to computerized adaptive testing. Applied Psychological Measurement, 34, 438-452. doi:10.1177/014662169602000303

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. 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

integrate.catR, nextItem, genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 bank <- as.matrix(tcals[,1:4])
 
 # Selection of two arbitrary items (15 and 20) of the
 # 'tcals' data set
 it.given <- bank[c(15, 20),]

 # Creation of a response pattern
 x <- c(0, 1)

 # KL for item 1, ML estimate of ability computed
 KL(bank, 1, x, it.given)

 # Current (ML) ability estimate 
 theta <- thetaEst(it.given, x, method = "ML")
 KL(bank, 1, x, it.given, theta = theta)

 # WL ability estimate instead
 theta <- thetaEst(it.given, x, method = "WL")
 KL(bank, 1, x, it.given, theta = theta)

 # KLP for item 1
 KL(bank, 1, x, it.given, theta = theta, type = "KLP")

 # KLP for item 1, different integration range
 KL(bank, 1, x, it.given, theta = theta, type = "KLP", lower = -2, upper = 2, nqp = 20)

 # KL for item 1, uniform prior distribution on the range [-2,2]
 KL(bank, 1, x, it.given, theta = theta, type = "KLP", priorDist = "unif", 
    priorPar = c(-2, 2))

 # Computation of likelihood function beforehand
 L <- function(th, r, param) 
  prod(Pi(th, param)$Pi^r * (1 - Pi(th,param)$Pi)^(1 - r))
 xx <- seq(from = -4, to = 4, length = 33)
 y <- sapply(xx, L, x, it.given) 
 KL(bank, 1, x, it.given, theta = theta, X = xx, lik = y)


## 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)

 # Selection of two arbitrary items (15 and 20) 
 it.given <- m.GRM[c(15, 20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GRM")

 # KL for item 1, ML estimate of ability computed
 KL(m.GRM, 1, x, it.given, model = "GRM")

 # Current (ML) ability estimate 
 theta <- thetaEst(it.given, x, method = "ML", model = "GRM")
 KL(m.GRM, 1, x, it.given, theta = theta, model = "GRM")

 # WL ability estimate instead
 theta <- thetaEst(it.given, x, method = "WL", model = "GRM")
 KL(m.GRM, 1, x, it.given, theta = theta, model = "GRM")

 # KLP for item 1
 KL(m.GRM, 1, x, it.given, theta = theta, model = "GRM", type = "KLP")

 # KLP for item 1, different integration range
 KL(m.GRM, 1, x, it.given, theta = theta, model = "GRM", type = "KLP", lower = -2, 
    upper = 2, nqp = 20)

 # KL for item 1, uniform prior distribution on the range [-2,2]
 KL(m.GRM, 1, x, it.given, theta = theta, model = "GRM", type = "KLP", 
    priorDist = "unif", priorPar = c(-2, 2))


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

 # Selection of two arbitrary items (15 and 20) 
 it.given <- cat_pav[c(15, 20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GPCM")

  # KL for item 1, ML estimate of ability computed
 KL(cat_pav, 1, x, it.given, model = "GPCM")

 # Current (ML) ability estimate 
 theta <- thetaEst(it.given, x, method = "ML", model = "GPCM")
 KL(cat_pav, 1, x, it.given, theta = theta, model = "GPCM")

 # WL ability estimate instead
 theta <- thetaEst(it.given, x, method = "WL", model = "GPCM")
 KL(cat_pav, 1, x, it.given, theta = theta, model = "GPCM")

 # KLP for item 1
 KL(cat_pav, 1, x, it.given, theta = theta, model = "GPCM", type = "KLP")

 # KLP for item 1, different integration range
 KL(cat_pav, 1, x, it.given, theta = theta, model = "GPCM", type = "KLP", lower = -2, 
    upper = 2, nqp = 20)

 # KL for item 1, uniform prior distribution on the range [-2,2]
 KL(cat_pav, 1, x, it.given, theta = theta, model = "GPCM", type = "KLP", 
    priorDist = "unif", priorPar = c(-2, 2))

---

(Maximum) Expected Information (MEI)

Description

This command returns the expected information (EI) for a given item (under dichotomous and polytomous IRT models), as used for Maximum Expected Information (MEI) criterion.

Usage

MEI(itemBank, item, x, theta, it.given, model = NULL, method = "BM", 
 	priorDist = "norm", priorPar = c(0, 1), D = 1, range = c(-4, 4), 
 	parInt = c(-4, 4, 33), infoType = "observed")

Arguments

itemBank	numeric: a suitable matrix of item parameters. See Details.
item	numeric: the item (referred to as its rank in the item bank) for which the expected information must be computed.
x	numeric: a vector of item responses, coded as 0 or 1 only (for dichotomous items) or from 0 to the number of response categories minus one (for polytomous items).
theta	numeric: the provisional ability estimate.
it.given	numeric: a suitable matrix of item parameters for previously administered items. The number of rows of it.given must be equal to the length of x.
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.
method	character: the ability estimator. Possible values are "BM" (default), "ML" and "WL". See Details.
priorDist	character: specifies the prior distribution. Possible values are "norm" (default), "unif" and "Jeffreys". Ignored if method is neither "BM" nor "EAP". See Details.
priorPar	numeric: vector of two components specifying the prior parameters (default is c(0,1)) of the prior ability distribution. Ignored if method is neither "BM" nor "EAP", or if priorDist="Jeffreys". See Details.
D	numeric: the metric constant. Default is D=1 (for logistic metric); D=1.702 yields approximately the normal metric (Haley, 1952).
range	numeric: vector of two components specifying the range wherein the ability estimate must be looked for (default is c(-4,4)). Ignored if method=="EAP".
parInt	numeric: vector of three components, holding respectively the values of the arguments lower, upper and nqp of the eapEst command. Default vector is (-4, 4, 33). Ignored if method is not "EAP".
infoType	character: the type of information function to be used. Possible values are "observed" (default) for observed information function, and "Fisher" for Fisher information function.

Details

The MEI (van der Linden, 1998; van der Linden and Pashley, 2000) can be used as a rule for selecting the next item in the CAT process (see also Choi and Swartz, 2009), both with dichotomous and polytomous IRT models. This command serves as a subroutine for the nextItem function.

Dichotomous IRT models are considered whenever model is set to NULL (default value). In this case, itemBank 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 itemBank 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.

Under polytomous IRT models, let k be the number of administered items, and set $x_1, ..., x_k$ as the provisional response pattern (where each response $x_l$ takes values in $\{0, 1, ..., g_l\}$). Set $\hat{\theta}_k$ as the provisional ability estimate (with the first k responses) and let j be the item of interest (not previously administered). Set also $P_{jt}(\theta)$ as the probability of answering response category t to item j for a given ability level $\theta$. Finally, set $\hat{\theta}_{k+1}^t$ as the ability estimates computed under the condition that the response to item j is t (with $t=0, ..., g_j$). Then, the EI for item j equals

$EI_j = \sum_{t=0}^{g_j} P_{jt}(\hat{\theta}_k)\,I_j(\hat{\theta}_{k+1}^t)$

where $I_j(\theta)$ is the information function for item j.

In case of dichotomous IRT models, all $g_l$ values reduce to 1, so that item responses $x_l$ equal either 0 or 1. Set simply $P_j(\theta)$ as the probability of answering item j correctly for a given ability level $\theta$, and set $Q_j(\theta)=1-P_j(\theta)$. Finally, set $\hat{\theta}_{k+1}^0$ and $\hat{\theta}_{k+1}^1$ as the ability estimates computed under the condition that the response to item j is 0 or 1 respectively (that is, if the response pattern is updated by 0 or 1 for item j). Then, the EI for item j reduces to

$EI_j = P_j(\hat{\theta}_k)\,I_j(\hat{\theta}_{k+1}^1) + Q_j(\hat{\theta}_k)\,I_j(\hat{\theta}_{k+1}^0)$

.

Two types of information functions are available. The first one is the observed information function, defined as

$OI_j(\theta) = -\frac{\partial^2}{\partial \theta^2} \,\log L(\theta | x_j)$

(van der Linden, 1998), where $L(\theta | x_j)$ is the likelihood related to item j. The second one is Fisher information function:

$I_j(\theta) = -E\,\left[\frac{\partial^2}{\partial\,\theta^2} \,\log L(\theta | x_j))\right].$

Under the 1PL and the 2PL models, these functions are identical (Veerkamp, 1996). See also OIi.

The observed and Fisher information functions are specified by the infoType argument, with respective values "observed" and "Fisher". By default, the observed information function is considered (Choi and Swartz, 2009; van der Linden, 1998).

The estimator of provisional ability is defined by means of the arguments method, priorDist, priorPar, D, range and parInt of the thetaEst function. See the corresponding help file for further details.

The provisional response pattern and the related item parameters are provided by the arguments x and it.given respectively. The target item (for which the maximum information computed) is given by its number in the item bank, through the item argument.

Note that the provisional response pattern x can also be set to NULL (which is useful when the number nrItems of starting items is set to zero). In this case, it.given must be a matrix with zero rows, such as e.g., itemBank[NULL,].

Value

The required expected information for the selected item.

Author(s)

David Magis
Department of Psychology, University of Liege, Belgium
[email protected]

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.

Choi, S. W., and Swartz, R. J. (2009). Comparison of CAT item selection criteria for polytomous items. Applied Psychological Measurement, 32, 419-440. doi:10.1177/0146621608327801

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. 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

van der Linden, W. J. (1998). Bayesian item selection criteria for adaptive testing. Psychometrika, 63, 201-216. doi:10.1007/BF02294775

van der Linden, W. J., and Pashley, P. J. (2000). Item selection and ability estimation in adaptive testing. In W. J. van der Linden and C. A. W. Glas (Eds.), Computerized adaptive testing. Theory and practice (pp. 1-25). Boston, MA: Kluwer.

Veerkamp, W. J. J. (1996). Statistical inference for adaptive testing. Internal report. Enschede, The Netherlands: University of Twente.

See Also

Ii, OIi, nextItem, thetaEst, genPolyMatrix

Examples

## Dichotomous models ##

 # Loading the 'tcals' parameters 
 data(tcals)

 # Selecting item parameters only
 bank <- as.matrix(tcals[,1:4])
 
 # Selection of two arbitrary items (15 and 20) of the
 # 'tcals' data set
 it.given <- bank[c(15, 20),]

 # Creation of a response pattern
 x <- c(0, 1)

 # MEI for item 1, provisional ability level 0
 MEI(bank, 1, x, 0, it.given)

 # With Fisher information instead
 MEI(bank, 1, x, 0, it.given, infoType = "Fisher")

 # With WL estimator instead
 MEI(bank, 1, x, 0, it.given, method = "WL")


## 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)

 # Selection of two arbitrary items (15 and 20) 
it.given <- m.GRM[c(15, 20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GRM")

 # EPV for item 1, provisional ability level 0
 MEI(m.GRM, 1, x, 0, it.given, model = "GRM")

 # With WL method
 MEI(m.GRM, 1, x, 0, it.given, model = "GRM", method = "WL")

 # With Fisher information
 MEI(m.GRM, 1, x, 0, it.given, model = "GRM", infoType = "Fisher")

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

 # Selection of two arbitrary items (15 and 20) 
 it.given <- cat_pav[c(15, 20),]

 # Generation of a response pattern (true ability level 0)
 x <- genPattern(0, it.given, model = "GPCM")

 # EPV for item 1, provisional ability level 0
 MEI(cat_pav, 1, x, 0, it.given, model = "GPCM")

 # With WL method
 MEI(cat_pav, 1, x, 0, it.given, model = "GPCM", method = "WL")

 # With Fisher information
 MEI(cat_pav, 1, x, 0, it.given, model = "GPCM", infoType = "Fisher")

---