stimScreens

Experiments

stimScreens states, in one cell, how a trial’s stimuli are grouped into sequential screens: stimScreens = 1+2+3 shows six stimuli as three screens (one stimulus, then two together, then three together). It is the modern replacement for encoding grouping through empty slots in ISI (200;;300): with stimScreens, grouping lives in stimScreens alone and ISI/presTime are plain per-gap / per-screen value lists. Use it for any sequential presentation where at least one screen shows more than one stimulus (prime then pair, sample then array, dot-probe pair then probe).

Syntax

Write one count per screen, joined with +: 1+2+3 on a six-stimulus row shows one stimulus, then two together, then three together. The counts must add up to the number of stimuli on the row, and the stimuli are taken in the order you listed them.

Two shorthands cover the case where every screen holds the same number of stimuli:

• 2 — every screen shows two stimuli, until the stimulus list is used up. The stimulus count has to divide evenly: 8 stimuli with stimScreens 2 makes 4 screens, while 7 stimuli is an error.
• 2*4 — four screens of two, the same value-first form as 800*3 in the timing columns. It also asserts the screen count. A frames suffix (2f*4) is not accepted here; that spelling belongs to timing values only.

On a row with stimScreens, the timing columns hold exact counts:

• presTime: exactly one value per screen (every screen timed), or one value fewer, which leaves the last screen up until the participant responds. A V*N repetition counts as N values; min_max jitter and a|b|c alternatives count as one value each. Combining the two (150_250*3) is not accepted for now.
• ISI: exactly one value per gap between screens, so one fewer than the number of screens.

Caution

Empty slots (;;) in either timing column are an error on a stimScreens row: the legacy empty-slot grouping and stimScreens cannot be mixed on the same row. Rows whose stimScreens cell is empty are left alone, so legacy rows keep working in a file that uses the column elsewhere.

Options

Value	Effect
empty cell	No explicit grouping; screens are derived from ISI exactly as before
1+2+3 (counts joined with +)	One screen per term, term = stimuli on that screen; sum must equal the trial’s stimulus count
2 (single count)	Every screen shows 2 stimuli until the stimulus list is consumed; the count must divide the stimulus list evenly
2*4 (count*screens)	Explicit repetition, equivalent to 2+2+2+2; also asserts the screen count

Zero terms (1+0+2), non-numeric values, and any other separator (;, -, >) are rejected by validation.

Defaults & missing values

With the column absent or the cell left empty, grouping falls back entirely to the legacy ISI empty-slot mechanism; nothing changes for existing files.

With stimScreens and no timing at all, the trial runs sequentially with sensible defaults: 1000 ms per screen, 500 ms gaps, and the last screen stays up until the participant responds. Writing one timing column keeps the other plain: a blank presTime still gets the 1000 ms default (screens need a duration to advance), but a blank ISI next to an explicit presTime means 0 ms gaps, not the 500 ms default.

A stimScreens that resolves to a single screen (say 3 with 3 stimuli) behaves like the ordinary simultaneous display: no gaps, presTime optional. The cell value is echoed into the results file like any other column.

Works with

• ISI: with stimScreens, ISI is purely temporal (one value per gap, one fewer than the screens); it no longer defines screen boundaries. Without stimScreens, ISI keeps its legacy double duty.
• presTime: one value per screen (all screens timed) or one fewer (last screen until response), the same “one value short = last screen unlimited” rule the column has always had.
• stimFormat: .mp3/.mp4 rows reject stimScreens (audio and video always play sequentially, in their own way); mp3 and .mp3 are both recognised. stimFormat list makes the row list-driven (see the dynamic lists bullet). Image and word trials, including trials that also play sound through the audio column, are in scope.
• target: cannot be combined with stimScreens; list every stimulus in stim instead.
• type: instructions and form rows reject stimScreens; other types (test, practice, learn…) are in scope.
• Dynamic lists (#listName# markers in stim/stimList, or stimFormat list): the stimulus count varies at run time, so only the single broadcast count is allowed; explicit sums and the 2*4 form are a validation error, and the presTime/ISI count checks wait until the list resolves.
• stimOptions random: shuffles stimulus order after the screens are computed. stimScreens grouping is positional, so screen sizes stay fixed while randomisation changes which stimuli fill them. The constrained ordering specs in stimOrder build on this: random(screens) and random(within screens) use this row’s screens directly, and require a stimScreens cell.
• A stimScreens value that cannot be resolved (bad sum, uneven broadcast) does not stop the experiment on its own: the trial silently falls back to the legacy ISI grouping. Upload validation exists precisely to keep such values out of a running study.

Examples

Dot-probe: two faces side by side for 500 ms, then a probe until response (no 500*1 tricks needed, the N−1 rule covers it):

type	stim	stimScreens	presTime	ISI	keyboard	key
test	threat1;neutral1;dot	2+1	500	0	f j	f

Sample-then-array: one sample, gap, four choices shown together:

type	stim	stimScreens	presTime	ISI	keyboard	key
test	sample;c1;c2;c3;c4	1+4	1000	200	1 2 3 4	1

Broadcast pairs with defaults (no timing written, runs 1000 ms per screen, 500 ms gaps, last screen until response):

type	stim	stimScreens
test	a;b;c;d;e;f	2

Tips & gotchas

Caution

A bad stimScreens value only stays out of your study through upload validation: a file edited outside Testable can run with surprising legacy grouping, because the experiment itself quietly falls back rather than stopping.

• The audio/video rejection reads the stimFormat cell only; a row whose stimuli are .mp3/.mp4 by file extension with an empty stimFormat is not caught.
• Broadcast requires even division by design: stimScreens 3 over 8 stimuli is an error rather than a silent 3+3+2, because an uneven remainder usually signals a wrong stimulus list.
• 2*4 and 2 are equivalent over 8 stimuli, but the starred form also asserts the screen count and fails if the list length changes; the bare form adapts.

Common combinations

stimScreens appears in these worked recipes:

• 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.
• 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.
• Dot-probe task: Show a pair of images side by side, replace one with a probe, and measure how fast the probe’s location is reported, in one row per trial.
• Attentional blink: Play a rapid serial stream with two embedded targets, then ask about both, with the second target’s report expected to suffer at short lags.