mapDPC: Finds an MAP estimate for a discrete partial credit CPT

In ralmond/CPTtools: Tools for Creating Conditional Probability Tables

Finds an MAP estimate for a discrete partial credit CPT

Description

This finds a set of parameters for a given discrete partial credit model which produces the best fit to the first argument. It is assumed that the first argument is a table produced by adding observed counts to a prior conditional probability table. Thus the result is a maximum a posterior (MAP) estimate of the CPT. The parametric structure of the table is given by the rules and link parameters.

Usage

mapDPC(postTable, skillLevels, obsLevels, lnAlphas, betas,
       rules = "Compensatory", link = "partialCredit",
       linkScale=NULL, Q=TRUE, tvals=lapply(skillLevels,
               function (sl) effectiveThetas(length(sl))),
       gamma=0.001,
       ...) 

Arguments

postTable	A table of cell counts which should have the same structure as the output of calcDPCTable(skillLevels, obsLevels, lnAlphas, betas, rules, link, linkScale). As zero counts would cause problems, the prior conditional probability table is normally added to the counts to make the argument a posterior counts.
skillLevels	A list of character vectors giving names of levels for each of the condition variables.
obsLevels	A character vector giving names of levels for the output variables from highest to lowest. As a special case, can also be a vector of integers.
lnAlphas	A list of vectors of initial values for the log slope parameters. Its length should be 1 or length(obsLevels)-1. The required length of the individual component vectors depends on the choice of rule (and is usually either 1 or the length of skillLevels).
betas	A list of vectors of initial values for the difficulty (-intercept) parameters. Its length should be 1 or length(obsLevels)-1. The required length of the individual component vectors depends on the choice of rule (and is usually either 1 or the length of skillLevels).
rules	A list of functions for computing effective theta (see Details). Its length should be length(obsLevels)-1 or 1 (implying that the same rule is applied for every gap.)
link	The function that converts a table of effective thetas to probabilities
linkScale	Initial values for the optional scale parameter for the link function. This is only used with certain choices of link function.
Q	This should be a Q matrix indicating which parent variables are relevant for which state transitions. It should be a number of states minus one by number of parents logical matrix. As a special case, if all variable are used for all levels, then it can be a scalar value.
tvals	A list of the same length as skillLevels. Each element should be a numeric vector values on the theta (logistic) scale corresponding to the levels for that parent variable. The default spaces them equally according to the normal distribution (see effectiveThetas).
gamma	This is a weight given to a penalty to keep the parameters close to zero.
...	Additional arguments passed to the optim function.

Details

The purpose of this function is to try to estimate the values of a discrete partial credit model. The structure of the model is given by the rules and link arguments: the form of the table produces is like the output of calcDPCTable(skillLevels, obsLevels, lnAlphas, betas, rules, link, linkScale). It tries to find the values of lnAlphas and betas (and if used linkScale) parameters which are most likely to have generated the data in the postTable argument. The lnAlphas, betas and linkScale arguments provide the initial values for those parameters.

Let p_{i,j} be the value in the ith row and the jth column of the conditional probability table output from calcDPCTable(skillLevels, obsLevels, lnAlphas, betas, rules, link, linkScale), and let x_{i,j} be the corresponding elements of postTable. The mapDPC function uses optim to find the value of the parameters that minimizes the deviance,

-2*\sum_i \sum_j x_{i,j} \log(p_{i,j}).

Value

A list with components:

lnAlphas

A vector of the same structure as lnAlphas containing the estimated values.

betas

A veto of the same structure as betas containing the estimated values.

linkScale

If the linkScale was supplied, the estimated value.

convergence

An integer code. 0 indicates successful completion, positive values are various error codes (see optim).

value

The deviance of the fit DPC model.

The list is the output of the optim) function, which has other components in the output. See the documentation of that function for details.

Author(s)

Russell Almond

References

Almond, R.G., Mislevy, R.J., Steinberg, L.S., Yan, D. and Williamson, D.M. (2015). Bayesian Networks in Educational Assessment. Springer. Chapter 8.

Muraki, E. (1992). A Generalized Partial Credit Model: Application of an EM Algorithm. Applied Psychological Measurement, 16, 159-176. DOI: 10.1177/014662169201600206

Samejima, F. (1969) Estimation of latent ability using a response pattern of graded scores. Psychometrika Monograph No. 17, 34, (No. 4, Part 2).

I also have planned a manuscript that describes these functions in more detail.

See Also

optim, calcDPCTable, Compensatory, OffsetConjunctive, gradedResponse, partialCredit

Examples

  pLevels <- list(Skill1=c("High","Med","Low"))
  obsLevels <- c("Full","Partial","None")

  trueLnAlphas <- list(log(1),log(.25))
  trueBetas <- list(2, -.5)

  priorLnAlphas <- list(log(.5),log(.5))
  priorBetas <- list(1, -1)

  truedist <- calcDPCTable(pLevels,obsLevels,trueLnAlphas,trueBetas,
                           rules="Compensatory",link="partialCredit")
  prior <- calcDPCTable(pLevels,obsLevels,priorLnAlphas,priorBetas,
                           rules="Compensatory",link="partialCredit")

  post1 <- prior + round(truedist*1000)

  map1 <- mapDPC(post1,pLevels,obsLevels,priorLnAlphas,priorBetas,
                           rules="Compensatory",link="partialCredit")

  if (map1$convergence != 0) {
    warning("Optimization did not converge:", map1$message)
  }

  postLnAlphas <- map1$lnAlphas
  postBetas <- map1$betas
  fitdist <- calcDPCTable(pLevels,obsLevels,map1$lnAlphas,map1$betas,
                           rules="Compensatory",link="partialCredit")
  ## Tolerance for recovery test.
  tol <- .01
  maxdistdif <- max(abs(fitdist-truedist))
  if (maxdistdif > tol) {
    stop("Posterior and True CPT differ, maximum difference ",maxdistdif)
  }
  if (any(abs(unlist(postLnAlphas)-unlist(trueLnAlphas))>tol)) {
    stop("Log(alphas) differ by more than tolerance")
  }
  if (any(abs(unlist(postBetas)-unlist(trueBetas))>tol)) {
   stop("Betas differ by more than tolerance")
  }

ralmond/CPTtools documentation built on Dec. 27, 2024, 7:15 a.m.