Generating Trials from Stimulus Lists

Experiments

Instead of writing one trial row per stimulus, you can point a single row at an uploaded stimulus list. Testable expands that row into one trial per list item, which keeps your stimulus content separate from the trial structure and makes it easy to randomise, sample, and reuse the same set across experiments.

Setting up a list-driven trial

1. Upload your list file in the Files tab (e.g. stimuli.csv).
2. In your trial file, set stim to the list name without the extension: stim = stimuli.
3. Set stimFormat to list.

At runtime Testable reads the file and generates one trial per item:

type,stimFormat,stim,listOptions
test,list,sounds,random

The trial type (image, audio, video, word) is derived from the file extension of the first stimulus picked from the list.

Note

This is different from the stimList column, which holds an inline, semicolon-separated set of stimuli for a single trial. stimList never references named lists and never expands into multiple trials.

Controlling trial order with listOptions

The listOptions column controls how items are drawn from the list:

Value	Behaviour
seq	Default. Items are drawn sequentially, in file order
random	Items are shuffled
sample X	Randomly sample X items from the list
repeat X	Repeat the entire list X times (use at least 2 to present the list twice)
group X	Divide the list into consecutive groups of X rows; further operations act on the groups as units
sample X min Y	Sample X items, guaranteeing at least Y full copies of the list
sample X max Y	Sample X items, with each unique item appearing at most Y times

By default sample picks each item at most once; raise max to allow repeats, or use min to guarantee whole copies of the list.

Caution

repeat is case sensitive: Repeat 3 is silently treated as seq. The other tokens accept capitals.

Combining listOptions

Separate multiple options with a comma. Operations are applied in order, so the sequence matters:

listOptions	Behaviour
repeat 2, random	Duplicate the list, then randomise all items
random, repeat 2	Randomise the list, then repeat that randomised order
group 2, random	Divide into groups of 2, then randomise the groups (pairs stay adjacent and internally ordered)
sample 20, repeat 3	Randomly pick 20 items, then repeat that selection 3 times

Note

Combinations must be sensible (combining seq and random has no meaning, and group applied after the last reordering token has no effect). The editor catches most invalid combinations, but double-check your inputs.

Combining multiple lists

Multiple lists in one stim column, separated with semicolons:

stim	stimFormat
list1; list2	list

Lists in separate stim columns:

stim1	stim2	stimFormat
list1	list2	list

Both forms behave the same: the stim columns are pooled, and the lists at each position are merged per pick.

Tip

You can combine lists with different lengths. The number of generated trials follows the longest list; once a shorter list runs out of items, the remaining trials use only the items from the longer list.

Caution

Your remaining trial setup must always match the final number of stimuli per trial. If your lists yield 3 stimuli per trial, defining 4 presentation times will produce an error.

Caution

On stimFormat = list rows, leave unused stim cells genuinely empty. Anything you type in them is read as the name of a stimulus list, and the trial file fails to expand when no list by that name exists.

Specifying listOptions per list

When using multiple lists, separate the options for each list with semicolons in listOptions, in the same order as the list names:

stim	listOptions	Behaviour
list1	random	list1 is randomised
list1; list2	random	Both lists are independently randomised
list1; list2	random; seq	list1 is randomised, list2 stays sequential
list1; list2	random, repeat 2; repeat 2, random	list1 is randomised then repeated; list2 is repeated then randomised

A list with no options of its own inherits the previous list’s options (that is why a single random shuffles both lists above). An explicitly empty group (;;) resets to seq.

Caution

Sampling specs in the trialOrder column (N: sample ... and N: groupSample ...) cannot be applied to stimFormat = list rows; the trial file is rejected with an error. Sample list items with listOptions instead.

Results from list-driven trials

When results are saved from experiments using stimulus lists:

• stim_actual stores the actual stimulus filenames drawn from the list.
• rowNo uses a special notation to track list items and repetitions:

rowNo	Meaning
3-3	Generated from trial file row 3; 3rd item from the first list was shown
5-2-4	Generated from trial file row 5; 2nd item from list 1 and 4th from list 2
5-2-4_2	Same trial shown a second time (e.g. via repeat)

Multi-column list files

Each row in the list CSV represents one trial; column headers map directly to trial file columns. For example:

stim,stim2,condition
images/cat.jpg,images/dog.jpg,control
images/bird.jpg,images/fish.jpg,experimental

This generates two trials, each with two stimuli and a condition label. The column headers must exactly match the column names used in your trial file.

Note

Values from the CSV overwrite any values set in the trial file row for the same column. For example, if the trial file row has presTime = 2000 but the CSV includes a presTime column, the CSV values will be used instead.

Next steps

• Generating Questions from Lists: use lists to generate survey questions
• Define and Position Stimuli: how stimFormat and the stim columns define stimuli
• Randomisation: randomise trials that are not list-driven