listOptions

Experiments

listOptions configures list-driven trial generation. It has TWO independent grammars for the two list features:

1. Static stimulus lists (stimFormat: list rows): per-list picking options applied while the trial file is built. Controls how rows are picked from each list named in stim/stimN.
2. Dynamic lists (#listName# markers in column values): listOptions decides whether multiple lists expand in parallel (default) or as a nested cross-product.

The column never takes JSON.

Syntax

Write one option per list, in the same order as the ;-separated list names in your stim columns: random;seq shuffles the first list and keeps the second in file order.

For stimFormat: list rows (grammar 1):

listOptions = <optionsForList1> ; <optionsForList2> ; ...
<optionsForListK> = token [, token ...]
token = seq | group N | repeat N | random | sample [N] [min M] [max K]

• ; separates option groups, aligned positionally with the ;-separated list names from the stim columns.
• , separates multiple tokens applied to ONE list, composed in the order you write them.
• A list with no own group inherits the PREVIOUS list’s tokens; an explicitly empty group (;;) resets to seq.

For dynamic lists (#listName# markers, grammar 2), the cell takes one of:

listOptions = parallel
listOptions = nested
listOptions = nested(listA, listB[, ...])

Options

Grammar 1 tokens (a token is recognised by its opening word):

Token	Behavior
seq	Use rows in file order. Default.
group N	Treat consecutive runs of N rows as units for the LATER tokens in the same group (group 2, random shuffles yoked pairs; group 2, sample 3 samples 3 pairs). Each generated trial still gets exactly ONE list row; groups never merge rows into one trial, and group N on its own changes nothing. N defaults to 1; grouping is skipped when N is 1 or as large as the list.
repeat N	Run through the whole list N times. N defaults to 1.
random	Shuffle the list’s rows.
sample [N] [min M] [max K]	Randomly pick N rows (default 1), each row at most K times (default 1), plus at least M full copies of the list (default 0, shuffled in); if N is smaller than M copies require, it is raised to fit.

Anything else (including an empty group) behaves as seq.

Grammar 2 values:

Value	Behavior
absent / no match / parallel	Lists referenced via #name# expand positionally in parallel; shorter lists pad with empty values
nested	Cross-product of ALL lists in the row
nested(a, b)	Cross-product over the named lists only; unnamed lists ride along in parallel with the combinations

Defaults & missing values

With the column absent or the cell left empty, every static list is used in file order (seq) and dynamic lists expand in parallel. For group and repeat, the number is the first run of digits in the token.

Works with

• Grammar 1 only runs on rows whose stimFormat is list; the rows it picks are recorded in stim_actual in the results.
• trialOrder specs refuse stimFormat: list rows: uploading such a file fails with a message pointing you back to this column, which is the way to sample list items.
• With several lists, the number of generated trials follows the longest picked list; positions past a shorter list’s end contribute nothing for that list.
• Grammar 2 runs when a trial containing #list# markers expands at run time; the values actually used are recorded per column as <column>_actual in the results.
• Dynamic-list markers also support inline functions #list.random# / #list.sample(n)#, which are independent of listOptions.
• listOptions is echoed into the results file for every saved row.

Examples

Shuffle one list, sample 10 with each row at most twice from a second:

type	stimFormat	stim	listOptions
test	list	words;faces	random; sample 10 max 2

Shuffle list rows in yoked pairs (pairs stay adjacent and internally ordered; still one stimulus per generated trial):

type	stimFormat	stim	listOptions
test	list	pairsList	group 2, random

Nested cross-product of two dynamic lists (one generated trial per color x shape combination):

type	stimFormat	stim1	stim2	listOptions
test	word	#colors#	#shapes#	nested(colors, shapes)

Tips & gotchas

Caution

repeat is the only case-sensitive token: Repeat 3 is silently ignored and the list falls back to file order. Write it lowercase.

• Option-group inheritance carries FORWARD only: a single random for 3 lists means all 3 shuffle (independently); to keep list 2 sequential you must write random;seq;random.
• Token order matters: group 2, random shuffles yoked pairs, while random, group 2 behaves like plain random, because grouping only affects the tokens written after it.
• Do not write the same token twice in one group: group 2, group 4 applies group 4 twice, never group 2. Use one group token per list.
• sample guarantees min full copies of the list first, then fills the remainder randomly under the max cap; max effectively limits only the picks beyond those copies.
• In grammar 2, nested combinations use the lists’ current contents: a list changed by addToList in a script column changes later expansions.
• The column never accepts JSON; older references to a JSON format are wrong.

Common combinations

listOptions 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.
• Multi-column list file: Give every generated trial its own settings, such as the correct key, from extra columns in the stimulus list CSV.