Skip to content

Data Logging

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

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

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

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

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

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

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

Adding to the timeline data file

sightlab.addToTimeline(objectName = "basketball", dwellTime = 0.75)

Setting a 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

import sightlab_utils.sightlab as sl
from sightlab_utils.settings import *

sightlab = sl.SightLab(
    gui=False,
    trackingdatalogging=False,
    replaydatalogging=False,
    timelinelogging=False,
    experimentdatalogging=False,
)
# Example showing how to set environment. Note that environment should be defined before #objects of interest
env = vizfx.addChild("sightlab_resources/environments/dojo.osgb")
sightlab.setEnvironment(env)
# set number of trials
sightlab.setTrialCount(5)
# add objects of interest
soccerball = env.getChild("soccerball")
basketball = env.getChild("basketball")
sightlab.addSceneObject("soccerball", soccerball, gaze=True, grab=True)
sightlab.addSceneObject("basketball", basketball, gaze=True, grab=True)



def sightLabExperiment():
    yield viztask.waitKeyDown(" ")
    while True:
        # Length of each trial
        yield sightlab.startTrial(trialLength=3, startTrialText="start trial")

        if sightlab.getTrialNumber() >= 2:
            yield sightlab.startTrial(
                trialLength=3,
                trackingDataLogging=True,
                replayDataLogging=True,
                experimentSummaryLogging=True,
                timeLineLogging=True,
            )
        else:
            yield sightlab.startTrial(trialLength=3)
        yield viztask.waitEvent(TRIAL_END)
        # Length of cooldown between trials
        yield viztask.waitTime(2)


viztask.schedule(sightlab.runExperiment)
viztask.schedule(sightLabExperiment)

Real time (within trial)

.setDataLoggingState

Example

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

To start logging data:

yield sightlab.startTrial(
    trackingDataLogging=True,
    replayDataLogging=True,
    experimentSummaryLogging=True,
    timeLineLogging=True,
)

To stop logging data

yield sightlab.startTrial(
    trackingDataLogging=False,
    replayDataLogging=False,
    experimentSummaryLogging=False,
    timeLineLogging=False,
)

Saving your own files to the Data Folder

To get access to the location of the data folder per trial you can use code such as this

fileName = '{d}_{p.id}_experiment_data._trial_{t}.pdf'.format(d=sightlab.dateTime, p=sightlab.participantData, t=sightlab.trialNumber-1)
fullPath = os.path.join(sightlab.getExperimentDataFolderPath(), fileName)