subjectGroup

Experiments Surveys & forms

subjectGroup implements between-subjects designs. Each session, the participant is assigned one subgroup per group label (randomly by default, or evenly across participants when the project’s even-allocation setting is on) and then sees only the trials tagged with a picked subgroup plus all untagged trials. Use it to give different participants different trial subsets (conditions, counterbalancing lists).

Syntax

Put a subgroup number in the subjectGroup cell of every trial that belongs to that subgroup, for example 1 on the trials of the first list and 2 on the trials of the second, and leave the cell empty on trials everyone should see. Each participant is allocated one subgroup and runs only its trials plus the untagged ones.

To vary more than one thing at a time, give the group a name and write <label>:<number>, for example taskOrder:1 and colour:2. Each name is a factor of its own: exactly one subgroup is allocated per name, so a file mixing colour:1/colour:2 with size:1/size:2 gives every participant one colour AND one size.

The values a cell accepts:

              <- empty: trial belongs to no group; shown to every participant
0             <- same as an empty cell
<int>         <- subgroup <int> of the current group name
<label>:<int> <- subgroup <int> of the named group <label>

The number after the colon must be digits. A bare word such as A is not a group name: it leaves the trial ungrouped and shown to everyone (see Tips & gotchas).

Options

Value	Read as	Effect
empty cell	no group	Trial shown to everyone
0	no group	Same as an empty cell
positive integer N (e.g. 1, 2)	subgroup N of the current group name	Trial shown only to participants allocated subgroup N of that group
label:N (e.g. taskOrder:2)	group label, subgroup N	Trial shown only to participants allocated label:N
label:0	group label, subgroup 0	Subgroup 0 is never allocated, so the trial is shown to everyone
non-numeric bare string (e.g. A, groupB)	no group, under the current group name	Trial shown to everyone. Letter group names WITHOUT the label:N syntax do not create selectable subgroups; see Tips & gotchas for the all-zero-group edge case
decimal like 2.5	truncated to 2	Behaves as subgroup 2

Defaults & missing values

If the column is absent, or every cell is empty or 0, there are no groups: nothing is allocated and every participant runs every trial.

Once groups do exist, rows left empty (or set to 0) are kept for every participant, whichever subgroup they were allocated. Use them for the parts of the experiment everyone shares, such as instructions, practice and debrief screens.

Works with

• random and randomBlock: trials are shuffled before the group is allocated, so shuffling and group filtering combine cleanly.
• randomPick: the pick happens after group filtering, so it draws only from the trials this participant’s subgroup is entitled to.
• break: a break defined on a row tagged with a subgroup the participant was not allocated is dropped along with that row’s trials, so each group only gets its own breaks.
• Results: the allocated subgroups are saved in a subjectGroup results column, space-separated when several groups are in play (for example taskOrder:1 colour:2). Per-trial values are recorded too, and cells set to 0 come out blank in exported results.
• Recruitment reporting: participation events record the allocated subgroup, so you can see how many participants each group received.
• Scripts you add with script can read the allocated subgroups from window.testableSDK.allocatedSubjectGroups.

Tip

Turn on the project’s even-allocation setting to balance groups across participants: each new session takes the subgroup with the fewest participants so far, instead of drawing one at random.

Examples

Simple two-list counterbalancing (no group name):

type	subjectGroup	target
instructions		Welcome
test	1	listA_1.png
test	1	listA_2.png
test	2	listB_1.png
test	2	listB_2.png

Each participant is randomly assigned subgroup 1 or 2 and sees the welcome screen plus only that list. Results record subjectGroup as 1 or 2.

Two crossed factors with named groups:

type	subjectGroup	target
test	taskOrder:1	firstTaskA.png
test	taskOrder:2	firstTaskB.png
test	colour:1	red.png
test	colour:2	blue.png
test	0	sharedTrial.png

One taskOrder subgroup and one colour subgroup are picked independently; sharedTrial runs for everyone. Saved info value looks like taskOrder:1 colour:2.

Group-specific break:

type	subjectGroup	break
break	2	trials:20

Only participants allocated subgroup 2 get this break; for everyone else it is filtered out.

Tips & gotchas

Caution

Do not mix plain numbers and label:N values in the same file. A plain number belongs to the group name last seen before it, and because groups are read in the order the participant sees the trials, shuffling can change which name a plain number ends up under. Use plain numbers everywhere, or names everywhere.

• Bare words such as A or groupB are silently treated as “no group”, so those trials go to every participant and you get no warning. Use 1, 2 or taskOrder:1 instead.
• Everything before the last colon is the group name, so a:b:2 means subgroup 2 of a group called a:b.
• A value like 2:1 is read as the plain number 2, not as group 2 subgroup 1.
• Break rows follow the same rules as trial rows, so a break tagged 2.5 behaves as subgroup 2.
• A group whose cells are all 0 (or all bare words) has no subgroup to allocate. Every trial still runs, but the saved subjectGroup value and the participation records for it come out as undefined. Give a group at least two real subgroups, or leave its cells empty.
• Under even allocation the per-trial subjectGroup values in saved results keep a nsg: prefix (for example nsg:2 instead of 2) when you use plain numbers. Account for that when parsing results.
• Even allocation counts a participant as soon as their session starts, and only releases the slot if they close the tab normally. A browser crash can therefore leave a subgroup looking fuller than it is.
• Previews are allocated a group like real sessions, and show only that group’s trials, but never count towards even allocation.

Common combinations

subjectGroup appears in these worked recipes:

• Between-subject conditions: Give each participant one of two stimulus sets, while shared screens run for everyone.
• Factorial vignette study: Show each participant one version of a scenario from a factorial design, then have everyone rate it on the same questions.
• Counterbalanced key mapping: Give half the participants one response-key mapping and half the reversed mapping, with matching instructions for each.