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

target_object_size = {'small':[0.5,0.5,0.5],'medium':[2,2,2],'large':[4,4,4]}

target_object_position = {'position1':[0,1,2],'position2':[0,1.5,3],'position3':[1,0,2]}

STIM_FILE_LOCATION = 'stim_file_directory/stim_file_example.csv'

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

from sightlab_utils import stim_reader


# Initialize StimReader with the STIM file

SR = stim_reader.StimReader(STIM_FILE_LOCATION)

SR.fillStimFileEntryList()

4. Define the list of entries

entries = SR.getStimFileEntryList() 

sightlab.setTrialCount = len(SR.getStimFileEntryList())

#set number of trials

sightlab.setTrialCount(3)


import random

random.shuffle(entries)


entries = SR.getStimFileEntryList()

    sightlab.setTrialCount(len(entries))

    

#     Iterate over the entries

    for i in range(len(entries)):

        yield viztask.waitKeyDown(' ')

        yield sightlab.startTrial()


        currentEntry = entries[i]

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) 

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

sightlab_resources/media_2D/SBS.mp4,video,mono,baseline,0,2

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

sightlab_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 sightlab_utils import replay as Replay

from sightlab_utils.replay_settings import *


#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 env = replay.getEnvironmentObject(), then objects are objectName = replay.sceneObjects[GAZE_OBJECTS]["objectName"]. Can also add the object separately


replay = Replay.SightLabReplay()


basketball = replay.sceneObjects.get('basketball')


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

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

currentEntry = entries[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


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()