group by and group by options

The group by and group by options tags can be applied to the enable cheatsweep widget in order to define different groups and establish different rules for each group. The group by tag determines the grouping, whereas the group by options tag is used to set the CheatSweep parameters for each defined group.

group by

The group by tag accepts a variable for input, such as QPANEL or QCOUNTRY. When defined, CheatSweep will consider each option of the variable as unique "groups." The variable defined here must be single-select.

group by options

The group by options/group by options from tag will work with the group by tag to define parameters for each group. If used, group by must be defined.

Options for CheatSweep (CS) groups can be define by either rules attached to the tag or a variable.

• If identifying a variable, use group by options from. Rules must be listed alongside the option using decorators.
• If identifying through rules on the tag, use group by options  and define using a heredoc. Each line within the heredoc corresponds to the related option in the group by variable, e.g., rules prefaced with '1' correspond to group 1 in the group by variable.

Note that each option defined for group by options can include different tags or multiple tags.

Syntax

In the below code block, all capital letters represent integer values.

Defining options with heredoc

enable cheatsweep 
group by: panel_quota
group by options: <<END 
991. remove: 0%
256. remove: 5%
301. threshold: 80
END
startsweep: 100
repeatsweep: n
allow_dup: n
term dup: n

Defining options in separate variable

enable cheatsweep
group by: QVAR
group by options from: QVAR

VAR.
type: radio
invisible: y
991. Client list {{remove: 0%}}
256. Panel 2     {{remove: 5%}} {{startsweep: 100}} {{repeat sweep: n}} 
301. Panel 3     {{threshold: 80}} {{startsweep: 50}} {{repeat sweep: n}} 

Tags

The following tags can be used with group by options, either as a semicolon-separated list of tags or as element decorators.

Note that rules may be defined at the enable cheatsweep widget with other rules defined at the group-level. Group-level rules override widget-level rules. If no rules are set at either the group or widget level, system CheatSweep defaults will apply.

Examples

Basic

In the example below, CheatSweep will treat each country (defined in QCOUNTRY) as a unique scoring group. By default, CheatSweep starts sweeping when N=50, so whenever a group option reaches N=50, CheatSweep will begin to sweep at a threshold of 80.

enable cheatsweep
allow dup: n
group by: QCOUNTRY
threshold: 80

COUNTRY.
type: radio
invisible: y
cvalue: url_param('c')
1. uk 
2. br 
3. fr 

Defining group by rules with enable cheatsweep

When the rules for groups are defined within the group by options tag, a heredoc is required. If a particular grouping does not include a CheatSweep tag that is also defined as part of enable cheatsweep - or is a default setting for CheatSweep - then the default/widget level rules will apply to that group. In the example below, since group 2 does not include a start sweep tag but enable cheatsweep does, CheatSweep will begin sweeping group 2's respondent data after the 10th respondent.

enable cheatsweep
start sweep: 10
group by: QSAMPLE
group by options: <<END
1. remove: 5%; start sweep: 100
2. remove: 8%; repeat sweep: n; disable rules: 51, 12
3. threshold: 85; start sweep: 50
END

Defining group by rules with separate variable

In the following example, QCOUNTRY is used to define the options and rules. Since each country/option in QCOUNTRY uses option data to define their remove, threshold, start sweep, and other values/rates, instead of using group by options with enable cheatsweep, use the group by options from tag.

enable cheatsweep
group by: QCOUNTRY
group by options from: QCOUNTRY

COUNTRY.
type: radio
invisible: y
cvalue: url_param('c')
1. uk {{remove: 5%}} {{start sweep: 30}}
2. br {{remove: 8%}} {{repeatsweep: n}} {{disable rules: 51, 12}}
3. fr {{threshold: 85}} {{start sweep: 100}}

Option level vs. widget level

When the same tag is applied both at the widget level and the option level, the option level rules will prevail. In the example below, the start sweep rates for the options defined by group by options would take precedent over the more globally defined level of start sweep: 30.  Any tags applied to enable cheatsweep that are not included with the options will be applied to those options.

Since the third option does not include a start sweep tag, it will inherit the start sweep rate defined outside of the heredoc, beginning at N=30. Options 1 and 2 will also inherit threshold: 80 since neither option includes a threshold tag, and allow dup: y will be applied to all options.

enable cheatsweep
start sweep: 30
allow dup: y
threshold: 80
group by: QCOUNTRY
group by options: <<END
1. remove: 5%; start sweep: 25
2. remove: 15%; start sweep: 100
3. threshold: 70;
END 

With disable rules

In this case, with no start sweep tag included, CheatSweep will default to starting at N=50 for all options defined in QCOUNTRY. Since allow dup and disable rules are defined outside of group by options, their definitions will apply to all options included in QCOUNTRY.

enable cheatsweep 
allow dup: y
group by: QCOUNTRY
group by options: <<END
1. remove: 5%
2. remove: 15%
3. threshold: 70
END 
disable rules: 51,55,61,105