Input.Checking {IRTBEMM}R Documentation

Checking user speciflied input variables.

Description

Based on the given model, checking whether user speciflied input variables are correct. If the input variables are acceptable, this function will format them and then return them as a list. Otherwise, this function will return a error message to indicate which variables are unacceptable.

Usage

Input.Checking(Model, data, 
	PriorA=c(0,0.25), PriorB=c(0,4), PriorC=c(4,16), PriorS=c(4,16),
	PriorAlpha=c(-1.9,1), PriorBeta=c(0,4), PriorGamma=c(-1.39,0.25),
	InitialA=NA, InitialB=NA, InitialC=NA, InitialS=NA,
	InitialAlpha=NA, InitialBeta=NA, InitialGamma=NA,
	Tol=0.0001, max.ECycle=1000L, max.MCycle=100L, n.Quadpts=31L, n.decimal=3L, 
	Theta.lim=c(-6,6), Missing=-9, ParConstraint=FALSE, BiasSE=FALSE)

Arguments

Model

A character to declare the type of items to be modeled. The parameter labels follow conventional use, can be:

  • '3PL' - Three parameter logistic (3PL) model proposed by Birnbaum(1968):

    P(x = 1|\theta, a, b, c) = c + (1 - c) / (1 + exp(-D * a * (\theta - b)))

    where x=1 is the correct response, theta is examinne's ability; a, b and c are the item discrimination, difficulty and guessing parameter, respectively; D is the scaling constant 1.702.

  • '4PL' - Four parameter logistic (4PL) model proposed by Barton & Lord's(1981). Transfer the unslipping (upper asymptote) parameter d to slipping parameter s by set s=1-d:

    P(x = 1|\theta, a, b, c, s) = c + (1 - s - c) / (1 + exp(-D * a * (\theta - b)))

    where x=1 is the correct response; theta is examinne's ability. a, b, c and s are the item discrimination, difficulty guessing and slipping parameter, respectively; D is the scaling constant 1.702.

  • '1PLG' - One parameter logsitc guessing (1PLG) model proposed by San Martín et al.(2006). Let invlogit(x)=1 / (1 + exp(-x)):

    P(x = 1|\theta, \beta, \gamma) = invlogit(\theta - \beta) + (1 - invlogit(\theta - \beta)) * invlogit(\gamma)

    where x=1 is the correct response, theta is examinne's ability; beta and gamma are the item difficulty and guessing parameter, respectively.

  • '1PLAG' - One parameter logsitc ability-based guessing (1PLAG) model proposed by San Martín et al.(2006). Let invlogit(x)=1 / (1 + exp(-x)):

    P(x = 1|\theta, \alpha, \beta, \gamma) = invlogit(\theta - \beta) + (1 - invlogit(\theta - \beta)) * invlogit(\alpha * \theta + \gamma)

    where x=1 is the correct response, theta is examinne's ability; alpha is the weight of the ability in the guessing component; beta and gamma are the item difficulty and guessing parameter, respectively.

These parameter labels are capitalized in program for emphasis.

data

A matrix or data.frame consists of dichotomous data (1 for correct and 0 for wrong response), with missing data coded as in Missing (by default, Missing=-9). Each row of data represents a examinne' responses, and each column represents an item.

PriorA

The user specified logarithmic normal distribution prior for item discrimation (a) parameters in the 3PL and 4PL models. Can be:

  • A numeric with two hyperparameters mean and variance of logarithmic normal distribution for all a parameters. By default, PriorA=c(0,0.25), which means a log normal prior of mean=0 and variance=0.25 will be used for all item discrimation parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item discrimation parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of log normal prior (mean and variance) for single item a parameter.

PriorB

The user specified normal distribution prior for item difficulty (b) parameters in the 3PL and 4PL models. Can be:

  • A numeric with two hyperparameters mean and variance of normal distribution for all b parameters. By default, PriorB=c(0,4), which means a normal prior of mean=0 and variance=4 will be used for all item difficulty parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item difficulty parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of normal prior (mean and variance) for single item b parameter.

PriorC

The user specified Beta(x,y) distribution prior for item guessing (c) parameters in the 3PL and 4PL models. Can be:

  • A numeric with two hyperparameters x and y of Beta distribution for all c parameters. By default, PriorC=c(4,16), which means a Beta prior of mean=4/(4+16)=0.2 and variance=0.008 will be used for all item guessing parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item guessing parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of Beta prior (x and y) for single item c parameter.

PriorS

The user specified Beta(x,y) distribution prior for item slipping (s) parameters in the 4PL model. Can be:

  • A numeric with two hyperparameters x and y of Beta distribution for all s parameters. By default, PriorS=c(4,16), which means a Beta prior of mean=4/(4+16)=0.2 and variance=0.008 will be used for all item slipping parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item slipping parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of Beta prior (x and y) for single item s parameter.

PriorAlpha

The user specified normal distribution prior for the logarithmic weight of the ability in the guessing component (ln(alpha)) parameter in the 1PLAG model. Can be:

  • A numeric with two hyperparameters normal distribution for all log(alpha) parameters. By default, PriorAlpha=c(-1.9,1), which means a Normal prior of mean=-1.9 and variance=1 will be used for the logarithmic weight of the ability.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for the weight of the ability will be obtained.

PriorBeta

The user specified normal distribution prior for item difficulty (beta) parameters in the 1PLAG and 1PLG model. Can be:

  • A numeric with two hyperparameters mean and variance of normal distribution for all beta parameters. By default, PriorBeta=c(0,4), which means a normal prior of mean=0 and variance=4 will be used for all item difficulty parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item difficulty parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of normal prior (mean and variance) for single item beta parameter.

PriorGamma

The user specified normal distribution prior for item guessing (gamma) parameters in the 1PLAG and 1PLG model. Can be:

  • A numeric with two hyperparameters mean and variance of normal distribution for all gamma parameters. By default, PriorGamma=c(-1.39,0.25), which means a normal prior of mean=-1.39 and variance=0.25 will be used for all item guessing parameters.

  • A NA, refers to no priors will be used, so maximum likelihood estimates for item guessing parameter will be obtained.

  • A matrix with two columns, and each row of matrix consists of two hyperparameters of normal prior (mean and variance) for single item gamma parameter.

InitialA

The user specified starting values for item discrimation (a) parameters in the 3PL and 4PL models. Can be:

  • A NA (default), refers to no specified starting values for a parameter.

  • A single number (numeric), refers to set this number to be the starting values of a for all items.

  • A numeric consists of starting values for each a parameter.

InitialB

The user specified starting values for item difficulty (b) parameters in the 3PL and 4PL models. Can be:

  • A NA (default), refers to no specified starting values for b parameter.

  • A single number (numeric), refers to set this number to be the starting values of b for all items.

  • A numeric consists of starting values for each b parameter.

InitialC

The user specified starting values for item guessing (c) parameters in the 3PL and 4PL models. Can be:

  • A NA (default), refers to no specified starting values for c parameter.

  • A single number (numeric), refers to set this number to be the starting values of c for all items.

  • A numeric consists of starting values for each c parameter.

InitialS

The user specified starting values for item slipping (s) parameters in the 4PL model. Can be:

  • A NA (default), refers to no specified starting values for s parameter.

  • A single number (numeric), refers to set this number to be the starting values of s for all items.

  • A numeric consists of starting values for each s parameter.

InitialAlpha

The user specified starting value for the weight of the ability in the guessing component (alpha) parameters in the 1PLAG model. Can be:

  • A NA (default), refers to no specified starting values for alpha parameter.

  • A single number (numeric), refers to set this number to be the starting value of alpha.

InitialBeta

The user specified starting values for item difficulty (beta) parameters in the 1PLAG and 1PLG models. Can be:

  • A NA (default), refers to no specified starting values for beta parameter.

  • A single number (numeric), refers to set this number to be the starting values of beta for all items.

  • A numeric consists of starting values for each beta parameter.

InitialGamma

The user specified starting values for item guessing (gamma) parameters in the 1PLAG and 1PLG models. Can be:

  • A NA (default), refers to no specified starting values for gamma parameter.

  • A single number (numeric), refers to set this number to be the starting values of gamma for all items.

  • A numeric consists of starting values for each gamma parameter.

Tol

A single number (numeric), refers to convergence threshold for E-step cycles; defaults are 0.0001.

max.ECycle

A single integer, refers to maximum number of E-step cycles; defaults are 2000L.

max.MCycle

A single integer, refers to maximum number of M-step cycles; defaults are 100L.

n.Quadpts

A single integer, refers to number of quadrature points per dimension (must be larger than 5); defaults are 31L.

n.decimal

A single integer, refers to number of decimal places when outputs results.

Theta.lim

A numeric with two number, refers to the range of integration grid for each dimension; default is c(-6, 6).

Missing

A single number (numeric) to indicate which elements are missing; default is -9. The Missing cannot be 0 or 1.

ParConstraint

A logical value to indicate whether estimates parametes in a reasonable range; default is FALSE. If ParConstraint=TRUE: a in [0.001, 6], b in [-6, 6], c in [0.0001, 0.5], s in [0.0001, c], alpha in [0, 0.707], beta in [-6, 6], gamma in [-7, 0].

BiasSE

A logical value to determine whether directly estimating SEs from inversed Hession matrix rather than USEM method, default is FALSE.

References

Barton, M. A., & Lord, F. M. (1981). An upper asymptote for the three-parameter logistic item response model. ETS Research Report Series, 1981(1), 1-8. doi:10.1002/j.2333-8504.1981.tb01255.x

Birnbaum, A. (1968). Some latent trait models and their use in inferring an examinee's ability. In F. M. Lord & M. R. Novick (Eds.), Statistical theories of mental test scores (pp. 395-479). MA: Adison-Wesley.

San Martín, E., Del Pino, G., & De Boeck, P. (2006). IRT models for ability-based guessing. Applied Psychological Measurement, 30(3), 183-203. doi:10.1177/0146621605282773

Examples

#An example to show the error message when the variance of a normal prior is negative.
library(IRTBEMM)
#generate a response matrix with 1000 examinees and 10 items randomly
data=matrix(rbinom(10000,1,0.5), 1000, 10)  
#test whether variable data is correct.
res=Input.Checking('3PL',data)
[Package IRTBEMM version 1.0.8 Index]