Constrain the sum of item values across multiple forms.

Description

Create constraints related to item values. That is, the created constraints assure that the sum of the item values (itemValues) across test forms is either (a) smaller than or equal to (operator = "<="), (b) equal to (operator = "="), or (c) greater than or equal to (operator = ">=") the chosen targetValue. Note that the length of itemValues should equal to the number of the length of whichForms times whichItems.

Usage

acrossFormsConstraint(
  nForms,
  nItems = NULL,
  operator = c("<=", "=", ">="),
  targetValue,
  whichForms = seq_len(nForms),
  whichItems = NULL,
  itemIDs = NULL,
  itemValues = NULL,
  info_text = NULL
)

Arguments

Value

An object of class "constraint".

Examples

## constraints to make sure that accross test form 1 and 3, only 4 items
##  of items 1:10 appear. Note that the constraint should be used in
##  in combination with constraining item overlap between the forms.
constr1 <- combineConstraints(
  acrossFormsConstraint(nForms = 3,
                        operator = "=", targetValue = 4,
                        whichForms = c(1, 3),
                        itemValues = c(rep(1, 10), rep(0, 10)),
                        itemIDs = 1:20),
  itemUsageConstraint(nForms = 3, nItems = 20, operator = "=", targetValue = 1,
                      itemIDs = 1:20)
                    )

## or alternatively
constr2 <- combineConstraints(
  acrossFormsConstraint(nForms = 3, nItems = 20,
                        operator = "=", targetValue = 4,
                        whichForms = c(1, 3),
                        whichItems = 1:10,
                        itemIDs = 1:20),
  itemUsageConstraint(nForms = 3, nItems = 20, operator = "=", targetValue = 1,
                      itemIDs = 1:20)
                    )

Analyze block exclusiveness

Description

Use exclusion tuples information to determine which assembled test blocks are exclusive.

Usage

analyzeBlockExclusion(
  solverOut,
  items,
  idCol,
  exclusionTuples,
  formName = "form"
)

Arguments

Details

If exclusion tuples have been used to assemble test forms (using the itemExclusionConstraint function), the resulting item blocks might also be exclusive. Using the initially used item exclusion tuples and the optimal solution given by useSolver this function determines, which item blocks are exclusive and can not be together in an assembled test form.

Value

A data.frame of block exclusions.

Examples

## Full workflow using itemExclusionTuples
# Example data.frame
items <- data.frame(ID = c("items1", "items2", "items3", "items4"),
                     exclusions = c("items2, items3", NA, NA, NA),
                     stringsAsFactors = FALSE)

# Create tuples
exTuples2 <- itemTuples(items = items, idCol = "ID", infoCol = "exclusions",
                    sepPattern = ", ")

#' ## Create constraints
exclusion_constraint <- itemExclusionConstraint(nForms = 2, itemTuples = exTuples2,
                                                itemIDs = items$ID)
depletion_constraint <- depletePoolConstraint(2, nItems = 4,
                                                itemIDs = items$ID)
target_constraint <- minimaxObjective(nForms = 2,
                                          itemValues = c(3, 1.5, 2, 4),
                                          targetValue = 1,
                                          itemIDs = items$ID)

opt_solution <- useSolver(list(exclusion_constraint, target_constraint,
                                        depletion_constraint))

analyzeBlockExclusion(opt_solution, items = items, idCol = "ID",
                       exclusionTuples = exTuples2)

Analyze complex block exclusiveness

Description

Use exclusion tuples information from independent test assembly problems to determine which assembled test blocks are exclusive.

Usage

analyzeComplexBlockExclusion(
  solverOut_list,
  items_list,
  idCol,
  exclusionTuples_list
)

Arguments

Details

If exclusion tuples have been used to assemble test forms (using the itemExclusionConstraint function), the resulting item blocks might also be exclusive. Using the initially used item exclusion tuples and the optimal solution given by useSolver this function determines, which item blocks are exclusive and can not be together in an assembled test form. analyzeComplexBlockExclusion allows analyzing block exclusiveness from separate test assembly problems. This can be useful if test forms consist of blocks containing different domains or dimensions.

Value

A data.frame of block exclusions.

Examples

## Full workflow using itemExclusionTuples
# tbd

Append a useSolver output

Description

Append a useSolver output of a successfully solved optimization problem to the initial item pool data.frame.

Usage

appendSolution(solverOut, items, idCol)

Arguments

Details

This function merges the initial item pool information in items to the solver output in solverOut.

Value

A data.frame.

Examples

## Example item pool
items <- data.frame(ID = 1:10,
itemValues = c(-4, -4, -2, -2, -1, -1, 20, 20, 0, 0))

## Test Assembly
usage <- itemUsageConstraint(nForms = 2, operator = "=",
                             targetValue = 1, itemIDs = items$ID)
perForm <- itemsPerFormConstraint(nForms = 2, operator = "=",
                                  targetValue = 5, itemIDs = items$ID)
target <- minimaxObjective(nForms = 2,
                               itemValues = items$itemValues,
                               targetValue = 0, itemIDs = items$ID)
sol <- useSolver(allConstraints = list(usage, perForm, target),
                                  solver = "lpSolve")

## Append Solution to existing item information
out <- appendSolution(sol, items = items, idCol = 1)

Create single value constraints with minimum and maximum.

Description

itemValuesDeviationConstraint creates constraints related to an item parameter/value. autoItemValuesMixMax automatically determines the appropriate targetValue and then calls itemValuesDeviationConstraint. The function only works for (dichotomous) dummy indicators with values 0 or 1.

Usage

autoItemValuesMinMaxConstraint(
  nForms,
  itemValues,
  testLength = NULL,
  allowedDeviation = NULL,
  relative = FALSE,
  verbose = TRUE,
  itemIDs = NULL
)

Arguments

Details

Two scenarios are possible when automatically determining the target value: (a) Either items with the selected property could be exactly distributed across test forms or (b) this is not possible. An example would be 2 test forms and 4 multiple choice items (a) or 2 test forms and 5 multiple choice items (b). If (a), the tolerance level works exactly as one would expect. If (b) the tolerance level is adapted, meaning that if tolerance level is 0 in example (b), allowed values are 2 or 3 multiple choice items per test form. For detailed documentation on how the minimum and maximum are calculated see also computeTargetValues.

Value

A sparse matrix.

Examples

autoItemValuesMinMaxConstraint(2, itemValues = c(0, 1, 0, 1))

Calculate Cumulants Lognormal Response Time Distribution

Description

These functions have been deprecated. See getMean3PLN or getVar3PLN instead.

Usage

calculateExpectedRT(lambda, phi, zeta, sdEpsi)

calculateExpectedRTvar(lambda, phi, zeta, sdEpsi)

Arguments

Functions

• calculateExpectedRT(): Calculate mean 3PLN

• calculateExpectedRTvar(): Calculate mean 2PLN

Calculate Item Information Function

Description

Calculate item information function given item parameters of the 1PL, 2PL or 3PL IRT model.

Usage

calculateIIF(A = rep(1, length(B)), B, C = rep(0, length(B)), theta, D = 1.7)

Arguments

Value

a matrix, with columns for different theta and rows for different items

References

van der Linden, W. J. (2005). Linear models for optimal test design. New York, NY: Springer.

Examples

# TIF for a single item (2PL model)
calculateIIF(A = 0.8, B = 1.1, theta = 0)

# TIF for multiple items (1PL model)
calculateIIF(B = c(1.1, 0.8, 0.5), theta = 0)

# TIF for multiple theta-values (3PL model)
calculateIIF(B = -0.5, C = 0.25, theta = c(-1, 0, 1))

# TIF for multiple items and multiple ability levels (2PL model)
calculateIIF(A = c(0.7, 1.1, 0.8), B = c(1.1, 0.8, 0.5),
            theta = c(-1, 0, 1))

Capped Maximin Constraint.

Description

Create maximin-constraints related to an item parameter/value. That is, the created constraints can be used to maximize the minimal sum of the item values (itemValues), while at the same time automatically setting an ideal upper limit to the overflow. More specifically, the capped minimax method described by Luo (2020) is used.

Usage

cappedMaximinObjective(
  nForms,
  itemValues,
  weight = 1,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Value

An object of class "constraint".

References

Xiao Luo (2020). Automated Test Assembly with Mixed-Integer Programming: The Effects of Modeling Approaches and Solvers. Journal of Educational Measurement, 57(4), 547-565. doi:10.1111/jedm.12262

Examples

# constraint that minimizes the maximum difference per test form value and a
#   target value of 0
cappedMaximinObjective(nForms = 2, itemValues = rep(-2:2, 2))

Combine constraints

Description

Combine multiple constraint-objects into one constraint object.

Usage

combineConstraints(..., message = TRUE)

Arguments

Value

A data.frame of block exclusions.

Examples

combineConstraints(
 itemValuesConstraint(2, 1:10, operator = ">=", targetValue = 4),
 itemValuesConstraint(2, 1:10, operator = "<=", targetValue = 6)
)

Compute target values based on the item pool.

Description

Compute target values for item values/categories based on the number of items in the item pool, the number of test forms to assemble and the number of items in each test form (i.e., test length).

Usage

computeTargetValues(
  itemValues,
  nForms,
  testLength = NULL,
  allowedDeviation = NULL,
  relative = FALSE
)

## Default S3 method:
computeTargetValues(
  itemValues,
  nForms,
  testLength = NULL,
  allowedDeviation = NULL,
  relative = FALSE
)

## S3 method for class 'factor'
computeTargetValues(
  itemValues,
  nForms,
  testLength = NULL,
  allowedDeviation = NULL,
  relative = FALSE
)

Arguments

Details

Both for numerical and categorical item values, the target values are the item pool average scaled by the ratio of items in the forms and items in the item pool. The behavior of the function changes depending on the class of itemValues.

When itemValues is a numerical vector, an when allowedDeviation is NULL (the default), only one target value is computed. This value could be used in the targetConstraint-function. Otherwise (i.e., allowedDeviation is a numerical value), the target is computed, but a minimal and a maximal (target)value are returned, based on the allowed deviation. When relative == TRUE the allowed deviation should be expressed as a proportion. In that case the minimal and maximal values are a computed proportionally.

When itemValues is a factor, it is assumed that the item values are item categories, and hence only whole valued frequencies are returned. To be more precise, a matrix with the minimal and maximal target frequencies for every level of the factor are returned. When allowedDeviation is NULL, the difference between the minimal and maximal value is one (or zero). As a consequence, dummy-item values are best specified as a factor (see examples).

Value

a vector or a matrix with target values (see details)

Methods (by class)

• computeTargetValues(default): compute target values

• computeTargetValues(factor): compute target frequencies for item categories

Examples

## Assume an item pool with 50 items with random item information values (iif) for
## a given ability value.
set.seed(50)
itemInformations <- runif(50, 0.5, 3)

## The target value for the test information value (i.e., sum of the item
## informations) when three test forms of 10 items are assembled is:
computeTargetValues(itemInformations, nForms = 3, testLength = 10)

## The minimum and maximum test iformation values for an allowed deviation of
## 10 percent are:
computeTargetValues(itemInformations, nForms = 3, allowedDeviation = .10,
   relative = TRUE, testLength = 10)


## items_vera$MC is dummy variable indication which items in the pool are multiple choise
str(items_vera$MC)

## when used as a numerical vector, the dummy is not treated as a categorical
## indicator, but rather as a numerical value.
computeTargetValues(items_vera$MC, nForms = 14)
computeTargetValues(items_vera$MC, nForms = 14, allowedDeviation = 1)

## Therefore, it is best to convert dummy variables into a factor, so that
## automatically freqyencies are returned
MC_factor <- factor(items_vera$MC, labels = c("not MC", "MC"))
computeTargetValues(MC_factor, nForms = 14)
computeTargetValues(MC_factor, nForms = 3)

## The computed minimum and maximum frequencies can be used to create contstraints.
MC_ranges <- computeTargetValues(MC_factor, nForms = 3)
itemCategoryRangeConstraint(3, MC_factor, range = MC_ranges)

## When desired, the automatically computed range can be adjusted by hand. This
##  can be of use when only a limited set of the categories should be constrained.
##  For instance, when only the multiple-choice items should be constrained, and
##  the non-multiple-choice items should not be constrained, the minimum and
##  maximum value can be set to a very small and a very high value, respectively.
##  Or to other sensible values.
MC_ranges["not MC", ] <- c(0, 40)
MC_ranges
itemCategoryRangeConstraint(3, MC_factor, range = MC_ranges)

Use complete item pool.

Description

Creates constraints that assure that every item in the item pool is used (at least) once. Essentially a wrapper around itemUsageConstraint.

Usage

depletePoolConstraint(nForms, nItems = NULL, itemIDs = NULL)

Arguments

Value

A sparse matrix.

Examples

depletePoolConstraint(2, itemIDs = 1:10)

Convert dummy variables to factor.

Description

Convert multiple dummy variables into a single factor variable.

Usage

dummiesToFactor(dat, dummies, facVar, nameEmptyCategory = "_none_")

Arguments

Details

The content of a single factor variable can alternatively be stored in multiple dichotomous dummy variables coded with 0/1 or NA/1. 1 always has to refer to "this category applies". The function requires factor levels to be exclusive (i.e. only one factor level applies per row.).

Value

A data.frame containing the newly created factor.

Examples

# Example data set
tdat <- data.frame(ID = 1:3, d1=c(1, 0, 0), d2 = c(0, 1, 0), d3 = c(0, 0, 1))

dummiesToFactor(tdat, dummies = c("d1", "d2", "d3"), facVar = "newFac")

Calculate Cumulants Lognormal Response Time Distribution

Description

Calculate the first and second cumulants (i.e., mean and variance) of item response time distributions given item parameters of the three-parameter log-normal model (3PLN) for response times.

Usage

getMean3PLN(lambda, phi = rep(1, length(lambda)), zeta, sdEpsi)

getMean2PLN(lambda, zeta, sdEpsi)

getVar3PLN(lambda, phi = rep(1, length(lambda)), zeta, sdEpsi)

getVar2PLN(lambda, zeta, sdEpsi)

Arguments

Details

Calculate the first and second cumulant of the two-parameter log-normal (2PLN) model for response times according to van der Linden (2006) or the 3PLN according to Klein Entink et al. (2009). If the speed sensitivity parameter phi in the 3PLN equals 1, the model reduces to the 2PLN, yet with a different parameterization for the item specific residual variance sdEpsi compared to van der Linden (2006).

The cumulants are computed for one or more speed parameters, and for one or more sets of item parameters.

The calculation is based on Fenton (1960). For the model by van der Linden (2006), the calculation was first introduced by van der Linden (2011).

Value

a matrix with either the mean or the variance of the response time distributions, with columns for different zeta and rows for different items

Functions

• getMean3PLN(): Calculate mean 3PLN

• getMean2PLN(): Calculate mean 2PLN

• getVar3PLN(): Calculate variance 3PLN

• getVar2PLN(): Calculate variance 2PLN

References

Fenton, L. (1960). The sum of log-normal probability distributions in scatter transmission systems. IRE Transactions on Communication Systems, 8, 57-67.

Klein Entink, R. H., Fox, J.-P., & van der Linden, W. J. (2009). A multivariate multilevel approach to the modeling of accuracy and speed of test takers. Psychometrika, 74(1), 21-48.

van der Linden, W. J. (2006). A lognormal model for response times on test items. Journal of Educational and Behavioral Statistics, 31(2), 181-204.

van der Linden, W. J. (2011). Test design and speededness. Journal of Educational Measurement, 48(1), 44-60.

Examples

# expected RT for a single item (van der Linden model)
getMean2PLN(lambda = 3.8, zeta = 0, sdEpsi = 0.3)
getVar2PLN(lambda = 3.8, zeta = 0, sdEpsi = 0.3)

# expected RT for multiple items (van der Linden model)
getMean2PLN(lambda = c(4.1, 3.8, 3.5), zeta = 0,
                   sdEpsi = c(0.3, 0.4, 0.2))
getVar2PLN(lambda = c(4.1, 3.8, 3.5), zeta = 0,
                   sdEpsi = c(0.3, 0.4, 0.2))

# expected RT for multiple items and multiple spped levels (Klein Entink model)
getMean3PLN(lambda = c(3.7, 4.1, 3.8), phi = c(1.1, 0.8, 0.5),
                    zeta = c(-1, 0, 1), sdEpsi = c(0.3, 0.4, 0.2))
getVar3PLN(lambda = c(3.7, 4.1, 3.8), phi = c(1.1, 0.8, 0.5),
                    zeta = c(-1, 0, 1), sdEpsi = c(0.3, 0.4, 0.2))

Inspect a useSolver output

Description

Process a useSolver output of a successfully solved optimization problem to a list so it becomes humanly readable.

Usage

inspectSolution(
  solverOut,
  items,
  idCol,
  colNames = names(items),
  colSums = TRUE
)

Arguments

Details

This function merges the initial item pool information in items to the solver output in solverOut. Relevant columns can be selected via colNames. Column sums within test forms are calculated if possible and if colSum is set to TRUE.

Value

A list with assembled blocks as entries. Rows are the individual items. A final row is added, containing the sums of each column.

Examples

## Example item pool
items <- data.frame(ID = 1:10,
itemValues = c(-4, -4, -2, -2, -1, -1, 20, 20, 0, 0))

## Test Assembly
usage <- itemUsageConstraint(nForms = 2, operator = "=",
                             targetValue = 1, itemIDs = items$ID)
perForm <- itemsPerFormConstraint(nForms = 2, operator = "=",
                                  targetValue = 5, itemIDs = items$ID)
target <- minimaxObjective(nForms = 2,
                               itemValues = items$itemValues,
                               targetValue = 0, itemIDs = items$ID)
sol <- useSolver(allConstraints = list(usage, perForm, target),
                                  solver = "lpSolve")

## Inspect Solution
out <- inspectSolution(sol, items = items, idCol = 1, colNames = "itemValues")

Create item category constraints.

Description

Create constraints related to item categories/groupings (as represented by itemCategories). That is, the created constraints assure that the number of items of each category per test form is either (a) smaller or equal than (operator = "<="), (b) equal to (operator = "="), or (c) greater than or equal to (operator = ">=") the corresponding targetValues.

Usage

itemCategoryConstraint(
  nForms,
  itemCategories,
  operator = c("<=", "=", ">="),
  targetValues,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemCategories)
)

Arguments

Value

A object of class "constraint".

Examples

## constraints to make sure that there are at least 3 items of each item type
## in each test form
nItems <- 30
item_type <- factor(sample(1:3, size = nItems, replace = TRUE))
itemCategoryConstraint(2, item_type, ">=", targetValues = c(1, 3, 2))

Create item category constraints with minimum and maximum.

Description

itemCategoriesRange, itemCategoriesMin, and itemCategoriesMax create constraints related to item categories/groupings (as represented by itemCategories). That is, the created constraints assure that the number of items of each category per test form is either smaller or equal than the specified max, greater than or equal to min or both range.

Usage

itemCategoryRangeConstraint(
  nForms,
  itemCategories,
  range,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemCategories)
)

itemCategoryMinConstraint(
  nForms,
  itemCategories,
  min,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemCategories)
)

itemCategoryMaxConstraint(
  nForms,
  itemCategories,
  max,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemCategories)
)

itemCategoryDeviationConstraint(
  nForms,
  itemCategories,
  targetValues,
  allowedDeviation,
  relative = FALSE,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemCategories)
)

Arguments

Details

itemCategoriesDeviation also constrains the minimal and the maximal value of the number of items of each category per test form, but based on chosen targetValues, and maximal allowed deviations (i.e., allowedDeviation) from those targetValues.

Value

A sparse matrix.

Functions

• itemCategoryMinConstraint(): constrain minimum value

• itemCategoryMaxConstraint(): constrain maximum value

• itemCategoryDeviationConstraint(): constrain the distance form the targetValues

Examples

## constraints to make sure that there are at least 2 and maximally 4
##  items of each item type in each test form
nItems <- 30
item_type <- factor(sample(1:3, size = nItems, replace = TRUE))
itemCategoryRangeConstraint(2, item_type, range = cbind(min = rep(2, 3), max = rep(4, 3)))

## or alternatively
itemCategoryDeviationConstraint(2, item_type,
targetValues = rep(3, 3),
allowedDeviation = rep(4, 3))

Create item inclusion or exclusion constraints.

Description

Create constraints that prohibit that item pairs occur in the same test forms (exclusions) or force item pairs to be in the same test forms (inclusions).

Usage

itemExclusionConstraint(
  nForms,
  itemTuples,
  itemIDs,
  whichForms = seq_len(nForms),
  info_text = NULL
)

itemInclusionConstraint(
  nForms,
  itemTuples,
  itemIDs,
  whichForms = seq_len(nForms),
  info_text = NULL
)

Arguments

Details

Item tuples can, for example, be created by the function itemTuples.

Value

An object of class "constraint".

Functions

• itemExclusionConstraint(): item pair exclusion constraints

• itemInclusionConstraint(): item pair inclusion constraints

Examples

## Simple Exclusion Example
# item-IDs
IDs <- c("item1", "item2", "item3", "item4")

# exclusion tuples: Item 1 can not be in the test form as item 2 and 3
exTuples <- data.frame(v1 = c("item1", "item1"), v2 = c("item2", "item3"),
                       stringsAsFactors = FALSE)
# inclusion tuples: Items 2 and 3 have to be in the same test form
inTuples <- data.frame(v1 = c("item2"), v2 = c("item3"),
                       stringsAsFactors = FALSE)

# create constraints
itemExclusionConstraint(nForms = 2, itemTuples = exTuples, itemIDs = IDs)
itemInclusionConstraint(nForms = 2, itemTuples = inTuples, itemIDs = IDs)


########
## Full workflow for exclusions using itemTuples
# Example data.frame
items <- data.frame(ID = c("item1", "item2", "item3", "item4"),
                     infoCol = c("item2, item3", NA, NA, NA))

# Create tuples
exTuples2 <- itemTuples(items = items, idCol = "ID", infoCol = "infoCol",
                    sepPattern = ", ")

## Create constraints
itemExclusionConstraint(nForms = 2, itemTuples = exTuples2, itemIDs = IDs)

Create item tuples.

Description

If item inclusions or exclusions are stored as a character vector, itemTuples separates this vector and creates item pairs ('tuples').

Usage

itemTuples(items, idCol = "ID", infoCol, sepPattern = ", ")

Arguments

Details

Tuples can be used by itemExclusionConstraint to set up exclusion constraints and by itemInclusionConstraint to set up inclusion constraints. Note that a separator pattern has to be used consistently throughout the column (e.g. ", ").

Value

A data.frame with two columns.

Examples

# Example data.frame
items <- data.frame(ID = c("item1", "item2", "item3", "item4"),
                     exclusions = c("item2, item3", NA, NA, NA))

# Create tuples
itemTuples(items = items, idCol = "ID", infoCol = 2,
                    sepPattern = ", ")

Create item usage constraints.

Description

Creates constraints related to item usage. That is, the number of times an item is selected is constrained to be either (a) smaller or equal than (operator = "<="), (b) equal to (operator = "="), or (c) greater or equal than (operator = ">=") the chosen value.

Usage

itemUsageConstraint(
  nForms,
  nItems = NULL,
  formValues = rep(1, nForms),
  operator = c("<=", "=", ">="),
  targetValue = 1,
  whichItems = NULL,
  info_text = NULL,
  itemIDs = NULL
)

Arguments

Details

When operator = "<=" and value = 1 (the default), each item can be selected maximally once, which corresponds with assuring that there is no item overlap between the forms. When operator = "=" and value = 1, each item is used exactly once, which corresponds to no item-overlap and complete item pool depletion.

If certain items are required in the resulting test form(s), as for example anchor items, whichItems can be used to constrain the usage of these items to be exactly 1. whichItems can either be a numeric vector with item numbers or a character vector with item identifiers corresponding to itemIDs.

Value

An object of class "constraint".

Examples

## create no-item overlap constraints with item pool depletion
##  for 2 test forms with an item pool of 20 items
itemUsageConstraint(2, operator = "=", targetValue = 1,
                    itemIDs = 1:20)

## force certain items to be in the test, others not
usage1 <- itemUsageConstraint(2, operator = "<=", targetValue = 1,
                    itemIDs = paste0("item", 1:20))
usage2 <- itemUsageConstraint(2, operator = "=", targetValue = 1,
                    itemIDs = paste0("item", 1:20),
                    whichItems = c("item5", "item8", "item10"))

Constrain the sum of item values per form.

Description

Create constraints related to an item parameter/value. That is, the created constraints assure that the sum of the item values (itemValues) per test form is either (a) smaller than or equal to (operator = "<="), (b) equal to (operator = "="), or (c) greater than or equal to (operator = ">=") the chosen targetValue.

Usage

itemValuesConstraint(
  nForms,
  itemValues,
  operator = c("<=", "=", ">="),
  targetValue,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Details

When operator is "<=", the constraint can be mathematically formulated as: \[\sum_{i=1}^{I} v_i \times x_{if} \leq t , \; \; \; \code{for} \: f \in G,\] where \(I\) refers to the number of items in the item pool, \(v_i\) is the itemValue for item \(i\) and \(t\) is the targetValue. Further, \(G\) corresponds to whichForms, so that the above inequality constraint is repeated for every test form \(f\) in \(G\). In addition, let \(\boldsymbol{x}\) be a vector of binary decision variables with length \(I \times F\), where \(F\) is nForms. The binary decision variables \(x_{if}\) are defined as:

Value

An object of class "constraint".

Examples

## constraints to make sure that the sum of the item values (1:10) is between
## 4 and 6
combineConstraints(
  itemValuesConstraint(2, 1:10, operator = ">=", targetValue = 4),
  itemValuesConstraint(2, 1:10, operator = "<=", targetValue = 6)
)

Create single value constraints with minimum and maximum.

Description

itemValuesRangeConstraint, itemValuesMinConstraint, and itemValuesMaxConstraint create constraints related to an item parameter/value. That is, the created constraints assure that the sum of the itemValues is smaller than or equal to max, greater than or equal to min, or both range.

Usage

itemValuesRangeConstraint(
  nForms,
  itemValues,
  range,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

itemValuesMinConstraint(
  nForms,
  itemValues,
  min,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

itemValuesMaxConstraint(
  nForms,
  itemValues,
  max,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

itemValuesDeviationConstraint(
  nForms,
  itemValues,
  targetValue,
  allowedDeviation,
  relative = FALSE,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Details

itemValuesDeviationConstraint also constrains the minimal and the maximal value of the sum of the itemValues, but based on a chosen and a maximal allowed deviation (i.e., allowedDeviation) from that targetValue.

Value

An object of class "constraint".

Functions

• itemValuesMinConstraint(): constrain minimum value

• itemValuesMaxConstraint(): constrain maximum value

• itemValuesDeviationConstraint(): constrain the distance form the targetValue

Examples

## constraints to make sure that the sum of the item values (1:10) is between
## 4 and 6
itemValuesRangeConstraint(2, 1:10, range(min = 4, max = 6))

## or alternatively
itemValuesDeviationConstraint(2, 1:10, targetValue = 5,
allowedDeviation = 1)

Create number of items per test form constraints.

Description

Creates constraints related to the number of items in each test form.

Usage

itemsPerFormConstraint(
  nForms,
  nItems = NULL,
  operator = c("<=", "=", ">="),
  targetValue,
  whichForms = seq_len(nForms),
  itemIDs = NULL
)

Arguments

Details

The number of items per test form is constrained to be either (a) smaller or equal than (operator = "<="), (b) equal to (operator = "="), or (c) greater or equal than (operator = ">=") the chosen value.

Value

An object of class "constraint".

Examples

## Constrain the test forms to have exactly five items
itemsPerFormConstraint(3, operator = "=", targetValue = 5,
                       itemIDs = 1:20)

Small simulated item pool example.

Description

A data.frame containing 165 items calibrated using a 3PL model. This item pool is analogous to one of the item pools used in Diao & van der Linden (2011).

Usage

items_diao

Format

A data.frame .

item

Item identifier.

a

Discrimination parameter.

b

Difficulty parameter.

c

Pseudo-guessing parameter.

category

Content category.

References

Diao, Q. & van der Linden, W.J. (2011). Automated test assembly using lp_solve version 5.5 in R. Applied Psychological Measurement, 35 (5), 398-409.

Simulated item pool example.

Description

A data.frame containing 209 calibrated items with different categorical and metric properties, comparable to an item pool from a large-scale assessment.

Usage

items_lsa

Format

A data.frame .

testlet

Testlet identifier (items in the same testlet share a common stimulus.

item

Item identifier.

level

Competence level.

format

Item format.

frequency

Solution frequency.

infit

Item infit.

time

Average response time in seconds.

anchor

Is the item an anchor item?

Small simulated item pool example.

Description

A data.frame containing 30 items with different categorical and metric properties.

Usage

items_mini

Format

A data.frame .

item

Item identifier.

format

Item format (e.g., multiple choice, open answer, order item).

time

Average response time in seconds.

difficulty

IRT difficulty parameter.

Small simulated item pool example.

Description

A data.frame containing 100 not yet calibrated items with different categorical and metric properties.

Usage

items_pilot

Format

A data.frame .

item

Item identifier.

diffCategory

Item difficulty (five categories).

format

Item format (multiple choice, constructed multiple choice, or open answer).

domain

Item domain (listening, reading, or writing).

time

Average response times in seconds.

exclusions

Items which can not be in the same test form.

Small artificial item pool example.

Description

A data.frame containing 80 items with different categorical and metric properties.

Usage

items_vera

Format

A data.frame .

item

Item identifier.

exclusions

Items which can not be in the same test form.

time

Average response times in minutes. 2.5 equals 2 minutes and 30 seconds, for example.

subitems

Number of sub items.

MC, CMC, short_answer, open

Answer formats.

diff_1, diff_2, diff_3, diff_4, diff5

Difficulty categories.

Create item exclusion tuples from matrix.

Description

If item exclusions are stored as a matrix, matrixExclusionTuples transforms this format into item pairs ('tuples'). Information on exclusions has to be coded as 1 (items are exclusive) and 0 (items are not exclusive).

Usage

matrixExclusionTuples(exclMatrix)

Arguments

Details

Exclusion tuples can be used by itemExclusionConstraint to set up exclusion constraints.

Value

A data.frame with two columns.

Examples

# Example data.frame
exclDF <- data.frame(c(0, 1, 0, 0),
                     c(1, 0, 0, 1),
                     c(0, 0, 0, 0),
                     c(0, 1, 0, 0))
rownames(exclDF) <- colnames(exclDF) <- paste0("item_", 1:4)

# Create tuples
matrixExclusionTuples(exclDF)

Max Constraint.

Description

Create max-constraints related to an item parameter/value. That is, the created constraints can be used to maximize the sum of the item values (itemValues) of the test form. Note that this constraint can only be used when only one test form has to be assembled.

Usage

maxObjective(
  nForms,
  itemValues,
  weight = 1,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Value

An object of class "constraint".

Examples

# constraint that maximizes the sum of the itemValues
maxObjective(nForms = 1, itemValues = rep(-2:2, 2))

Maximin Constraint.

Description

Create maximin-constraints related to an item parameter/value. That is, the created constraints can be used to maximize the minimal sum of the item values (itemValues), while at the same time setting an upper limit to the overflow by means of a maximally allowed deviation allowedDeviation.

Usage

maximinObjective(
  nForms,
  itemValues,
  allowedDeviation,
  weight = 1,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Value

An object of class "constraint".

Examples

# constraint that minimizes the maximum difference per test form value and a
#   target value of 0
maximinObjective(nForms = 2, itemValues = rep(-2:2, 2),
                 allowedDeviation = 1)

Min Constraint.

Description

Create min-constraints related to an item parameter/value. That is, the created constraints can be used to minimize the sum of the item values (itemValues) of the test form. Note that this constraint can only be used when only one test form has to be assembled.

Usage

minObjective(
  nForms,
  itemValues,
  weight = 1,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Value

An object of class "constraint".

Examples

# constraint that maximizes the sum of the itemValues
maxObjective(nForms = 1, itemValues = rep(-2:2, 2))

Minimax Constraint.

Description

Create minimax-constraints related to an item parameter/value. That is, the created constraints can be used to minimize the maximum distance between the sum of the item values (itemValues) per test form and the chosen targetValue.

Usage

minimaxObjective(
  nForms,
  itemValues,
  targetValue,
  weight = 1,
  whichForms = seq_len(nForms),
  info_text = NULL,
  itemIDs = names(itemValues)
)

Arguments

Value

An object of class "constraint".

Examples

# constraint that minimizes the maximum difference per test form value and a
#   target value of 0
minimaxObjective(nForms = 2,
                 itemValues = rep(-2:2, 2),
                 targetValue = 0)

Create item inclusion tuples from item stem.

Description

If item-stimulus hierarchies are stored in a single stimulus column, stemInclusionTuples transforms this format into item pairs ('tuples').

Usage

stemInclusionTuples(items, idCol = "ID", stemCol)

Arguments

Details

Inclusion tuples can be used by itemInclusionConstraint to set up inclusion constraints.

Value

A data.frame with two columns.

Examples

# Example data.frame
inclDF <- data.frame(ID = paste0("item_", 1:6),
          stem = c(rep("stim_1", 3), "stim_3", "stim_4", "stim_3"),
          stringsAsFactors = FALSE)

# Create tuples
stemInclusionTuples(inclDF, idCol = "ID", stemCol = "stem")

Use a solver for a list of constraints.

Description

Use a mathematical programming solver to solve a list for constrains.

Usage

useSolver(
  allConstraints,
  solver = c("GLPK", "lpSolve", "Gurobi", "Symphony"),
  timeLimit = Inf,
  formNames = NULL,
  ...
)

Arguments

Details

Wrapper around the functions of different solvers (gurobi::gurobi(), lpSolve::lp(), ... for a list of constraints set up via eatATA. Rglpk is used per default.

Additional arguments can be passed through ... and vary from solver to solver (see their respective help pages, lp or Rglpk_solve_LP); for example time limits can not be set for lpSolve.

Value

A list with the following elements:

solution_found

Was a solution found?

solution

Numeric vector containing the found solution.

solution_status

Was the solution optimal?

Examples

nForms <- 2
nItems <- 4

# create constraits
target <- minimaxObjective(nForms = nForms, c(1, 0.5, 1.5, 2),
                       targetValue = 2, itemIDs = 1:nItems)
noItemOverlap <- itemUsageConstraint(nForms, operator = "=", itemIDs = 1:nItems)
testLength <- itemsPerFormConstraint(nForms = nForms,
                           operator = "<=", targetValue = 2, itemIDs = 1:nItems)

# use a solver
result <- useSolver(list(target, noItemOverlap, testLength),
  itemIDs = paste0("Item_", 1:4),
  solver = "GLPK")