Data Logging in SightLab

SightLab will automatically create a 'data' folder when you first run a session and save the following data by default. See below on how to add additional data to these files. 

The files created are

• Trial_Data file that reports tracking data and is created for every file individually.

• Trial_Timeline file that summarizes gaze events by time stamps.

• Experiment_Summary file that includes events for the whole experiment, such as gaze events, time to first fixation, saccade averages, as well as custom measurements per trial. 

It is possible to customize the data included in these data files, in the GUI and in the scripts.

Trial_data  shows a timestamp (from start of session and Unix Time Stamp) along with the trial Label, x,y,z coordinates of the gaze intersect, eye Euler (combined and individual eye), head position (6DOF), Fixation/Saccade status, saccade amplitude, velocity, average amplitude, peak velocity, pupil diameter (if you are using a headset that tracks pupil diameter), eye openness (if hardware allows), and custom flags as well as user added data.

Experiment Summary - Shows a summary of the view count, fixation count, dwell time, average view time, per trial saccade calculations, time to first fixation, as well as any additional data that you want to summarize per trial. See documentation on how to add more data. 

Trial Timeline - Shows a timeline of when objects were viewed, for how long, and how many fixations there were per object. You can also add custom flags to the timeline file. 

SightLab_Config .stlb files - STLB files are saved in a folder called "sightlab_configs" and are .json files that can be opened in a text editor or any method you use to open .json files if you need to access the data stored on them. 

config.json  - This json file gives an overview of the options used for the session

Adding Custom Data Points

Adding to the Data Files

See the Example folder "Custom Data Saving" in the ExampleScripts folder for some examples

Adding a scene object to the tracking data

basketball = env.getChild('basketball')

sightlab.addSceneObject('basketball', basketball, gaze=True, grab=True)

sightlab.addTrackingTrialDataColumn("basketball", basketball, dataType = SIXDOF, mode = viz.ABS_GLOBAL)

Setting multiple data  measurements

def update_right_hand():

     rHandPos = sightlab.getAvatarRHand().getPosition()

     rHandPos = [round(x, 3) for x in rHandPos]

     sightlab.setCustomTrialData(str(rHandPos[0]), 'Rhand X')

 update_action = vizact.onupdate(0, update_right_hand)

Adding to the experiment summary file 

(make sure this is done before sightlab.endTrial())

sightlab.setExperimentSummaryData('condition',condition)

Adding to the experiment summary file second way

targetCorrect = 'Unknown'

sightlab.customExperimentDataColumns = {'Performance':targetCorrect}

#wait for event to trigger change

targetCorrect = 'Correct'

Adding to the trial timeline

def buttonTrigger():

     sightlab.addToTimeline("t pressed")

     print("T key pressed")

vizact.onkeydown('t', buttonTrigger)

Example Usage

import sightlab_utils.sightlab as sl

from sightlab_utils.settings import *

sightlab = sl.SightLab(gui=False, pid=False)

# Set up environment

env = vizfx.addChild("sightlab_resources/environments/dojo.osgb")

sightlab.setEnvironment(env)

# Configure trials

sightlab.setTrialCount(3)

basketball = env.getChild('basketball')

sightlab.addSceneObject('basketball', basketball, gaze=True, grab=True)

sightlab.addTrackingTrialDataColumn("basketball", basketball)

sightlab.addCustomTrialDataColumn("Condition")

def sightLabExperiment():

    for i in range(sightlab.getTrialCount()):

        yield viztask.waitKeyDown(' ')

       # Start recording right hand position

        def update_right_hand():

            rHandPos = sightlab.getAvatarRHand().getPosition()

            rHandPos = [round(x, 3) for x in rHandPos]

            sightlab.setCustomTrialData(str(rHandPos[0]), 'Rhand X')

            sightlab.setCustomTrialData(str(rHandPos[1]), 'Rhand Y')

            sightlab.setCustomTrialData(str(rHandPos[2]), 'Rhand Z')

        update_action = vizact.onupdate(0, update_right_hand)

        # Start trial

        yield sightlab.startTrial()

        # Define a button trigger event

        def buttonTrigger():

            sightlab.setCustomTrialData('T key pressed', 'custom flag')

            print("T key pressed")

        vizact.onkeydown('t', buttonTrigger)

        # Set condition

        condition = 'condition1'

        sightlab.setCustomTrialData(condition, 'Condition')

        sightlab.setExperimentSummaryData('condition', condition)

        yield viztask.waitKeyDown(' ')

        yield sightlab.endTrial(endExperimentText='Done')

viztask.schedule(sightlab.runExperiment)

viztask.schedule(sightLabExperiment)

Setting multiple objects to Experiment Summary

# Create a dictionary with all the data

experimentData = {

'Object Size': sceneObjectSizeString,

'NUM_OBJ': NUM_OBJ,

'Time to Find Target': time_to_find_target,

'Target Position': targetPos,

'Target Correct': targetCorrect,

'Confidence Level': sightlab.ratingChoice}

# Iterate through the dictionary and set each item

for columnName, data in experimentData.items():

    sightlab.setExperimentSummaryData(columnName, data)

    sightlab.customExperimentDataColumns = experimentData

Setting Condition

yield sightlab.startTrial(trialLabel = "A")

Logging Flags or Events

To log specific events or flags during the experiment, such as a button press or a significant event:

sightlab.setCustomTrialData('name of flag')

• Example:

def buttonTrigger():

sightlab.setCustomTrialData('T key pressed', 'custom flag')

print("T key pressed")

vizact.onkeydown('t',buttonTrigger)

• Changing Data Directories

sightlab.setDataDirectory() #Changes the name of the folder where the data is stored

sightlab(directory = ('absolute path to the current running script')

Starting and Stopping the Logger

Real time (within trial)

.setDataLoggingState

Example

sightlab.setDataLoggingState(0) #This will set it to stop

To start logging data:

To stop logging data