This document explains how to create constraints data for `loadConstraints()`

. In test assembly, practitioners often want to select items satisfying various types of constraints. As of *TestDesign* version 1.1.0, constraints can be read in from `data.frame`

objects or `.csv`

spreadsheet files. Data is expected to be in the following structure:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

1 | Number | Item | 30 | 30 | ||

2 | Number | Item | LEVEL == 3 | 10 | 10 | |

3 | Number | Item | LEVEL == 4 | 10 | 10 | |

4 | Number | Item | LEVEL == 5 | 10 | 10 | |

5 | Number | Item | STANDARD == 1 | 17 | 20 |

Constraints data must have seven columns, named as `CONSTRAINT`

, `TYPE`

, `WHAT`

, `CONDITION`

, `LB`

, `UB`

, `ONOFF`

on the first row. Beginning from the second row, each row must have corresponding values for each column. A convenient way to creating constraints is to use a spreadsheet application (e.g. Excel) and work on the content from there.

This column serves as indices. One number must be put into each row, beginning from 1 and incrementing by 1. `loadConstraints()`

recreates these if necessary.

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 |

`Sum`

specifies the constraint to be applied to the sum of attributes of selected items (if`WHAT`

column is`Item`

), or of selected item sets (if`WHAT`

column is`Stimulus`

). For example, the following row tells the solver to keep the sum of`WORDS`

between 500–600.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

2 | Sum | Item | WORDS | 500 | 600 |

`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 supplied attributes.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

32 | Order | Item | LEVEL |

`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”) |

`Include`

specifies the items matching the condition to be always included in selection. For example, the following row tells the solver to include items`SC00003`

and`SC00004`

:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

34 | Include | Item | ID %in% c(“SC00003”, “SC00004”) |

`Exclude`

specifies the items matching the condition to be always excluded from selection. The following row tells the solver to exclude items that match`PTBIS < 0.15`

, based on supplied item attributes.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

35 | Exclude | Item | PTBIS < 0.15 |

`AllOrNone`

specifies the items matching the condition to be either all included or all excluded. To tell the solver to either select 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”) |

This column specifies the unit of assembly the constraint uses. Expected values are `Item`

or `Stimulus`

.

This column specifies the condition of the constraint. An R expression returning logical values (`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.

For `TYPE == SUM`

, using a variable name imposes the constraint on the sum of the variable. The following row tells the solver to keep the sum of `WORDS`

between 500–600.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

2 | Sum | Item | WORDS | 500 | 600 |

For `TYPE == SUM`

, constraints on conditional sums can be imposed by using a variable name, placing a comma, and then giving an R expression returning logical values. The following row tells the solver to keep the sum of `WORDS`

within `DOK == 1`

items between 50–80.

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

3 | Sum | Item | WORDS, DOK == 1 | 50 | 80 |

In set-based assembly, `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 |

These two columns specify lower and upper bounds on the number of selected items. These must be specified when `TYPE`

is `Number`

, and otherwise must be left empty.

Some example rows are provided.

- To select a total of 12 items:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

1 | Number | Item | 12 | 12 |

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

:

CONSTRAINT | TYPE | WHAT | CONDITION | LB | UB | ONOFF |
---|---|---|---|---|---|---|

17 | Number | Item | DOK >= 2 | 15 | 30 |

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 | OFF |