Sample 06: Verifying fixation before starting a trial

What does this sample do?

In many experiments, participants are requested to fixate on a small point at the beginning of a trial to control initial gaze position. verifyFixation() is a helper function to perform this procedure. Following code shows a small square at the center of the screen and waits for space key to be pressed. At the moment the key is pressed, distance between gaze position and the small square is measured. If the distance is smaller than permissibleError (20pix), verifyFixation() is finished. Otherwise, verifyFixation() repeats these tasks for number of times specified by maxTry.

ret = tracker.verifyFixation(maxTry=3,
                             permissibleError=20,
                             units='pix')
if ret=='q':
    sys.exit()

Note

VisionEgg-based controller doesn’t have ‘units’ option.

If verifyFixation() has not been finished after repetition of the number of times specified by maxTry, verifyFixation automatically calls doCalibration(). After calibration procedure has been finished by ESC key, verifyFixation() repeats its tasks from the beginning. If calibration procedure has been finished by ‘q’ key, verifyFixation() is terminated immediately.

../_images/sample06_001.png

Figure 1

Return value of verifyFixation() is the measured distance (see getSpatialError() for detail) unless verifyFixation() is terminated by ‘q’ key. If ‘q’ key is pressed to exit calibration, return value is ‘q’.

To change messages shown below the small square, use ‘message’ option. Mouse buttons can also be used by using ‘mouseButton’ option. See document of verifyFixation() for detail.:

messages = ['Ready?',
            'Try again.',
            'Please call experimenter.']
ret = tracker.verifyFixation(maxTry=3,
                             permissibleError=20,
                             message=messages,
                             mouseButton=0)

If recorded data is so noisy that gaze position frequently goes in and out even when participant fixates the target, consider using ‘ma’ option (new feature in 0.6.5).

ret = tracker.verifyFixation(maxTry=3, permissibleError=20, ma=5)

Codes (PsychoPy)

This sample code is the same as Sample 01: Controlling SimpleGazeTracker from GazeParser.TrackingTools except that verifyFixation() is called instead of getSpatialError() at the beginning of a trial.

Codes (VisionEgg)

This sample code is the same as Sample 01: Controlling SimpleGazeTracker from GazeParser.TrackingTools except that verifyFixation() is called instead of getSpatialError() at the beginning of a trial.

New function in 0.6.3

In 0.6.3, verifyFixation() can toggle visibility of current gaze position and limit of permissible error by pressing “m” key (Figure 2).

../_images/sample06_002.png

Figure 2

This feature is implemented by parameters added to verifyFixation in 0.6.3.

Parameter Description
gazeMarker Specify a stimulus which is presented on the current gaze position. If None, default marker (small yellow dot) is used. Default value is None.
backgroundStimuli (sequence) Specify a list of stimuli which are presented as background stimuli. If None, a circle is presented as background. Radius of this circle is equal to the value of permissible error parameter. Default value is None.
toggleMarkerKey (str) Specify name of a key to toggle visibility of gaze marker. Default value is ‘m’. Note that the default value of this parameter is equal to that of toggleBackgroundKey.
toggleBackgroundKey (str) Specify name of a key to toggle visibility of background stimuli. Default value is ‘m’. Note that the default value of this parameter is equal to that of toggleBackgroundKey.
showMarker (bool) If True, gaze marker is visible when getSpatialError is called. Default value is False.
showBackground (bool) If True, gaze marker is visible when getSpatialError is called. Default value is False.

In following example, different keys (‘p’ and ‘b’) are assigned to toggleMarkerKey and toggleBackgroundKey. Multiple psychopy.visual.Rect objects are presented as background stimuli. Large white circle is used as gaze position marker.:

marker = psychopy.visual.Circle(win, radius=40, fillColor='white', units='pix')
background = [psychopy.visual.Rect(win, width=300, height=200, pos=(-160,-120),
                                   lineColor=None, fillColor='red', units='pix'),
              psychopy.visual.Rect(win, width=300, height=200, pos=(-160, 120),
                                   lineColor=None, fillColor='blue', units='pix'),
              psychopy.visual.Rect(win, width=300, height=200, pos=( 160,-120),
                                   lineColor=None, fillColor='black', units='pix'),
              psychopy.visual.Rect(win, width=300, height=200, pos=( 160, 120),
                                   lineColor=None, fillColor='green', units='pix')]

error = tracker.verifyFixation(maxTry=3, permissibleError=40, units='pix',
                               gazeMarker=marker, showMarker=True,
                               toggleMarkerKey='p', toggleBackgroundKey='b',
                               backgroundStimuli=background, showBackground=True)

By pressing ‘p’ and ‘b’, visibility of gaze position marker and background stimuli can be toggled separately (Figure 3).

../_images/sample06_003.png

Figure 3

In the next example, a bitmap file (‘grid.png’) is presented as background stimulus. To change fixation target to a yellow square, setCalibrationTargetStimulus() is used. By setting None as toggleBackgroundKey, changing visibility of backgroud stimuli is disabled. Only visibility of gaze position marker can be toggled by pressing default (‘m’) key (Figure 4).:

target = psychopy.visual.Rect(win, width=16, height=16, units='pix',
                              lineColor=None, fillColor='yellow')
background = [psychopy.visual.SimpleImageStim(win,image='grid.png')]

tracker.setCalibrationTargetStimulus(target)
error = tracker.verifyFixation(maxTry=3, permissibleError=40, units='pix',
                               toggleBackgroundKey=None,
                               backgroundStimuli=background, showBackground=True)
../_images/sample06_004.png

Figure 4