# Creating constraints file in TestDesign package

#### Sangdon Lim

### Introduction

This document explains how to create a constraint file. In test assembly, practitioners often want to select the items that satify various types of constraints. As of TestDesign version 0.2, constraints can be read in from a `.csv` spreadsheet file. The file is expected to be in the following structure:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
1 | Number | Item |  | 30 | 30 | NA
2 | Number | Item | LEVEL == 3 | 10 | 10 | NA
3 | Number | Item | LEVEL == 4 | 10 | 10 | NA
4 | Number | Item | LEVEL == 5 | 10 | 10 | NA
5 | Number | Item | STANDARD == 1 | 17 | 20 | NA

The constraint file should have 7 columns, named as `CONSTRAINT`, `TYPE`, `WHAT`, `CONDITION`, `LB`, `UB`, `ONOFF` on the first row of the file. Beginning from the second row, each row should have the corresponding values for the 7 columns. A convenient way to creating the file is to use a spreadsheet application (e.g. Excel), work on the contents from there, and then saving it as a `.csv` file.

#### CONSTRAINT

This column serves as indices for the constraints. A single numeric value should be put into each row, incrementing by 1.

#### TYPE

This column specifies the type of constraint. Following values are expected: `Number`, `Order`, `Enemy`, `Include`, `Exclude`, `AllorNone`.

- `Number` specifies the constraint to be applied to the number of selected items (if `WHAT` column is `Item`), or to the number of selected item sets (if `WHAT` column is `Stimulus`). For example, the following row tells the solver to select a total of 30 items.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
1 | Number | Item |  | 30 | 30 | NA

- `Order` specifies the selection to be made in ascending order. The following row tells the solver to select the items in ascending `LEVEL`, based on the supplied item attributes.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
32 | Order | Item | LEVEL | NA | NA | NA

- `Enemy` specifies the items (or item sets) matching the condition to be treated as enemy items. To tell the solver to select at most one of the two items:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
33 | Enemy | Item | ID %in% c(“SC00001”, “SC00002”) | NA | NA | NA

- `Include` specifies the items matching the condition to be included in selection. For example, the following row tells the solver to include the two items `SC00003` and `SC00004`:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
34 | Include | Item | ID %in% c(“SC00003”, “SC00004”) | NA | NA | NA

- `Exclude` specifies the items matching the condition to be excluded in selection. The following row tells the solver to exclude the items satisfying `PTBIS < 0.15`, based on the supplied item attributes.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
35 | Exclude | Item | PTBIS < 0.15 | NA | NA | NA

- `AllOrNone` specifies the items matching the condition to be either all included or all excluded. To tell the solver to either select the items `SC00005` and `SC00006` at the same time or exclude them at the same time:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
36 | AllOrNone | Item | ID %in% c(“SC00005”, “SC00006”) | NA | NA | NA

#### WHAT

This column specifies where the constraint is applied. The expected values are `Item` or `Stimulus`.

#### CONDITION

This column specifies the condition of the constraint. An R expression returning a logical value (`TRUE` or `FALSE`) is expected. The variables supplied in item attributes can be used in the expression as variable names.

Some examples are:

- `"STANDARD %in% c(2, 4)"` tells the solver to select when `STANDARD` is either 2 or 4.
- `"STANDARD %in% c(2, 4) & DOK >= 3"` tells the solver to select when `STANDARD` is either 2 or 4, and also `DOK` is at least 3.
- `!is.na(FACIT)` tells the solver to select when `FACIT` is not empty.
- Leave it empty to not specify any condition. This is useful in constraining the total number of items.

Also, `Per Stimulus` can be used to specify the number of items to select in each stimulus. For example, the following row tells the solver to select 4 to 6 items per stimulus:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
3 | Number | Item | Per Stimulus | 4 | 6 |

#### LB and UB

These two columns specify the lower and upper bounds on the number of selected items. These columns should be specified when `TYPE` is `Number`, and should be left empty otherwise.

Some example rows are provided.

- To select a total of 12 items:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
1 | Number | Item |  | 12 | 12 | NA

- To select 15 to 30 items satisfying `DOK >= 2`:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
17 | Number | Item | DOK >= 2 | 15 | 30 |

#### ONOFF

Set this to `OFF` to turn off the constraint from being applied. `ON` or leaving it blank applies the constraint. The following example specifies the order constraint to be not applied.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF
--- | --- | --- | --- | --- | --- | ---
18 | Order | Passage | CONTENT | NA | NA | OFF