Mixing Surveys and Experiments

Experiments Surveys & forms

A Testable project does not have to be either an experiment or a survey. A single trial file can contain both: experiment trials (test, practice, learn, instructions) and survey rows (type = form), in any order. The type column decides, row by row, which world each row belongs to.

This page covers what happens at the seams: how form rows group into pages between experiment trials, which columns cross over between the two worlds, and which stay experiment only.

Interleaving form rows between trials

Drop form rows anywhere in the trial file. Consecutive form rows are gathered onto one survey page, and a page always ends when the next row is not a form. That gives you the two building blocks:

To show several questions together, put their form rows on consecutive lines.
To split a run of questions across pages, put 1 in the pageBreak cell of the last question of each page.

So a typical mixed file reads naturally top to bottom: an instructions screen, a block of test trials, a page or two of questions, another block of trials, and so on. Each block of consecutive form rows becomes its own survey page (or pages, with pageBreak), and the surrounding experiment trials run exactly as they would in a pure experiment.

Form pages write their own rows to the results file, alongside the rows written by your test trials. See Forms and Surveys for the anatomy of a form row and How to Read the Results Files for where the answers land.

Showing stimuli next to questions

The stimulus columns work on form rows too: stim1..stimN (and an inline list in stim) display next to the question. This is how you ask “how pleasant is this image?” with the image right there on the survey page.

Two differences from experiment trials:

On form rows the stimuli are display only. They are not clickable response options; the answer comes from the question’s responseType widget.
stimFormat still matters on form rows: it controls whether images preload next to the question. It does not make a row a survey question; only type = form does that. Stimulus list expansion and HTML apps are experiment only.

Scoring form answers with `key`

The key column scores survey answers just as it scores experiment responses. Each question’s key cell scores that question:

A plain text key scores against the response text, on any question type.
A responseCode= key scores against the recorded option codes instead (useful for checkboxes, where several options can be selected).
On choice questions (radio, dropdown, rank, checkboxes) a key of 0 means “correct when nothing is selected”.
On matrix questions (a question with responseRows or stimuli), the key is a ; separated list of per row expected answers, and the recorded correctness is a per row string like 1;0;... rather than a single 0 or 1.

Questions with an empty key cell are simply not scored, and unscored questions are left out of the accuracy average shown at debrief. This is what makes mixed knowledge checks work: score the quiz questions, leave the opinion questions unscored.

For numeric scoring of answer options (summed scale scores rather than correct or incorrect), use the score column instead; see Forms and Surveys.

Renaming the submit button

On experiment trials, button1 and up define the clickable response choices. On form pages, button1 does something different: it renames the page’s submit button.

By default a survey page’s button reads NEXT, or FINISH when it is the last page of the project or the next trial is not a form. A filled in button1 overrides both. Each page has one button and its label comes from the last row on the page, so put the button1 value on the page’s final form row.

Workflow features that span both worlds

Most of the project level machinery does not care whether a row is an experiment trial or a form row, so a mixed project can be randomised, branched and timed as one whole:

Randomisation: random and randomBlock shuffle form rows and experiment trials alike, and sampling specs in the trialOrder column select among them. See Randomisation. Note that after shuffling, “consecutive form rows” means consecutive in presentation order, so randomising forms can change how they group into pages.
Subject groups: subjectGroup shows rows of either kind only to their group, so different groups can get different questionnaires as easily as different trial blocks. See Subject Groups and Allocation.
Logic: the if and then columns branch on responses from either world, which is how a survey answer can route a participant past or into an experimental block. See How to Inject Logic and Screener Surveys.
Timers: the timer column runs on form pages too, with two form specific behaviours: form rows without their own timer value inherit the timer of the first row of their page, and when a skip timer expires inside a form, the page is submitted and the participant jumps past the timed block.

What does not carry over

The columns that shape a stimulus presentation timeline are experiment only and are ignored on form rows:

presTime (stimulus display durations)
ISI (blank gaps between stimulus screens)
The feedback column, which is only honoured on test and practice trials

Two more columns cross over, but behave differently on forms:

ITI applies the pre trial delay on surveys normally, with nuances in old style form projects (a 500 ms default, and only a plain integer is read from the cell); see the column page.
responseWindow on surveys only accepts a plain number, which auto submits the page after that many milliseconds; the full start position syntax is experiment only.

When in doubt about any column, its Columns Reference page carries an applies to badge at the top saying whether it works on experiments, on surveys and forms, or both, plus a note on how the behaviour differs.

A worked example

A miniature recognition study: instructions, two scored test trials, then a survey page with one unscored question and one scored question.

type,content,stimFormat,stim1,keyboard,key,head,responseType,responseOptions,button1
instructions,Press F if the word is OLD and J if it is NEW.,,,,,,,,Start
test,,word,APPLE,f j,f,,,,
test,,word,TABLE,f j,j,,,,
form,,,,,,How confident are you in your answers?,likert,Not at all;Slightly;Moderately;Very;Extremely,
form,,,,,No,Did you look anything up during the task?,radio,Yes;No,Finish

Walking through it:

The instructions row shows the task description; button1 relabels its advance button to Start.
The two test rows are word trials: participants press F or J (keyboard), and key scores F correct for APPLE and J correct for TABLE. Both rows are saved to the results file.
The two form rows are consecutive, so they share one survey page (no pageBreak needed). The confidence question has no key and stays unscored; the honesty check is scored correct when the answer is No.
button1 on the last form row relabels the page’s submit button to Finish. Left blank, it would have read FINISH anyway here, because no form follows.

Next steps

Trial Types for what each type value does
Forms and Surveys for the full form row toolkit
Randomisation and How to Inject Logic for the shared workflow layer