Looping

The looping feature gives users the ability to “loop through” a series of questions of their respondents, while only having to create that set of questions one time.  The loop object is actually just a specialized form of a collection.  You add the loop object where you want in the survey, and then add the questions to be looped through into the loop collection.  Finally, you edit the loop collection to tell Illume how it should loop through the items contained within.

Create a loop object in a survey by:

1. Click the Add a loop icon         or from the Add menu select “Loop”

When this object is opened, a tabbed editor is available to the user for specification of the Loop Object.

The General Tab

The General tab is identical to the General tab when defining a Collection. Users provide a unique name for the Loop, and specify whether the Loop should be made as a section in the data dictionary, whether the questions in the Loop should be randomized, and whether the Loop as a whole should be anchored if it is part of a parent collection that is randomized.

Loop Iterations Tab

This tab is used to define the type of loop.  There are three primary types of Loops:

• Iterate until done:  With this type of looping, the respondent continues to iterate through the defined Illume questions that are part of the Loop either until the respondent decides no more loops need to occur, or until a maximum number of loops has been reached, as defined on the Loop Iteration Guides tab.  This maximum can be hard coded, or can be based on the response to a question.  For example, Q1 in the survey might ask, “How many people are in your family?”  This value can be piped into the Maximum Allowed field to limit the number of Loops to the number entered into the Q1 field.
• Iterate for Each Entity in a Previous Loop:  This type of loop allows the respondent to loop through a series of questions in relation to a prior “parent” loop.  For example, a “parent” loop may ask the respondent to identify the Name and Gender of each member of their family (we will call this the “Members loop”.  Then, for each member of the family, this loop may ask the respondent to answer several questions regarding the medications taken by each member of that family, or for a subset of the members of that family. Selecting “Iterate for All entities in a previous loop” causes the respondent to be looped through the questions defined in the loop for all family members defined in the Members loop.  Alternatively, the user may specify that only certain family members are asked the questions in the medication loop.  In this scenario, the users selects “Only iterate if…” and defines the conditions that specify for which members should the medication questions be asked (e.g. Only iterate if GENDER=male).
• Iterate over a pre-defined set of response options: This type of loop allows the respondent to loop through a series of questions based on a predefined set of responses.    The Import from Question feature can be used in conjunction with this scenario, such that the scale from another question can be automatically imported, with show-if logic automatically applied to each option in the scale.  For example, respondents might be asked which websites they’ve visited, and select those websites in a check-all-that-apply question.  You may then want to ask a series of 5 questions about each of the selected websites.  This type of loop would allow you to define those 5 questions, and have respondents loop through those but only X number of times, based on how many websites were checked in the prior question.

NOTE: The Loop Options, Loop Summary Columns and Loop Summary Options tabs are described in the Loop Summary Table section of Help.

Show-If Tab

Set Show-if Logic for the entire Loop Object, which is the conditions under which the loop should run.  For example, you may ask respondents “how many members are in your family” (data dictionary name = MEMBERS), and then loop through questions about each family member.  You would want to specify show-if logic on the loop containing the questions about each family member to show-if  MEMBERS>0.

A Loop Summary Table is a visual representation of the data contained within a loop that is presented to the respondent during the run-time of the survey. Loop Summary Tables allow a participant to Add, Review, Edit or Delete the information provided in an iteration of the looped variables.  This table is optional – it is selected by default, however this option can simply be un-checked if it is not desired.  In the absence of this table, respondents will simply loop through the items contained within the loop, page after page.  To change entries in a prior loop, respondents would need to use the Previous button to page back to that iteration.  When the table is used, respondents can easily “jump” back to a particular iteration by simply clicking the Edit icon.

Example of a Loop Summary Table

A Loop Summary Table is configured in the Loop Options Tab of the Loop Object.

Loop Options Tab

The check box to enable the Loop Summary Table is checked by default.

If this is unchecked only the Loop Iteration Guide will be displayed on the Loop Options Tab, as in the screenshot below.

Only the Required Number of Iterations can be set in this field.  When the survey is taken it will just loop for as many iterations as entered in that field but the respondent will not know why or have any way to delete, or edit a specific iteration without using the Previous button.

When “Use a loop summary table for loop iteration control” is checked, the user may then specify a Loop Summary Table Prompt which will appear above the table, as shown below.

NOTE: In the example above piping is used in the prompt to show the number of members provided in an earlier variable “RESIDENCECOUNT”.

Loop Iteration Guides

The loop iteration guides give users the ability to define the Minimum and Maximum number of required iterations of the loop.  Typically these will be defined by the response to a previous question.  In the example above, a previous question in the survey asked “How many members are in your household” (data dictionary name RESIDENCECOUNT).  These loop iteration guides specify that the respondent should be asked the loop question no fewer and no more than the number of members in their household.

If the number of iterations is unknown or should be open-ended (i.e. the respondent can continue looping as long as they desire), then only supply a minimum number, for instance “1”.

The Error Message field is to supply the respondent with a custom error message regarding the number of iterations.

NOTE: The Minimum and Maximum setting will not be available in a “Iterate for Each Entity in a Previous Loop” loop type.

Loop Summary Columns Tab

The Loop Summary Columns Tab is where the Column Types, Headers and Text can be configured for the loop summary table.

Summary Column Types

There are four types of Columns that can be displayed in a Summary Table.

• Value of a Loop Or Survey Variable – Used to display the variables included within the loop. In the screenshot above, residence member name, type, gender and relationship are all survey variables contained within the loop.  Those four are added to the table so that the respondent can see what was entered into each of those survey variables.
• The Label or Sequence Number of a Loop Iteration – Used when Iterating over a predefined set of responses.  For example, in this type of loop the respondent may be asked to select which websites they’ve visited from a check-all-that-apply list of websites.  If the respondent selects 3 websites, he will iterate through the loop 3 times, and each row of the table will be labeled with 1, 2, 3, as this is the “sequence number of the loop iteration”.
• An Answered/Unanswered indicator for a Loop Iteration – Used in Iterate for Each Entity in a Previous Loop or an Iterate over a pre-defined set of response options Loop types.  This indicator shows whether the questions within the loop for a particular iteration have been received.
• Loop Iteration Buttons – The Edit, Delete or Respond button for each loop

Once a table column has been defined, it can be dragged-and-dropped within the editor window on the Loop Summary Columns tab to control the order of columns in the table.  For example, you may want to drag and drop “Loop Iteration Buttons” to be the first or last column int he table.

Loop Summary Options Tab

The Loop Summary Options Tab allows the Survey Designer to customize the Iteration Buttons  and Summary Indicators for a specific Loop Summary Table.  By default these Options are set at a Survey level under Survey/Preferences.  If those default preferences are satisfactory, it is not necessary to edit this tab.

Example of an”Iterate until done” loop Summary Table

With this type of looping, the respondent continues to iterate through the defined Illume questions that are part of the Loop either until the respondent decides no more loops need to occur, or until a maximum number of Loops has been reached, as defined on the Loop Iteration Guides tab.  This maximum can be hard coded, or can be based on the response to a question.  For example, Q1 in the survey may ask, “How many people are in your family?”  This value can be piped into the Maximum Allowed field to limit the number of Loops to the number entered into the Q1 field.

Creating an Open-Ended Loop

Steps:

1. Create the Loop Object from the Add menu/Loop
2. Enter the appropriate information in the General Tab
3. Select Iterate until done in the Loop Iteration Tab

4. In the Loop Options tab, enter the Table Prompt, and the appropriate values for the Minimum and/or Maximum number of loops.  If no Summary Table is desired, uncheck the Summary Table check box and enter only the Required Number of Iterations.

NOTE: If no Minimum or Maximum is set the Loop is considered not required

5. In the Loop Summary Columns Tab, add the desired columns for the Summary Table.  The table does not need to include all of the variables within the loop.
6. For the Loop Summary Options Tab, by default the buttons and indicators are set in preferences. To create custom button text, or use a different button graphic, uncheck Use Survey Preferences.
7. To create custom indicators of Answered/Unanswered Loops uncheck the Use Survey Preferences.
8. Set the appropriate Show-If logic for the Loop Object if desired and Click OK to save.

Example of an “Iterate for all entities in a previous loop” Loop Summary Table

This type of loop allows the respondent to Loop through a series of questions in relation to a prior “parent” loop.  For example, a “parent” loop may ask the respondent to identify the Name and Gender of each member of their family (we’ll refer to this as the “Members loop”).  Then, for each member of the family, this follow-up loop may ask the respondent to answer several questions regarding the medications taken by each member of that family, or for a subset of the members of that family.

Selecting “Iterate for All entities in a previous loop” causes the respondent to be looped through the questions defined in the  loop for all family members defined in the Members loop.  Alternatively, the user may specify that only certain family members are asked the questions in the medication loop.  In this scenario, the users selects “Only iterate if…” and defines the conditions that specify for which members should the medication questions be asked (e.g. Only iterate if GENDER=male).

Note: This type of loop cannot have other loops nested within it.

Creating an “Iterate for all entities in a previous loop” object

Steps:

1. Create the Loop Object from the Add/Loop menu
2. Enter the appropriate information in the General Tab
3. Select Iterate for All entities in a previous loop in the Loop Iteration Tab
4. Under Loop Iteration Follow-Up Configuration, use the poplist to select the previous loop.  In the example below, the previous loop is called “RESIDENCEMEMBERS”.

5. The default will be to iterate through all of the entries in the previous loop.  If Logic should apply then select Only Iterate if… and click the Edit button to add the logic.  In the example above, this loop will only iterate for the Male members identified in the RESIDENCEMEMBERS loop
6. On the Loop Options tab, enter the Table Prompt.  If no Summary Table is desired, uncheck the Summary Table check box.
7. Check the box in Loop Iterations Guide to Require a follow-up for each iteration in the original loop.  This will ensure that looping will continue until questions are asked about each male member.
8. Enter a Custom Error Message if desired.

9. In the Loop Summary Columns Tab select the appropriate Columns to include in the Summary Table.

NOTE: The Answered/Unanswered Indicator column can be used to show which of the Follow-up Loops have been completed

10. For the Loop Summary Options Tab, by default the buttons and indicators are set in preferences. To create custom button text, or use a different button graphic, uncheck Use Survey Preferences.
11. To create custom indicators of Answered/Unanswered Loops uncheck the Use Survey Preferences.
12. Set the appropriate Show-If logic for the Loop Object if desired and Click OK to save.

Example of an “Iterate over a pre-defined set of response options” Loop Summary Table

This type of loop allows the respondent to loop through a series of questions based on a predefined set of responses.    The Import from Question feature can be used in conjunction with this scenario, such that the scale from another question can be automatically imported, with show-if logic automatically applied to each option in the scale.

Creating a Pre-Defined Loop

Steps:

1. Create the variables that will be used to define the Loop, For Example a Select One Question that provides the list of responses to use for each Loop Iteration.
2. Create the Loop Object and click OK
3. Using the right pane select the Object to add the Pre-defined Question
4. Go back to the Loop Object
5. Enter the appropriate information in the General Tab
6. Select Iterate over a pre-defined set of response options in the Loop Iterations Tab
7. Under Add/Edit Loop Iteration Response Option, you may enter each response option one by one from the prior question

Alternatively, or you may use the Import from Question option to import the response options from the previous question.  This can be opened by clicking Import and selecting “Import from Question” from the poplist.  When Import from Question is utilized, you may check the box to “add show to only show imported responses if answered for selected question”, meaning that the loop will only occur if the option was selected in the prior question.

8. In the Loop Options tab, enter the Table Prompt, and the appropriate values for the Minimum and/or Maximum number of loops.  If no Summary Table is desired, uncheck the Summary Table check box.
9. In the Loop Summary Columns Tab select the appropriate Columns to include in the Summary Table.

For this table there are two additional types of Columns:

• Iteration Label – The label or sequence number of a loop iteration – This will reference the Loop Iteration Response Options created earlier.
• Survey Data – The value of the loop or survey variable – This will reference the responses created in the Variable inside the Loop in step 3.

10. For the Loop Summary Options Tab, by default the buttons and indicators are set in preferences. To create custom button text, or use a different button graphic, uncheck Use Survey Preferences.
11. To create custom indicators of Answered/Unanswered Loops uncheck the Use Survey Preferences.
12. Set the appropriate Show-If logic for the Loop Object if desired and Click OK to save.

Nesting loop objects involves placing of a Loop Object within another Loop Object.  There is no limit to the level of nesting.

A best practice in nesting loops is to keep the same iteration type throughout the loops, and if there is a Summary Table in the Original Loop, to use Summary Tables in all nested loops.

Example of an Iterate Until Done Loop nested in another Iterate Until Done Loop:

Explanation:

• The variable RESIDENCECOUNT asks for the number of people in the residence
• The RESIDENCEMEMBERS loop uses the number of people in the residence as the minimum and maximum for the number of loops

• Within the Loop RESIDENCEMEMBERS there is a nested loop called PRESCRIPTIONS.

• The PRESCRIPTION loop collects the name of each prescription drug based on the number of drugs provided in a question called RESMEM_DRUGS
• There is Show-If logic on the PRESCRIPTION loop to only show if the RESMEM_DRUGS is greater than 0.

• The PRESCRIPTION loop uses the RESMEM_DRUGS variable to set the minimum and maximum for the number of nested loops.

• Each loop uses a Summary Table to display the information collected.