STIM Files

STIM files in SightLab allow you to easily manipulate an independent variable in a study. For example, you can adjust the size or position of an object per trial, and these conditions can be randomized or iterated through sequentially. Other potential conditions might be things such as a category of video to play, a specific environment that a participant will be in, etc. 

SightLab has a built-in StimReader class which reads the contents of a STIM file in .csv format. To create a STIM file, you first define the variables you want to adjust and then declare what the value of that variable will be. 

For example, to manipulate the size and position of an object (e.g., a basketball), you would do the following:

Sample Optional Config File to define parameters for STIM file

3. In your main experiment script, use the StimReader to load the STIM file:

from utils import stim_reader

SR = stim_reader.StimReader('stim_files/stim_file.csv')


4. Define the list of entries

entries = SR.getStimFileEntryList() 

sightlab.sceneConfigDict["trials"] = len(SR.getStimFileEntryList())

#set number of trials

sightlab.sceneConfigDict["trials"] = 3

import random


for i in range(sightlab.sceneConfigDict["trials"]):

    currentEntry = entries[i]


if 'object size' in currentEntry:

    ballSizeString = currentEntry['object size']

    ballSize = object_Size[ballSizeString]


if 'object position' in currentEntry:

    positionString = currentEntry['object position']

    positionTuple = object_position[positionString]


yield viztask.waitKeyDown(' ')

print('experiment end') 

By using STIM files and the StimReader, you can create more flexible and easily configurable experiments, adjusting different independent variables as needed. 

Example for iterating through videos:

Stim file:




if 'Video' in currentEntry:

video = viz.addVideo(currentEntry['Video'])

STIM Files in Session Replay

Here's a quick sample of using the STIM file in the Session Replay using a few conditions

#First import a STIM file config file or wherever you are either defining the parameters of the condition you are changing (if needed)

from STIM_File_Config import *

#Import Stim File Reader

import viz

import vizfx

from utils import session_replay, stim_reader

#Add these lines to locate your actual STIM file (i.e. what condition is being set for each trial)

SR = stim_reader.StimReader(STIM_FILE_PATH)


entries = SR.getStimFileEntryList()

#Next get a handle to whatever object is being modified. environment is session_replay_object.objects[0], gaze point session_replay_object.objects[1], avatarhead session_replay_object.objects[2], controller session_replay_object.objects[3] and [4] if HMD, then objects start at objects [4] for desktop or [5] for HMD. See utils/data/tracking_data_replay files for exact objects. Can also add the object separately

if __name__ == '__main__':

session_replay_object = session_replay.AvatarReplay(session_replay.replayfileName[session_replay.trialNumber-1],session_replay.trackingfileName[session_replay.trialNumber-1])

basketball = session_replay_object.objects[4]

#Add this code to read STIM file per number of trials

if 1 <= session_replay.trialNumber <= len(entries):

currentEntry = entries[session_replay.trialNumber - 1]


print("Invalid trial number")

#Set conditions

if 'object size' in currentEntry:

ballSizeString = currentEntry['object size']

ballSize = target_object_size[ballSizeString]


STIM  File Loader

If wanting to be able to save multiple STIM files you can also add a STIM file loader to choose which one to use

folder = STIM_FILE_FOLDERlist_of_files = os.listdir(folder)current_stim_file = (f'{folder}/{list_of_files[vizinput.choose("select a stim file", list_of_files)]}') SR = stim_reader.StimReader(current_stim_file)SR.fillStimFileEntryList()