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