stim

Experiments Surveys & forms On form rows an inline stimulus list displays next to the question; list expansion and HTML apps are experiment-only.

stim is a multi-role column; its meaning depends on stimFormat:

1. Inline stimulus list (media/word trials): identical to stimList, used only when stimList is empty. One cell of ;-separated stimuli replaces stim1..stimN.
2. Stimulus-list name(s) (stimFormat: list trials): names one or more uploaded stimulus lists to draw rows from; such a trial row expands into one generated trial per picked list row, provided the file’s stimFormat column is placed and spelled so that expansion runs at all (see Tips & gotchas). The bare stim header counts as a stim column alongside stim1, stim2 and the rest.
3. App/HTML reference (stimFormat: html trials): stim is preferred over stim1 and is resolved to a predefined app name (cubefield, langfuse), a URL, or a relative .html path.

Separately, each row of an uploaded stimulus list file has a stim field, and those values are what a list’s name gives you when a script column reads or extends the list.

Syntax

Write the trial’s stimuli in one cell, separated by semicolons: cat;dog;bird. Semicolon is the only separator.

On stimFormat: list rows the cell holds stimulus-list names instead, again separated by semicolons, and the picking options for each list come from listOptions.

On stimFormat: html rows the cell holds one value: a predefined app name, a URL, or the path of an HTML file you uploaded to the project’s stimuli.

Options

Context (stimFormat)	Accepted values	Behavior
media extension or word	;-separated stimuli, or empty	Same handling as stimList, but only consulted when stimList is empty
list	;-separated stimulus-list names	Trial expands into generated rows; picked rows’ stim values become stim_actual
html	predefined app name, http(s)://... URL, or relative path (auto-suffixed .html)	Loaded as the trial’s HTML app
anything else	free text	Ignored by stimulus display

Defaults & missing values

Leave the cell empty, or leave the column out, and the trial has no inline stimulus list: it falls back to stim1..stimN.

On stimFormat: html rows an empty stim cell falls through to stim1.

Caution

On stimFormat: list rows, leave unused stim cells genuinely empty. Anything you write there is read as the name of a stimulus list, and a name that matches no uploaded list stops the trial file from building.

Works with

• stimList always wins over stim when both have values.
• stimFormat selects the role (see above) and supplies the appended extension in role 1.
• listOptions configures per-list picking in role 2.
• stim_actual reports the stimulus each generated trial got in role 2. Any extra columns in the stimulus list file are merged into the generated trial row as well, overriding the values on the base row.
• A long stim cell widens how many numbered stim slots the file offers, the same way stimList does.
• In a script column, a stimulus list’s name gives you an array of its rows’ stim values.
• For stimFormat: html (role 3), the in-app API for saving responses and reading trial data is documented in the “Custom HTML trials” section of the stimFormat page.

Examples

Inline list fallback (equivalent to stimList):

type	stimFormat	stim	keyboard	key
test	word	cat;dog;bird	c d	c

Stimulus-list trial: draw 5 random rows from list “faces”, one generated trial per row:

type	stimFormat	stim	listOptions	presTime	keyboard	key
test	list	faces	sample 5	1000	f j	f

HTML app trial:

type	stimFormat	stim
test	html	cubefield

Tips & gotchas

Caution

Role 2 only happens when list expansion is switched on for the whole file, and two things about the stimFormat column silently switch it off: stimFormat being the file’s first column, or its header spelled in any other letter case (stimformat, StimFormat). Neither shows an error. Nothing expands, no stim_actual is recorded, and a stim cell naming a list is used as an ordinary stimulus instead, so the participant is shown a stimulus literally called faces rather than an item drawn from the list faces. The stimFormat page has the details and the fix.

• In role 2 it makes no difference whether you write listA;listB in one stim cell or put listA in stim and listB in stim1. All the stim columns are read as one semicolon-separated sequence, and the lists at each position are merged per pick.
• Role 1 shares all of stimList’s gotchas: items are not trimmed, and an item carrying a different extension than stimFormat ends up with both.
• In role 3 the value goes through variable replacement first, so %variable% placeholders work.

Caution

In role 3, .html is added only when the value does not already CONTAIN .html anywhere, and only a leading ../ is stripped. A .. in the middle of a path survives, so keep app paths simple and relative to the project’s stimuli folder.

Common combinations

stim appears in these worked recipes:

• 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.
• Counterbalanced sides: Show a fixed pair of stimuli with the left and right assignment drawn once per participant, and score the choice correctly whichever side the target lands on.
• Multi-column list file: Give every generated trial its own settings, such as the correct key, from extra columns in the stimulus list CSV.
• Match to sample: Show a sample stimulus, then an array of choices in shuffled positions, scoring the matching choice correctly wherever it appears.
• Paired presentation: Present items in fixed pairs whose order shuffles for every participant while the members of each pair always stay together on screen.