ata: Automated Test Assembly (ATA)
In xxIRT: Item Response Theory and Computer-Based Testing in R

Description Usage Arguments Details Examples

ata initiates an ATA model

ata_obj_relative adds a relative objective to the model

ata_obj_absolute adds an absolute objective to the model

ata_constraint adds a constraint to the model

ata_item_use limits the minimum and maximum usage for items

ata_item_enemy adds an enemy-item constraint to the model

ata_item_fixedvalue forces an item to be selected or not selected

ata_solve solves the MIP model

ata(pool, num_form = 1, len = NULL, max_use = NULL, ...)

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

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

ata_obj_relative(x, coef, mode = c("max", "min"), tol = NULL,
  negative = FALSE, forms = NULL, collapse = FALSE,
  internal_index = FALSE, ...)

ata_obj_absolute(x, coef, target, equal_tol = FALSE, tol_up = NULL,
  tol_down = NULL, forms = NULL, collapse = FALSE,
  internal_index = FALSE, ...)

ata_constraint(x, coef, min = NA, max = NA, level = NULL,
  forms = NULL, collapse = FALSE, internal_index = FALSE)

ata_item_use(x, min = NA, max = NA, items = NULL)

ata_item_enemy(x, items)

ata_item_fixedvalue(x, items, min = NA, max = NA, forms)

ata_solve(x, solver = c("lpsolve", "glpk"), as.list = TRUE,
  details = TRUE, time_limit = 10, message = FALSE, ...)

`pool`	item pool, a data.frame
`num_form`	number of forms to be assembled
`len`	test length of each form
`max_use`	maximum use of each item
`...`	options, e.g. group, common_items, overlap_items
`x`	an ATA object
`coef`	coefficients of the objective function
`mode`	optimization mode: 'max' for maximization and 'min' for minimization
`tol`	the tolerance paraemter
`negative`	`TRUE` when the objective function is expected to be negative
`forms`	forms where objectives are added. `NULL` for all forms
`collapse`	`TRUE` to collapse into one objective function
`internal_index`	`TRUE` to use internal form indices
`target`	the target values of the objective function
`equal_tol`	`TRUE` to force upward and downward tolerance to be equal
`tol_up`	the range of upward tolerance
`tol_down`	the range of downward tolerance
`min`	the lower bound of the constraint
`max`	the upper bound of the constraint
`level`	the level of a categorical variable to be constrained
`items`	a vector of item indices, `NULL` for all items
`solver`	use 'lpsolve' for lp_solve 5.5 or 'glpk' for GLPK
`as.list`	`TRUE` to return results in a list; otherwise, a data frame
`details`	`TRUE` to print detailed information
`time_limit`	the time limit in seconds passed along to solvers
`message`	`TRUE` to print messages from solvers

The ATA model stores the definition of a MIP model. ata_solve converts the model definition to a real MIP object and attempts to solve it.

ata_obj_relative: when mode='max', maximize (y-tol), subject to y <= sum(x) <= y+tol; when mode='min', minimize (y+tol), subject to y-tol <= sum(x) <= y. When negative is TRUE, y < 0, tol > 0. coef can be a numeric vector that has the same length with the pool or forms, or a variable name in the pool, or a numeric vector of theta points. When tol is NULL, it is optimized; when FALSE, ignored; when a number, fixed; when a range, constrained with lower and upper bounds.

ata_obj_absolute minimizes y0+y1 subject to t-y0 <= sum(x) <= t+y1.

When level is NA, it is assumed that the constraint is on a quantitative item property; otherwise, a categorical item property. coef can be a variable name, a constant, or a numeric vector that has the same size as the pool.

ata_solve takes control options in .... For lpsolve, see lpSolveAPI::lp.control.options. For glpk, see glpkAPI::glpkConstants
Once the model is solved, additional data are added to the model. status shows the status of the solution, optimum the optimal value of the objective fucntion found in the solution, obj_vars the values of two critical variables in the objective function, result the assembly results in a binary matrix, and items the assembled items

## Not run: 
## generate a pool of 100 items
n_items <- 100
pool <- with(model_3pl_gendata(1, nitems), data.frame(id=1:n_items, a=a, b=b, c=c))
pool$content <- sample(1:3, n_items, replace=TRUE)
pool$time <- round(rlnorm(n_items, log(60), .2))
pool$group <- sort(sample(1:round(n_items/3), n_items, replace=TRUE))

## ex. 1: four 10-item forms, maximize b parameter
x <- ata(pool, 4, len=10, max_use=1)
x <- ata_obj_relative(x, "b", "max")
x <- ata_solve(x, timeout=5)
data.frame(form=1:4, b=sapply(x$items, function(x) mean(x$b)))

## ex. 2: four 10-item forms, minimize b parameter
x <- ata(pool, 4, len=10, max_use=1)
x <- ata_obj_relative(x, "b", "min", negative=TRUE)
x <- ata_solve(x, as.list=FALSE, timeout=5)
with(x$items, aggregate(b, by=list(form=form), mean))

## ex. 3: two 10-item forms, mean(b)=0, sd(b)=1
## content = (3, 3, 4), avg. time = 58--62 seconds
constr <- data.frame(name='content',level=1:3, min=c(3,3,4), max=c(3,3,4), stringsAsFactors=F)
constr <- rbind(constr, c('time', NA, 58*10, 62*10))
x <- ata(pool, 2, len=10, max_use=1)
x <- ata_obj_absolute(x, pool$b, 0*10)
x <- ata_obj_absolute(x, (pool$b-0)^2, 1*10)
for(i in 1:nrow(constr))
  x <- with(constr, ata_constraint(x, name[i], min[i], max[i], level=level[i]))
x <- ata_solve(x, timeout=5)
sapply(x$items, function(x) c(mean=mean(x$b), sd=sd(x$b)))

## ex. 4: two 10-item forms, max TIF over (-1, 1), consider item sets
x <- ata(pool, 2, len=10, max_use=1, group="group")
x <- ata_obj_relative(x, seq(-1, 1, .5), 'max')
x <- ata_solve(x, timeout=5)
plot(x)

## End(Not run)