mst function

Computerized Multistage Testing (MST)

mst creates a multistage (MST) object for assembly

mst_route adds/removes a route to/from the MST

mst_get_indices maps the input indices to the actual indices

mst_obj adds objective functions to the MST

mst_constraint adds constraints to the MST

mst_stage_length sets length limits on stages

mst_rdp anchors the routing decision point (rdp) between adjacent modules

mst_module_mininfo sets the minimum information for modules

mst_assemble assembles the mst

mst_get_items extracts items from the assembly results

mst(pool, design, num_panel, method = c("topdown", "bottomup"),
  len = NULL, max_use = NULL, group = NULL, ...)

mst_route(x, route, op = c("+", "-"))

mst_get_indices(x, indices)

mst_obj(x, theta, indices = NULL, target = NULL, ...)

mst_constraint(x, coef, min = NA, max = NA, level = NULL,
  indices = NULL)

mst_stage_length(x, stages, min = NA, max = NA)

mst_rdp(x, theta, indices, tol = 0)

mst_module_info(x, thetas, min, max, indices)

mst_assemble(x, ...)

## S3 method for class 'mst'
print(x, ...)

## S3 method for class 'mst'
plot(x, ...)

mst_get_items(x, panel_ix = NULL, stage_ix = NULL, module_ix = NULL,
  route_ix = NULL)

Arguments

• pool: the item pool (data.frame)
• design: the MST design (string): e.g., "1-3", "1-2-2", "1-2-3"
• num_panel: the number of panels (integer)
• method: the design method (string): 'topdown' or 'bottomup'
• len: the module/route length (integer)
• max_use: the maximum selection of items (integer)
• group: the grouping variable (string or vector)
• ...: further arguments
• x: the MST object
• route: a MST route represented by a vector of module indices
• op: "+" to add a route and "-" to remove a route
• indices: the indices of the route (topdown) or the module (bottomup) where objectives are added
• theta: a theta point or interval over which the TIF is optimized
• target: the target values of the TIF objectives. NULL for maximization
• coef: the coefficients of the constraint
• min: the lower bound of the constraint
• max: the upper bound of the constraint
• level: the constrained level, NA for quantitative variable
• stages: the stage indices
• tol: tolerance parameter (numeric)
• thetas: theta points, a vector
• panel_ix: the panel index, an int vector
• stage_ix: the stage index, an int vector
• module_ix: the module index, an int vector
• route_ix: the route index, an integer

Details

There are two methods for designing a MST. The bottom-up approach adds objectives and constraints on individual modules, whereas the topdown approach adds objectives and constraints directly on routes.

plot.mst draws module information functions when byroute=FALSE

and route information functions when byroute=TRUE

Examples

## Not run:

## generate item pool
num_item <- 300
pool <- with(model_3pl_gendata(1, num_item), data.frame(a=a, b=b, c=c))
pool$id <- 1:num_item
pool$content <- sample(1:3, num_item, replace=TRUE)
pool$time <- round(rlnorm(num_item, 4, .3))
pool$group <- sort(sample(1:round(num_item/3), num_item, replace=TRUE))

## ex. 1: 1-2-2 MST, 2 panels, topdown
## 20 items in total and 10 items in content area 1 in each route
## maximize info. at -1 and 1 for easy and hard routes
x <- mst(pool, "1-2-2", 2, 'topdown', len=20, max_use=1)
x <- mst_obj(x, theta=-1, indices=1:2)
x <- mst_obj(x, theta=1, indices=3:4)
x <- mst_constraint(x, "content", 10, 10, level=1)
x <- mst_assemble(x, timeout=5)
plot(x, byroute=TRUE)
for(p in 1:x$num_panel)
  for(r in 1:x$num_route) {
     route <- paste(x$route[r, 1:x$num_stage], collapse='-')
     count <- sum(mst_get_items(x, panel_ix=p, route_ix=r)$content==1)
     cat('panel=', p, ', route=', route, ': ', count, ' items in content area #1\n', sep='')
  }

## ex. 2: 1-2-3 MST, 2 panels, bottomup,
## remove two routes with large theta change: 1-2-6, 1-3-4 
## 10 items in total and 4 items in content area 2 in each module
## maximize info. at -1, 0 and 1 for easy, medium, and hard modules
x <- mst(pool, "1-2-3", 2, 'bottomup', len=10, max_use=1)
x <- mst_route(x, c(1, 2, 6), "-")
x <- mst_route(x, c(1, 3, 4), "-")
x <- mst_obj(x, theta= 0, indices=c(1, 5))
x <- mst_obj(x, theta=-1, indices=c(2, 4))
x <- mst_obj(x, theta= 1, indices=c(3, 6))
x <- mst_constraint(x, "content", 4, 4, level=2)
x <- mst_assemble(x, timeout=10) 
plot(x, byroute=FALSE)
for(p in 1:x$num_panel)
  for(m in 1:x$num_module){
    count <- sum(mst_get_items(x, panel_ix=p, module_ix=m)$content==2)
    cat('panel=', p, ', module=', m, ': ', count, ' items in content area #2\n', sep='')
  }
 
## ex.3: same with ex.2 (w/o content constraints), but group-based  
x <- mst(pool, "1-2-3", 2, 'bottomup', len=12, max_use=1, group="group")
x <- mst_route(x, c(1, 2, 6), "-")
x <- mst_route(x, c(1, 3, 4), "-")
x <- mst_obj(x, theta= 0, indices=c(1, 5))
x <- mst_obj(x, theta=-1, indices=c(2, 4))
x <- mst_obj(x, theta= 1, indices=c(3, 6))
x <- mst_assemble(x, timeout=10)
plot(x, byroute=FALSE)
for(p in 1:x$num_panel)
  for(m in 1:x$num_module){
    items <- mst_get_items(x, panel_ix=p, module_ix=m)
    cat('panel=', p, ', module=', m, ': ', length(unique(items$id)), ' items from ', 
        length(unique(items$group)), ' groups\n', sep='')
  }
  
## ex.4: 2 panels of 1-2-3 top-down design
## 20 total items and 10 items in content area 3
## 6+ items in stage 1 & 2
x <- mst(pool, "1-2-3", 2, "topdown", len=20, max_use=1)
x <- mst_route(x, c(1, 2, 6), "-")
x <- mst_route(x, c(1, 3, 4), "-")
x <- mst_obj(x, theta=-1, indices=1)
x <- mst_obj(x, theta=0, indices=2:3)
x <- mst_obj(x, theta=1, indices=4)
x <- mst_constraint(x, "content", 10, 10, level=3)
x <- mst_stage_length(x, 1:2, min=6)
x <- mst_assemble(x, timeout=15)
head(x$items)
plot(x, byroute=FALSE)
for(p in 1:x$num_panel)
  for(s in 1:x$num_stage){
    items <- mst_get_items(x, panel_ix=p, stage_ix=s)
    cat('panel=', p, ', stage=', s, ': ', length(unique(items$id)), ' items\n', sep='')
  }

## ex.5: same with ex.4, but use RDP instead of stage length to control routing errors
x <- mst(pool, "1-2-3", 2, "topdown", len=20, max_use=1)
x <- mst_route(x, c(1, 2, 6), "-")
x <- mst_route(x, c(1, 3, 4), "-")
x <- mst_obj(x, theta=-1, indices=1)
x <- mst_obj(x, theta=0, indices=2:3)
x <- mst_obj(x, theta=1, indices=4)
x <- mst_constraint(x, "content", 10, 10, level=3)
x <- mst_rdp(x, 0, 2:3, .1)
x <- mst_module_mininfo(x, 0, 5, 2:3)
x <- mst_assemble(x, timeout=15)
plot(x, byroute=FALSE)
## End(Not run)