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:

1. Create a STIM file with entries for 'object size' and 'object position (note that since python is sensitive to spaces, make sure to not have spaces between any values). 

2. For certain situations you might want to use a config file to define the possible values for 'object size' and 'object position'. This is usually done in a config file, which is placed alongside your main script, but you can also add this directly in the code. The config file can also give the path to the STIM file. This may not be needed for all cases however. 

Sample Optional Config File to define parameters for STIM file

4. Define the list of entries

entries = SR.getStimFileEntryList() 

5. In your experiment function, iterate or randomize through the conditions for each trial. Can also use this code to have number of trials automatically match number of lines in the STIM file:

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

#set number of trials

sightlab.sceneConfigDict["trials"] = 3

import random

random.shuffle(entries)

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

    currentEntry = entries[i]

    ... 

6. For each trial, adjust the object's properties based on the current entry:

if 'object size' in currentEntry:

    ballSizeString = currentEntry['object size']

    ballSize = object_Size[ballSizeString]

    basketball.setScale(ballSize)

if 'object position' in currentEntry:

    positionString = currentEntry['object position']

    positionTuple = object_position[positionString]

    basketball.setPosition(positionTuple) 

7. Make sure to yield control back to the main experiment loop after each trial:

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:

Video,Type,Config,Tag,Start,End

utils/resources/media_2D/SBS.mp4,video,mono,baseline,0,2

utils/resources/media/01_Warehouse.avi,video,mono,baseline,0,2

utils/resources/media_2D/SBS.mp4,video,mono,baseline,0,2

Code:

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)

SR.fillStimFileEntryList() 

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]

else:

print("Invalid trial number")

#Set conditions

if 'object size' in currentEntry:

ballSizeString = currentEntry['object size']

ballSize = target_object_size[ballSizeString]

basketball.setScale(ballSize)

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