selectby 'steps' (r9)

Starting in r9.4, you can use the selectby tag with the steps process on a quota variable to specify a series of programming steps for the software to select multiple options. This is often called a "step quota."

This new selection method was designed specifically for quotas with multiple steps, where each step may involve different selection methods and conditions to pre-select eligible quota options in a tiered approach before making the final selection.

Steps are evaluated in the order they are presented. Each step can include decorators that apply to unique selectby processes, maxgroups, conditions, and inclusion/exclusion filters. The variable must use type: quotas.

Syntax

Step quota

To program a step quota, apply selectby: steps (alias step or stepwise), to the parent quota variable using type: quotas. Reference your option set with optsfrom. Apply the maxgroups tag to define the maximum number of total options that can be selected for the quota. Add the steps tag, and list each step in the order you want them evaluated. Lastly, affix the relevant logic to each step with an "if statement" (condition).

You can optionally apply the steps chapter tag  (alias step chapter) to change the step question's location in the reporting field tree. By default, the step variables are located in the Survey fields chapter along with the step quota variable.

BRANDS. 2 Brands for deep dive
type: quotas
selectby: steps
optsfrom: BRANDS
maxgroups: 2
steps chapter: appendix
steps:
1. Step 1 {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Step 2 {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: counts}
3. Step 3 {if anyChecked($Q8,[id])}  {maxgroups: 2} {selectby: counts}
4. Step 4 {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: counts}

Note, this example is simplified for illustrative purposes. The BRANDS list and all referenced questions would need to also exist in the survey code to make this example work correctly.

Steps

The individual steps have specific requirements. Each step must have the following decorators: a condition, maxgroups, and selectby. If needed, you can filter the option set with inclusion/exclusion and option data syntax before applying a condition.

steps:
1. Step 1 {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Step 2 {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: weight}
3. Step 3 {if anyChecked($Q8,[id])}  {maxgroups: 1} {selectby: condition}
4. Step 4 {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: counts}

Understanding step quota behaviors

There are several step quota behaviors that are helpful to understand.

1. An item selected in an earlier step cannot be chosen in a later step. If selected in Step 1, it becomes ineligible for Step 2, or beyond.
2. Step quotas keep a running count of selected items. A later step cannot exceed the remaining number needed, regardless of the maxgroups allowance.
3. The selectby: steps process cannot be combined with other selection methods. For example, selectby: steps, counts is not allowed.
4. Each step establishes its own selectby process.
   • A step cannot use selectby: steps in its own selection process.
   • A step's selection process can be tiered, such as selectby: counts, weight.
   • Currently, selectby: percentage and selectby: balance are not supported.
5. Steps are evaluated in the order they are listed, not by option ID. A set of steps labeled, "1,2,4,5,3" is acceptable.
6. Non-numeric labels like '2A' are also acceptable.

Additionally, step quotas automatically create a separate variable in the reporting field tree to store the data at each step. These variables are named QNAME_[id], where "NAME" is your quota label and [id] is the step's ID.

Examples

There are endless ways to create selection logic and combine methods for selection. Below are a few examples to start with. Given the large amount of code used in a step quota process, we will refer to the same BRANDS list and survey questions for each example. 

We encourage you to apply these to your own test area and adapt them to your needs.

Basic

In this first example, we establish the BRANDS list and survey questions referred to in the step quota QBRANDS. The maxgroups decorator restricts steps 1 and 3 to selecting only one brand, while steps 2 and 4 can select up to two brands. Best practice is to use selectby: condition or selectby: random when only one selection is possible. Therefore, steps 1 and 3 utilize the condition method, while selectby: counts is used for steps 2 and 4. 

set list: BRANDS
1. brand 1 
2. brand 2 
3. brand 3 
4. brand 4 

7. Select random brands. 
type: checkbox
optsfrom: BRANDS

8. Select competitors. 
type: checkbox
optsfrom: BRANDS

9. Select recent brands. 
type: checkbox
optsfrom: BRANDS

10. Select a primary brand. 
type: radio
optsfrom: BRANDS

BRANDS. 2 Brands for deep dive
type: quotas
selectby: steps
optsfrom: BRANDS
maxgroups: 2
steps:
1. Primary brand {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Recent brand  {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: counts}
3. Purchased competitors {if anyChecked($Q8,[id])} {maxgroups: 1} {selectby: condition}
4. Other brands  {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: counts}

Chapters

In this second example, we keep everything the same, but we add the steps chapter and chapter tags to the quota.

Since this variable uses type: quotas, the step quota and the derived step variables are stored in the main Survey fields chapter. By applying the steps chapter tag, you can move the step variables to a new chapter (for example, the Appendix chapter). However, QBRANDS would remain in the main survey data chapter. To move the QBRANDS quota variable as well, you apply the chapter tag. Using the example below, we are moving QBRANDS to the Appendix, and the four derived step variables to the Logic chapter. 

BRANDS. 2 Brands for deep dive
type: quotas
selectby: steps
optsfrom: BRANDS
maxgroups: 2
chapter: appendix
steps chapter: logic
steps:
1. Primary brand {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Recent brand  {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: counts}
3. Purchased competitors {if anyChecked($Q8,[id])} {maxgroups: 1} {selectby: condition}
4. Other brands  {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: counts}

Weights

We continue to build on the previous examples. The next example changes the selection method, and step 4 now employs a tiered approach, selectby: weight, counts. Step 4 selects the brand with the highest weight first, and in the event of a tie, selects the brand with least counts.

Since selectby: weight is used, a weight must be present on the brands from the BRANDS list somewhere in the survey source. There are multiple ways to do this. For this example, we simply add weight decorators to the BRANDS list.

Updated list with weights

set list: BRANDS
1. brand 1 {weight: 100}
2. brand 2 {weight: 10}
3. brand 3 {weight: 10}
4. brand 4 {weight: 1}

Updated quota

BRANDS. 2 Brands for deep dive
type: quotas
selectby: steps
optsfrom: BRANDS
maxgroups: 2
chapter: appendix
steps chapter: logic
steps:
1. Primary brand {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Recent brand  {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: counts}
3. Purchased competitors {if anyChecked($Q8,[id])} {maxgroups: 1} {selectby: condition}
4. Other brands  {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: weight, counts}

With inclusion and option data

For this final example, we apply an additional filter on step 3. Step 3 first filters the brands by looking at the option data included for 'target' for each item. If 'target' has a value of '1', the brand is eligible to be checked by the condition. Then, like usual, if the brand meets the condition, it can be selected.

Option data can be added to the BRANDS list with option data decorators or via a survey sheet. In this example, we simply add this to the BRANDS list. We place double curly brackets around the label and value inline on each item. 

Updated list with option data 'target'

set list: BRANDS
1. brand 1 {weight: 100}  {{target: 0}}
2. brand 2 {weight: 10}   {{target: 1}}
3. brand 3 {weight: 10}   {{target: 0}}
4. brand 4 {weight: 1}    {{target: 0}}

Updated quota

BRANDS. 2 Brands for deep dive
type: quotas
selectby: steps
optsfrom: BRANDS
maxgroups: 2
steps:
1. Primary brand {if anyChecked($Q10,[id])} {maxgroups: 1} {selectby: condition}
2. Recent brand  {if anyChecked($Q9,[id])}  {maxgroups: 2} {selectby: counts}
3. Purchased competitors [if [target]==1] {if anyChecked($Q8,[id])} {maxgroups: 1} {selectby: condition}
4. Other brands  {if anyChecked($Q7,[id])}  {maxgroups: 2} {selectby: weight, counts}