caMST (version 0.1.4)

multistage_test: Computer Adaptive Multistage Test

Description

Computer Adaptive Multistage Test

Usage

multistage_test(
  mst_item_bank,
  modules,
  transition_matrix,
  method = "BM",
  response_matrix,
  initial_theta = 0,
  model = NULL,
  n_stages = 3,
  test_length = 18,
  nc_list = NULL
)

Arguments

mst_item_bank

A data frame with the items on the rows and their item parameters on the columns. These should be in the mstR package format for item banks.

modules

A matrix describing the relationship between the items and the modules they belong to. See Details.

transition_matrix

A matrix describing how individuals can transition from one stage to the next.

method

A character value indicating method for the provisional theta estimate. Defaults to "BM" (Bayes Modal). See the mstR package for more details.

response_matrix

A matrix of the person responses, with individuals as rows and items as columns.

initial_theta

The initial theta estimate for all individuals. Default is 0.

model

Either NULL (default) for dichotomous models or a character value indicating the polytomous model used. See themstR package for more details.

n_stages

A numeric value indicating the number of stages in the test.

test_length

A numeric value indicating the total number of items each individual answers.

nc_list

This parameter controls whether or not to use number correct ("NC") scoring to select modules. Defaults to `NULL`, using module information. Otherwise, this should be a list where the elements of the list correspond to each module which routes to other modules by number correct. If no `method` argument is provided in this list, or if an invalid entry is given, the method will default to `'cumulative_sum'`, meaning the values provided are a running tally of the number of items correctly answered on the test. If `method` is set to `module_sum`, then the sum of the number correct within the current module will be used to select the next module. See 'details' for more information.

Value

A list of all individuals with the following elements: the vector of final theta estimates based on "method", the vector of final theta estimates based on EAP, the vector of final theta estimates based on the iterative estimate from Baker 2004, a matrix of the final items taken, a matrix of the modules seen, and a matrix of the final responses.

An S4 object of class 'MST' with the following slots:

function.call

The function and arguments called to create this object.

final.theta.estimate

A numeric vector of the final theta estimates using the method provided in function.call.

eap.theta

A numeric vector of the final theta estimates using the expected a posteriori (EAP) theta estimate from catR::eapEst.

final.theta.Baker

A numeric vector of the final theta estimates using an iterative maximum likelihood estimation procedure as described in chapter 5 of Baker (2001).

final.theta.SEM

A numeric vector of the final standard error of measurement (SEM) estimates using an iterative maximum likelihood estimation procedure as described in chapter 5 of Baker (2001).

final.items.seen

A matrix of the final items seen by each individual using the supplied item names. `NA` values indicate that an individual wasn't given any items to answer after the last specified item in their row.

final.responses

A matrix of the responses to the items seen in final.items.seen. NA values indicate that the individual didn't answer the question in the supplied response file or wasn't given any more items to answer.

transition.matrix

The transition_matrix originally supplied to the function.

n.stages

The n_stages originally supplied to the function.

nc.list

The nc_list originally supplied to the function.

runtime

A difftime object recording how long the function took to complete.

Details

When using (cumulative) number correct module selection, the input list should contain one element for each module that needs to route to other modules. For example, in a 1-3-3 design the first module can route to any module in the second stage, so the first element of `nc_list` would be a numeric vector with three values indicating the *maximum* number of correct items needed in order to be routed to the second, third, or fourth module respectively. When the design is not crossed (e.g., a person routed to the easy module in the second stage **cannot** be routed to the hard module in the third stage), `-Inf` and `Inf` need to be used within `nc_list` to indicate this. Continuing the example, let's assume the 1-3-3 design is not crossed and will be balanced so that each stage has the same number of items (10 each) for a total of 30 items administered. The `nc_list` object could be specified like so: nc_list = list(module1 = c(4, 5, 7), module2 = c(8, 14, Inf), module3 = c(8, 14, 20), module4 = c(-Inf, 14, 20), method = "cumulative_sum").

As it is the most common method of number correct scoring, "cumulative_sum" is the default. Any value included in the `method` argument of `nc_list` that does _not_ equal "module_sum" will cause the default "cumulative_sum" to be used. _This is intentional and will not be changed unless I am given a good argument to change it_.

References

Baker (2001). http://echo.edres.org:8080/irt/baker/final.pdf

See Also

[mixed_adaptive_test] for a multistage test with a routing module using item-level adaptation.

Examples

# NOT RUN {
# using simulated test data
data(example_thetas) # 5 simulated abilities
data(example_responses) # 5 simulated response vectors
# the transition matrix for an 18 item 1-3-3 design
data(example_transition_matrix)
# the MST item bank
data(mst_only_items)
# the MST module matrix
data(example_module_items)
# run the MST model
results <- multistage_test(mst_item_bank = mst_only_items,
modules = example_module_items, transition_matrix = example_transition_matrix,
method = "BM", response_matrix = example_responses, initial_theta = 0,
model = NULL, n_stages = 3, test_length = 18)
# }
# NOT RUN {
# using number correct scoring for the same data
# create nc_list as explained in 'details'
nc_list = list(module1 = c(4, 5, 7),
module2 = c(8, 14, Inf),
module3 = c(8, 14, 18),
module4 = c(-Inf, 14, 18),
method = 3) # the method here will default to "cumulative_sum" as described in 'details'
# this is the ONLY difference currently! Everything else remains the same
# run the example
nc.results <- multistage_test(mst_item_bank = mst_only_items,
modules = example_module_items, transition_matrix = example_transition_matrix,
method = "BM", response_matrix = example_responses, initial_theta = 0,
model = NULL, n_stages = 3, test_length = 18, nc_list = nc_list)
# }