estimate_latent_trait: Latent trait estimation

In Karel-Kroeze/ShadowCAT: Multidimensional Computer Adaptive Testing with the Shadow Testing Procedure

Description

Obtains a latent trait estimate and variance of the estimate.

Usage

estimate_latent_trait(estimate, answers, prior_form, prior_parameters, model,
  administered, number_dimensions, estimator, alpha, beta, guessing,
  number_itemsteps_per_item, safe_eap = FALSE,
  eap_estimation_procedure = "riemannsum")

Arguments

estimate	Vector containing current theta estimate, with covariance matrix as an attribute.
answers	Vector with answers to administered items.
prior_form	String indicating the form of the prior; one of "normal" or "uniform". Not required if estimator is maximum likelihood.
prior_parameters	List containing mu and Sigma of the normal prior: list(mu = ..., Sigma = ...), or the upper and lower bound of the uniform prior: list(lower_bound = ..., upper_bound = ...). Not required if estimator is maximum likelihood. The list element Sigma should always be in matrix form. List elements mu, lower_bound, and upper_bound should always be vectors. The length of mu, lower_bound, and upper_bound should be equal to the number of dimensions. For uniform prior in combination with expected aposteriori estimation, true theta should fall within lower_bound and upper_bound and be not too close to one of these bounds, in order to prevent errors. Setting the shadowcat argument safe_eap to TRUE ensures that the estimation switches to maximum aposteriori if the expected aposteriori estimate fails.
model	One of "3PLM", "GPCM", "SM" or "GRM", for the three-parameter logistic, generalized partial credit, sequential or graded response model, respectively.
administered	Vector with indices of administered items.
number_dimensions	Number of dimensions.
estimator	Type of estimator to be used, one of "maximum_likelihood", "maximum_aposteriori", or "expected_aposteriori"; see details.
alpha	Matrix of alpha parameters, one column per dimension, one row per item. Row names should contain the item keys. Note that so called within-dimensional models still use an alpha matrix, they simply have only one non-zero loading per item.
beta	Matrix of beta parameters, one column per item step, one row per item. Row names should contain the item keys. Note that shadowcat expects answer categories to be sequential, and without gaps. That is, the weight parameter in the GPCM model is assumed to be sequential, and equal to the position of the 'location' of the beta parameter in the beta matrix. The matrix should have a number of columns equal to the largest number of item steps over items, items with fewer answer categories should be right-padded with NA. NA values between answer categories are not allowed, and will lead to errors.
guessing	Matrix with one column of guessing parameters per item. Row names should contain the item keys. Optionally used in 3PLM model, ignored for all others.
number_itemsteps_per_item	Vector containing the number of non missing cells per row of the beta matrix.
safe_eap	Only relevant if estimator is expected aposteriori. Set to TRUE if estimator should switch to maximum aposteriori if the integration algorithm results in an error. An error may occur if the prior is uniform, estimator is expected aposteriori, and the bounds of the prior do not exceed the true theta value, or are too close to it.
eap_estimation_procedure	String indicating the estimation procedure if estimator is expected aposteriori and prior form is normal. One of "riemannsum" for integration via Riemannsum or "gauss_hermite_quad" for integration via Gaussian Hermite Quadrature. If prior form is uniform, estimation procedure should always be "riemannsum".

Value

Vector containing the updated estimate with the covariance matrix as attribute.

Examples

number_dimensions <- 1
estimate <- rep(.3, number_dimensions)
model <- "3PLM"
number_items <- 50
answers <- rep(c(1, 0), 17)
administered <- c(6:20, 31:49)
alpha <- matrix(runif(number_items * number_dimensions, .3, 1.5),
                nrow = number_items, ncol = number_dimensions)
beta <- matrix(rnorm(number_items), nrow = number_items, ncol = 1)
guessing <- c(rep(.1, number_items / 2), rep(.2, number_items / 2))
number_itemsteps_per_item <- ShadowCAT:::number_non_missing_cells_per_row(beta)
prior_form <- "normal"
prior_parameters <- list(mu = 0, Sigma = diag(1))

# Obtain estimates
# Note that maximum a posteriori combined with uniform prior 
# is equivalent to maximum likelihood with bounds
estimator <- "maximum_aposteriori"
ML <- ShadowCAT:::estimate_latent_trait(estimate, answers, 
                                        prior_form = "uniform", 
                                        prior_parameters = list(lower_bound = -4, upper_bound = 4), 
                                        model, administered, number_dimensions, estimator, 
                                        alpha, beta, guessing, number_itemsteps_per_item)
estimator <- "maximum_aposteriori"
MAP <- ShadowCAT:::estimate_latent_trait(estimate, answers, 
                                         prior_form, prior_parameters, 
                                         model, administered, number_dimensions, estimator,
                                         alpha, beta, guessing, number_itemsteps_per_item)
estimator <- "expected_aposteriori"
EAP <- ShadowCAT:::estimate_latent_trait(estimate, answers, 
                                         prior_form, prior_parameters, 
                                         model, administered, number_dimensions, estimator, 
                                         alpha, beta, guessing, number_itemsteps_per_item)
ML; MAP; EAP

# access variance
attr(ML, "variance")

# Note that expected_aposteriori takes considerably more time when dimensionality is higher:
number_dimensions <- 5
estimate <- rep(.3, number_dimensions)
alpha <- matrix(runif(number_items * number_dimensions, .3, 1.5), 
                nrow = number_items, ncol = number_dimensions)
prior_form <- "normal"
prior_parameters <- list(mu = rep(0, number_dimensions), Sigma = diag(number_dimensions))

estimator <- "maximum_aposteriori"
system.time(ShadowCAT:::estimate_latent_trait(estimate, answers, 
                                              prior_form, prior_parameters, 
                                              model, administered, number_dimensions, estimator, 
                                              alpha, beta, guessing, number_itemsteps_per_item))
estimator <- "expected_aposteriori"
system.time(ShadowCAT:::estimate_latent_trait(estimate, answers, 
                                              prior_form, prior_parameters,
                                              model, administered, number_dimensions, estimator, 
                                              alpha, beta, guessing, number_itemsteps_per_item))

Karel-Kroeze/ShadowCAT documentation built on May 7, 2019, 12:28 p.m.