Trials from a stimulus list

Expand a single trial-file row into one trial per item of an uploaded stimulus list, in a fresh random order each session.

When to use it

You have a bank of stimuli that all get the same trial treatment, and writing one row per image means duplicating every setting dozens of times and editing them all when anything changes. Pointing one row at an uploaded list keeps the stimulus set separate from the trial structure, so you can swap or grow the set without touching the trial file. If every item needs its own settings, such as a per-item correct key, extend the list file with extra columns instead (see the multi-column list file recipe); if you only have a handful of stimuli for a single trial, an inline stimList cell is simpler than an uploaded list.

Trial file

type	content	stimFormat	stim	listOptions	button1	button2
instructions	Photographs of places will appear one at a time. Click INDOORS or OUTDOORS for each.				Start
practice		list	scenes	sample 3	Indoors	Outdoors
instructions	End of practice. The main block starts now.				Continue
test		list	scenes	random	Indoors	Outdoors

How it works

The list itself is a CSV uploaded to the project’s Files tab as scenes.csv, one item per row under a stim header, each filename carrying its extension:

stim
kitchen.jpg
beach.jpg
forest.jpg
office.jpg
street.jpg
bedroom.jpg

stimFormat set to list switches a row into expansion mode: instead of holding a stimulus, stim names the uploaded list (without the .csv extension), and the row generates one trial per picked item. The trial type is derived from the extension of the first picked stimulus, so the .jpg items above produce image trials. Stick to .jpg, .jpeg, .png, .gif, .bmp, .pdf, .mp3 or .mp4 in list files; other extensions (.webp, .wav, .webm) are not recognised for type derivation and the trials silently render as word trials.

listOptions controls the picking, and the two blocks use it differently. sample 3 on the practice row draws 3 items at random, each at most once, so the warm-up is short and different every session. random on the test row shuffles the whole list, one trial per item. Left blank it would default to seq, file order. Because both rows point at the same list and expand independently, a practice item can reappear in the main block; use two separate list files if that matters.

The buttons carry the response: any non-empty button1 turns on button responding, the click records the button number (1 for Indoors, 2 for Outdoors) plus the visible label in the results, and with key absent the trials are simply unscored. With no presTime, each photograph stays on screen until the click.

Two expansion gotchas are worth designing around. First, on stimFormat: list rows every unused stim cell must be genuinely empty: any text in stim1 and up is read as the name of another list, and the file fails to expand when no such list exists. Second, sampling specs in the trialOrder column (1: sample ...) refuse list rows outright; sampling list items is listOptions’ job, as done here.

In the results, stim_actual records which file each generated trial actually showed, and rowNo uses the 3-2 notation (trial-file row, then item number) so you can trace every trial back to its list row.

Variations

• Cap the main block at a fixed length with sample 20 in listOptions; add max 2 to allow each item up to twice when the cap exceeds the list length.
• Present the full list twice with repeat 2, random in listOptions (note repeat is case-sensitive, Repeat silently becomes seq).
• Keep file order for a fixed narrative sequence by leaving listOptions empty (seq is the default).
• Draw from two lists at once by naming both in stim (scenes;faces) and giving each its own option group in listOptions (random; random); the lists merge per pick, one trial per position.