tam.jml: Joint Maximum Likelihood Estimation

Description

This function estimate unidimensional item response models with joint maximum likelihood (JML, see e.g. Linacre, 1994).

Usage

tam.jml(resp, group=NULL, adj=.3, disattenuate=FALSE, bias=TRUE,
    xsi.fixed=NULL, xsi.inits=NULL, theta.fixed=NULL, A=NULL, B=NULL, Q=NULL,
    ndim=1, pweights=NULL, constraint="cases", verbose=TRUE, control=list(), version=3)
# S3 method for tam.jml
summary(object, file=NULL, ...)
# S3 method for tam.jml
logLik(object, ...)

Value

A list with following entries

item1: Data frame with item parameters
xsi: Vector of item parameters $\xi$
errorP: Standard error of item parameters $\xi$
theta: MLE in final step
errorWLE: Standard error of WLE
WLE: WLE in last iteration
WLEreliability: WLE reliability
PersonScores: Scores for each person (sufficient statistic)
ItemScore: Sufficient statistic for each item parameter
PersonMax: Maximum person score
ItemMax: Maximum item score
deviance: Deviance
deviance.history: Deviance history in iterations
resp: Original data frame
resp.ind: Response indicator matrix
group: Vector of group identifiers (if provided as an argument)
pweights: Vector of person weights
A: Design matrix $A$ of item intercepts
B: Loading (or scoring) matrix $B$
nitems: Number of items
maxK: Maximum number of categories
nstud: Number of persons in resp
resp.ind.list: Like resp.ind, only in the format of a list
xsi.fixed: Fixed $\xi$ item parameters
control: Control list
item: Extended data frame of item parameters
theta_summary: Summary of person parameters
...

Arguments

resp: A matrix of item responses. Missing responses must be declared as NA.
group: An optional vector of group identifier
disattenuate: An optional logical indicating whether the person parameters should be disattenuated due to unreliability? The disattenuation is conducted by applying the Kelley formula.
adj: Adjustment constant which is subtracted or added to extreme scores (score of zero or maximum score). The default is a value of 0.3
bias: A logical which indicates if JML bias should be reduced by multiplying item parameters by the adjustment factor of $(I-1)/I$
xsi.fixed: An optional matrix with two columns for fixing some of the basis parameters $\xi$ of item intercepts. 1st column: Index of $\xi$ parameter, 2nd column: Fixed value of $\xi$ parameter
xsi.inits: An optional vector of initial $\xi$ parameters. Note that all parameters must be specified and the vector is not of the same format as xsi.fixed.
theta.fixed: Matrix for fixed person parameters $\theta$. The first column includes the index whereas the second column includes the fixed value. This argument can only be applied for version=1.
A: A design array $A$ for item category intercepts. For item $i$ and category $k$, the threshold is specified as $ \sum _j a_{ikj} \xi_j$.
B: A design array for scoring item category responses. Entries in $B$ represent item loadings on abilities $\theta$.
Q: A Q-matrix which defines loadings of items on dimensions.
ndim: Number of dimensions in the model. The default is 1.
pweights: An optional vector of person weights.
constraint: Type of constraint for means. Either "cases" (set mean of person parameters to zero) or "items" (set mean of item parameters to zero).
verbose: Logical indicating whether output should be printed during iterations. This argument replaces control$progress.
control: A list of control arguments. See tam.mml for more details.
version: Version function which should be used. version=2 is the former tam.jml2 function in TAM (<2.0). The default version=3 allows efficient handling in case of missing data.
object: Object of class tam.jml (only for summary.tam function)
file: A file name in which the summary output will be written (only for summary.tam.jml function)
...: Further arguments to be passed

References

Linacre, J. M. (1994). Many-Facet Rasch Measurement. Chicago: MESA Press.

Examples

Run this code

#############################################################################
# EXAMPLE 1: Dichotomous data
#############################################################################
data(data.sim.rasch)
resp <- data.sim.rasch[1:700, seq( 1, 40, len=10)  ]  # subsample
# estimate the Rasch model with JML (function 'tam.jml')
mod1a <- TAM::tam.jml(resp=resp)
summary(mod1a)
itemfit <- TAM::tam.fit(mod1a)$fit.item

# compare results with Rasch model estimated by MML
mod1b <- TAM::tam.mml(resp=resp )

# constrain item difficulties to zero
mod1c <- TAM::tam.jml(resp=resp, constraint="items")

# plot estimated parameters
plot( mod1a$xsi, mod1b$xsi$xsi, pch=16,
    xlab=expression( paste( xi[i], " (JML)" )),
    ylab=expression( paste( xi[i], " (MML)" )),
    main="Item Parameter Estimate Comparison")
lines( c(-5,5), c(-5,5), col="gray" )

# Now, the adjustment pf .05 instead of the default .3 is used.
mod1d <- TAM::tam.jml(resp=resp, adj=.05)
# compare item parameters
round( rbind( mod1a$xsi, mod1d$xsi ), 3 )
  ##          [,1]   [,2]   [,3]   [,4]   [,5]  [,6]  [,7]  [,8]  [,9] [,10]
  ##   [1,] -2.076 -1.743 -1.217 -0.733 -0.338 0.147 0.593 1.158 1.570 2.091
  ##   [2,] -2.105 -1.766 -1.233 -0.746 -0.349 0.139 0.587 1.156 1.574 2.108

# person parameters for persons with a score 0, 5 and 10
pers1 <- data.frame( "score_adj0.3"=mod1a$PersonScore, "theta_adj0.3"=mod1a$theta,
           "score_adj0.05"=mod1d$PersonScore, "theta_adj0.05"=mod1d$theta  )
round( pers1[ c(698, 683, 608), ],3  )
  ##       score_adj0.3 theta_adj0.3 score_adj0.05 theta_adj0.05
  ##   698          0.3       -4.404          0.05        -6.283
  ##   683          5.0       -0.070          5.00        -0.081
  ##   608          9.7        4.315          9.95         6.179

if (FALSE) {
#*** item fit and person fit statistics
fmod1a <- TAM::tam.jml.fit(mod1a)
head(fmod1a$fit.item)
head(fmod1a$fit.person)

#*** Models in which some item parameters are fixed
xsi.fixed <- cbind( c(1,3,9,10), c(-2, -1.2, 1.6, 2 ) )
mod1e <- TAM::tam.jml( resp=resp, xsi.fixed=xsi.fixed )
summary(mod1e)

#*** Model in which also some person parameters theta are fixed
# fix theta parameters of persons 2, 3, 4 and 33 to values -2.9, ...
theta.fixed <- cbind( c(2,3,4,33), c( -2.9, 4, -2.9, -2.9 ) )
mod1g <- TAM::tam.jml( resp=resp, xsi.fixed=xsi.fixed, theta.fixed=theta.fixed )
# look at estimated results
ind.person <- c( 1:5, 30:33 )
cbind( mod1g$WLE, mod1g$errorWLE )[ind.person,]

#############################################################################
# EXAMPLE 2: Partial credit model
#############################################################################

data(data.gpcm, package="TAM")
dat <- data.gpcm

# JML estimation
mod2 <- TAM::tam.jml(resp=dat)
mod2$xsi     # extract item parameters
summary(mod2)
TAM::tam.fit(mod2)    # item and person infit/outfit statistic

#* estimate rating scale model
A <- TAM::designMatrices(resp=dat, modeltype="RSM")$A
#* estimate model with design matrix A
mod3 <- TAM::tam.jml(dat, A=A)
summary(mod3)

#############################################################################
# EXAMPLE 3: Facet model estimation using joint maximum likelihood
#            data.ex10; see also Example 10 in ?tam.mml
#############################################################################

data(data.ex10)
dat <- data.ex10
  ## > head(dat)
  ##  pid rater I0001 I0002 I0003 I0004 I0005
  ##    1     1     0     1     1     0     0
  ##    1     2     1     1     1     1     0
  ##    1     3     1     1     1     0     1
  ##    2     2     1     1     1     0     1
  ##    2     3     1     1     0     1     1

facets <- dat[, "rater", drop=FALSE ] # define facet (rater)
pid <- dat$pid      # define person identifier (a person occurs multiple times)
resp <- dat[, -c(1:2) ]        # item response data
formulaA <- ~ item * rater      # formula

# use MML function only to restructure data and input obtained design matrices
# and processed response data to tam.jml (-> therefore use only 2 iterations)
mod3a <- TAM::tam.mml.mfr( resp=resp, facets=facets, formulaA=formulaA,
             pid=dat$pid,  control=list(maxiter=2) )

# use modified response data mod3a$resp and design matrix mod3a$A
resp1 <- mod3a$resp
# JML
mod3b <- TAM::tam.jml( resp=resp1, A=mod3a$A, control=list(maxiter=200) )

#############################################################################
# EXAMPLE 4: Multi faceted model with some anchored item and person parameters
#############################################################################

data(data.exJ03)
resp <- data.exJ03$resp
X <- data.exJ03$X

#*** (0) preprocess data with TAM::tam.mml.mfr
mod0 <- TAM::tam.mml.mfr( resp=resp, facets=X, pid=X$rater,
                formulaA=~ leader + item + step,
                control=list(maxiter=2) )
summary(mod0)

#*** (1) estimation with tam.jml (no parameter fixings)

# extract processed data and design matrix from tam.mml.mfr
resp1 <- mod0$resp
A1 <- mod0$A
# estimate model with tam.jml
mod1 <- TAM::tam.jml( resp=resp1, A=A1, control=list( Msteps=4, maxiter=100 ) )
summary(mod1)

#*** (2) fix some parameters (persons and items)

# look at indices in mod1$xsi
mod1$xsi
# fix step parameters
xsi.index1 <- cbind( 21:25, c( -2.44, 0.01, -0.15, 0.01,  1.55 ) )
# fix some item parameters of items 1,2,3,6 and 13
xsi.index2 <- cbind( c(1,2,3,6,13), c(-2,-1,-1,-1.32, -1 ) )
xsi.index <- rbind( xsi.index1, xsi.index2 )
# fix some theta parameters of persons 1, 15 and 20
theta.fixed <- cbind(  c(1,15,20), c(0.4, 1, 0 ) )
# estimate model, theta.fixed only works for version=1
mod2 <- TAM::tam.jml( resp=resp1, A=A1, xsi.fixed=xsi.fixed, theta.fixed=theta.fixed,
            control=list( Msteps=4, maxiter=100) )
summary(mod2)
cbind( mod2$WLE, mod2$errorWLE )
}