Checklists (r9)

A checklist is a multi-punch system variable that serves as a flag to identify respondents who meet a particular condition, such as failing an attention check. Checklists are defined using the define checklists widget.

Once a checklist is defined, it may be triggered anywhere in the survey. Each instance of a trigger automatically adds an option to the checklist. That option is punched if the trigger's condition is met when the respondent submits the survey page containing the trigger. Checklists may be triggered using a trigger checklist widget, a trigger tag on a question, or a trigger decorator on an option.

Syntax

Defining checklists

To create a checklist, use the define checklists widget (alternatively, define checklist). Multiple checklists can be defined, one per line. The checklist ID must begin with a letter, but may contain numbers and underscores. The ID must be unique.

define checklists
chapter: Z
attn. Attention checks
short_oe. Open-end response less than 20 characters long

The chapter tag is optional. Include this tag to organize the checklist fields in the reporting field tree.  If individual checklists need to be placed in different chapters, use multiple define checklists widgets, one for each chapter. Checklists will be placed at the end of the Survey fields chapter by default. 

Unlike a multi-punch variable, you do not need to define options for a checklist. Instead, the options are defined automatically at each instance of a trigger for that checklist throughout the survey.

Triggering checklists

Checklists may be triggered using a standalone widget, a tag on a question or table, or a decorator on an option. Each trigger is associated with a specific option in the checklist. The option is automatically created along with the trigger. When used as a tag or decorator, trigger checklist can use the alias trigger.

Widget

For the trigger checklist widget, you first need the ID of the checklist being triggered. Then, the id and text tags are required to define the option ID and option text that will be added to the checklist field. Lastly, the condition tag is required to define the condition which triggers the checklist.

1. Which of these is a musical instrument? 
type: radio 
1. Apple 
2. Bicycle
3. Piano
4. Airplane
5. Ocean

trigger checklist: attn
id: Q1 
text: Did not select 'piano'
condition: noneChecked($Q1,3)

Tag (question)

When using the trigger checklist tag (alias, trigger), input the checklist ID, then write the condition inside a condition decorator.

1. Which of these is a musical instrument? 
type: radio 
trigger: attn { condition: noneChecked($Q1,3) } { trigger text: Did not select 'piano' } { trigger id: Q1_ATTN }
1. Apple 
2. Bicycle
3. Piano
4. Airplane
5. Ocean

The trigger text and trigger id decorators are optional. These will default to the question text and question ID if not specified. You may also use text and id as shortened forms of these decorators.

Tag (table)

Checklist triggers may also be added to tables using the trigger tag.

2. Rate your satisfaction with each of the following brands.
type: radio table
1. Unsatisfied
2. Neutral
3. Satisfied
99. Not aware of this brand
trigger: attn { condition: noneChecked($Q2R9,99) } { trigger text: Rated fake brand }
rowsfrom: BRANDS

Decorator

The trigger decorator can be added to any closed-end option or list element. In this usage, the checklist always triggers if the option is selected – a conditional statement is not accepted.

1. Which of these instruments have you considered learning to play? 
instruct: Select all that apply.
type: checkbox
1. Saxophone 
2. Bicycle { trigger checklist: attn } { trigger text: Selected 'bicycle' } { trigger id: Q1_ATTN }
3. Piano 
4. Guitar
5. Violin

The trigger text and trigger id decorators are optional. If not specified, the text will default to the option text. The ID will default to the pattern 'QX_Y' where 'QX' is the question ID, and 'Y' is the option ID. Unlike the trigger tag, shortened forms of trigger text and trigger id are not available with the trigger checklist decorator.

Examples

Attention check in a table

Use a checklist to create an attention check flag. In this example, an attention check is placed in a brand rating table. If the instruction to select 'Satisfied' at row 4 isn't followed by the respondent, the attn checklist is triggered.

define checklists 
attn. Attention checks

1. How satisfied are you with each of the following brands? 
type: radio table
1. Very Unsatisfied
2. Unsatisfied
3. Neutral
4. Satisfied
5. Very Satisfied
trigger: attn { condition: noneChecked($Q1R4,4) }
rows:
1. Brand 1
2. Brand 2
3. Brand 3
4. Select 'Satisfied' for this row.
5. Brand 5

Open end response length

In this example, a trigger is added to an open-end question in the survey to check for answers below a certain length. The short_oe checklist field can then be used to review the data later for low-quality open end responses.

define checklists
short_oe. Response fewer than 20 characters 

5. What could we have done differently to provide a better service? 
instruct: Please be as detailed as possible.
type: textbox 
trigger: short_oe { if length($Q5) < 20 }

Referencing checklists in survey logic

Checklists are similar to survey variables and may be referenced in survey logic. Unlike survey variables, there is no leading 'Q'. Instead, include a dollar sign ('$') followed directly by the checklist ID.

The following goto statement routes respondents to a page or group labeled 'bad' if its condition is 'true'. The condition anyChecked($attn) will evaluate as 'true' if one or more options have been triggered for the attn checklist.

goto: bad
condition: anyChecked($attn)

Checklists could also be used in logic for terminating respondents. Here is an example of a set term widget that will terminate respondents if 3 more or options have been triggered for the attn checklist.

setterm: attn_term 
text: Failed more than 2 attention checks
condition: countChecked($attn) > 2