test_shadowcat: Simulate a testing routine with shadowcat

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

Description

Simulate several iterations of getting the key of the new item to administer and the updated theta estimate, and getting an answer to the new item.

Usage

test_shadowcat(true_theta, prior_form, prior_parameters, model, alpha, beta,
  start_items, stop_test, estimator, information_summary, guessing = NULL,
  eta = NULL, constraints_and_characts = NULL, lower_bound = NULL,
  upper_bound = NULL, safe_eap = FALSE, initital_estimate = rep(0,
  ncol(alpha)), initial_variance = diag(ncol(alpha)) * 25,
  eap_estimation_procedure = "riemannsum")

Arguments

true_theta	True theta value or vector.
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.
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.
start_items	List indicating the items that should be shown to the respondent before the theta estimate will be updated for the first time. One of list(type = "random", n = ...), list(type = "fixed", item_keys = ..., n = ...), or list(type = "random_by_dimension", n_by_dimension = ..., n = ...), where n is the total number of burn in items, item_keys is a character vector with keys of the burn in items, and n_by_dimension is the number of burn in items per dimension, or a vector with the number of burn in items for each dimension. If n is 0, only n needs to be defined. Note that the type "random_by_dimension" assumes that items load on a single dimension; if any item has a non-zero loading on a dimension, it is considered to be part of that dimension.
stop_test	List indicating rules for when to terminate the test. Should be a list of the form list(target = ..., max_n = ..., min_n = ..., cutoffs = ...), where target is a vector indicating the maximum acceptable variance per dimension; NULL means no variance target, max_n is the test length at which the test should be terminated (even if the target has not been reached yet), min_n is the minimum test length; NULL means no mimimum test length, and cutoffs is a matrix containing cut off values per dimension (columns) and test iteration (rows). First row contains cut off values for when no items have been administered yet, second row for when one item has been administered, etc. If estimate + 3SE < cutoff for each dimension at a certain iteration, test terminates; NULL means no cut off values.
estimator	Type of estimator to be used, one of "maximum_likelihood", "maximum_aposteriori", or "expected_aposteriori"; see details.
information_summary	How to summarize Fisher information, used for item selection. One of "determinant", "posterior_determinant", "trace", "posterior_trace", or "posterior_expected_kullback_leibler". Fisher Information of the test so far (including all administered items) is added to the Fsher Information of the available item before the summary is computed.
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.
eta	Matrix of location parameters, optionally used in GPCM model, ignored for all others. Row names should contain the item keys. If eta is defined, the beta matrix will be derived from this eta matrix by computing the cumulative sums of the rows of eta; see Glas and Dagohoy (2006).
constraints_and_characts	List with constraints and characteristics for Shadow Testing; NULL means no constraints. See details.
lower_bound	Vector with lower bounds for theta per dimension. Estimated theta values smaller than the lower bound values are truncated to the lower bound values. Can only be defined when estimator is maximum likelihood. Setting bounds with maximum likelihood estimation is equivalent to using maximum aposteriori estimation with a uniform prior.
upper_bound	Vector with upper bounds for theta per dimension. Estimated theta values larger than the upper bound values are truncated to the upper bound values. Can only be defined when estimator is maximum likelihood. Setting bounds with maximum likelihood estimation is equivalent to using maximum aposteriori estimation with a uniform prior.
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.
initital_estimate	Vector containing the initial theta estimate, before any items have been administered.
initial_variance	Matrix containing the initial covariance matrix, before any items have been administered.
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

List as returned by shadowcat after test is terminated, with variance element turned into matrix.

Examples

# One dimension
alpha_beta_one_dim <- simulate_testbank(model = "GPCM", number_items = 50, 
                                        number_dimensions = 1, number_itemsteps = 3)
test_shadowcat(true_theta = 2, prior_form = "normal", 
               prior_parameters = list(mu = 0, Sigma = diag(1)), model = "SM", 
               alpha = alpha_beta_one_dim$alpha, beta = alpha_beta_one_dim$beta, 
               start_items = list(type = 'random', n = 3), 
               stop_test = list(max_n = 20, target = 0.1), estimator = "maximum_aposteriori", 
               information_summary = "posterior_determinant")

# Three dimensions
alpha_beta_three_dim <- simulate_testbank(model = "GPCM", number_items = 100, 
                                          number_dimensions = 3, number_itemsteps = 3)
test_shadowcat(true_theta = c(0, 1, -.5), prior_form = "normal", 
               prior_parameters = list(mu = c(0, 0, 0), Sigma = diag(3)), 
               model = "SM", alpha = alpha_beta_three_dim$alpha, 
               beta = alpha_beta_three_dim$beta, start_items = list(type = 'random', n = 3), 
               stop_test = list(max_n = 60, target = c(.1, .1, .1)), 
               estimator = "maximum_aposteriori", information_summary = "posterior_determinant")

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