Skip to content

Trial Files

Trial files give you complete control over stimulus selection across trials and participants.

Note

This feature is not yet fully supported on all tasks.

How to enable Trial Files for a task

  1. Go to the Stimuli tab of your task
  2. Select trials > upload_file_when_creating_batch
  3. Create a version for your experiment
  4. When creating a participant batch, you'll see an entry for "trial file" corresponding to the relevant task
  5. Upload your TSV (Tab Separated Values) file

Creating a Trial File

Trial files use the TSV (Tab Separated Values) format. You can create one using:

  • Spreadsheet software — Microsoft Excel, Google Sheets, or LibreOffice Calc (use Export as > TSV or similar)
  • Programming languages — Python (the pandas library is useful) or MATLAB

File Format

The trial file structure is:

Column Purpose
First column Participant ID
Remaining columns Stimuli (one column per stimulus)

Key points:

  • Each row represents one trial
  • Rows with the same participant ID belong to the same participant
  • The participant ID can correspond to a "token" passed in the entry URL, or any arbitrary value if you don't use tokens
  • the stimulus name is the filename without its extension
  • Make sure the separator between columns is a TAB, not spaces.

Example

Here's an example file with 4 columns:

a   moon    star    comet
a   sun planet  nebula
b   planet  nebula  moon
b   star    sun comet

This example creates:

  • 2 participants (IDs: "a" and "b")
  • 2 trials per participant
  • 3 stimuli per trial