mdl.eyetracking.run¶

class mdl.eyetracking.run(window, timer, isPsychopy=True, libraries=False, subject=None, **kwargs)[source]¶

Module allowing communcation to the SR Research Eyelink eyetracking system. Code is optimized for the Eyelink 1000 Plus (5.0), but should be compatiable with earlier systems.

Notes

According to [Pylink.chm](_staticpdfPylink.chm), the sequence of operations for implementing a trial is:

Perform a DRIFT CORRECTION, which also serves as the pre-trial fixation target.
Start recording, allowing 100 milliseconds of data to accumulate before the trial display starts.
Draw the subject display, recording the time that the display appeared by placing a message in the EDF file.

4) Loop until one of these events occurs RECORDING halts, due to the tracker ABORT menu or an error, the maximum trial duration expires ‘ESCAPE’ is pressed, the program is interrupted, or abutton on the EyeLink button box is pressed. 5) Add special code to handle gaze-contingent display updates. 6) Blank the display, stop recording after an additional 100 milliseconds of data has been collected. 7) Report the trial result, and return an appropriate error code.

Methods

`calibration`()	Start calibration procedure.
`connect`([calibration_type, …])	Connect to Eyelink.
`console`([c, msg])	Allows user-friend console logging using ANSI escape codes.
`drift_correction`([source])	Starts drift correction.
`finish_recording`([path])	Ending Eyelink recording.
`gc`(bound, t_min[, t_max])	Creates gaze contigent event.
`library`()	Check if required libraries to run eyelink and Psychopy are available.
`sample`()	Collects new gaze coordinates from Eyelink.
`send_message`(msg)	Send message to Eyelink.
`send_variable`(variables)	send trial variable to eyelink at the end of trial.
`set_eye_used`(eye)	Set dominant eye.
`start_recording`(trial, block)	Starts recording of Eyelink.
`stop_recording`([trial, block, variables])	Stops recording of Eyelink.

library()[source]¶: Check if required libraries to run eyelink and Psychopy are available.

classmethod console(c='green', msg='')[source]¶

Allows user-friend console logging using ANSI escape codes.

Returns:	result : `str` ANSI escape code.

Notes

Colors are produced using ASCII Oct format. For example: ‘[40m’ See http://jafrog.com/2013/11/23/colors-in-terminal.html

Examples

>>> console(self, message, color='blue)
>>>
>>>

Attributes:	message : `str` Message to send to console. color : `str` Name of color or ANSI escape event to use.

connect(calibration_type=13, automatic_calibration_pacing=1000, saccade_velocity_threshold=35, saccade_acceleration_threshold=9500, sound=True, select_parser_configuration=0, recording_parse_type='GAZE', enable_search_limits=True, ip='100.1.1.1')[source]¶

Connect to Eyelink.

Parameters:

Parameters:	ip : `string` Host PC ip address. calibration_type : `int` Calibration type. Default is 13-point. [see Eyelink 1000 Plus User Manual, 3.7 Calibration] automatic_calibration_pacing : `int` Select the delay in milliseconds, between successive calibration or validation targets if automatic target detection is activeSet automatic calibration pacing. [see pylink.chm] saccade_velocity_threshold : `int` Sets velocity threshold of saccade detector: usually 30 for cognitive research, 22 for pursuit and neurological work. Default is 35. Note: EyeLink II and EyeLink 1000, select select_parser_configuration should be used instead. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration; Eyelink 1000 Plus User Manual, Section 4.3.5 Saccadic Thresholds] saccade_acceleration_threshold : `int` Sets acceleration threshold of saccade detector: usually 9500 for cognitive research, 5000 for pursuit and neurological work. Default is 9500. Note: For EyeLink II and EyeLink 1000, select select_parser_configuration should be used instead. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration; Eyelink 1000 Plus User Manual, Section 4.3.5 Saccadic Thresholds] select_parser_configuration : `int` Selects the preset standard parser setup (0) or more sensitive (1). These are equivalent to the cognitive and psychophysical configurations. Default is 0. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration] sound : `bool` Should sound be used for calibration/validation/drift correction. recording_parse_type : `str` Sets how velocity information for saccade detection is to be computed. Enter either ‘GAZE’ or ‘HREF’. Default is ‘GAZE’. [see Eyelink 1000 Plus User Manual, Section 4.4: File Data Types] enable_search_limits : `bool` Enables tracking of pupil to global search limits. Default is True. [see Eyelink 1000 Plus User Manual, Section 4.4: File Data Types]
Returns:	param : `pandas.DataFrame` Returns dataframe of parameters for subject.

ip : string: Host PC ip address.
calibration_type : int: Calibration type. Default is 13-point. [see Eyelink 1000 Plus User Manual, 3.7 Calibration]
automatic_calibration_pacing : int: Select the delay in milliseconds, between successive calibration or validation targets if automatic target detection is activeSet automatic calibration pacing. [see pylink.chm]
saccade_velocity_threshold : int: Sets velocity threshold of saccade detector: usually 30 for cognitive research, 22 for pursuit and neurological work. Default is 35. Note: EyeLink II and EyeLink 1000, select select_parser_configuration should be used instead. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration; Eyelink 1000 Plus User Manual, Section 4.3.5 Saccadic Thresholds]
saccade_acceleration_threshold : int: Sets acceleration threshold of saccade detector: usually 9500 for cognitive research, 5000 for pursuit and neurological work. Default is 9500. Note: For EyeLink II and EyeLink 1000, select select_parser_configuration should be used instead. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration; Eyelink 1000 Plus User Manual, Section 4.3.5 Saccadic Thresholds]
select_parser_configuration : int: Selects the preset standard parser setup (0) or more sensitive (1). These are equivalent to the cognitive and psychophysical configurations. Default is 0. [see EyeLink Programmer’s Guide, Section 25.9: Parser Configuration]
sound : bool: Should sound be used for calibration/validation/drift correction.
recording_parse_type : str: Sets how velocity information for saccade detection is to be computed. Enter either ‘GAZE’ or ‘HREF’. Default is ‘GAZE’. [see Eyelink 1000 Plus User Manual, Section 4.4: File Data Types]
enable_search_limits : bool: Enables tracking of pupil to global search limits. Default is True. [see Eyelink 1000 Plus User Manual, Section 4.4: File Data Types]

Returns:

param : pandas.DataFrame: Returns dataframe of parameters for subject.

Examples

>>> param = eyetracking.connect(calibration_type=13)

set_eye_used(eye)[source]¶

Set dominant eye. This step is required for recieving gaze coordinates from Eyelink->Psychopy.

Parameters:	eye : `str` Dominant eye (left, right). This will be used for outputting Eyelink gaze samples.

Examples

>>> dominant_eye = 'left'
>>> eye_used = eyetracking.set_eye_used(eye=dominant_eye)

calibration()[source]¶

Start calibration procedure.

Returns:	isCalibration : `bool` Message indicating status of calibration.

Examples

>>> eyetracking.calibration()

drift_correction(source='manual')[source]¶

Starts drift correction. This can be done at any point after calibration, including before and after eyetracking.start_recording has already been initiated.

Parameters:	source : `str` Origin of call, either manual (default) or from gaze contigent event (gc).
Returns:	isDriftCorrection : `bool` Message indicating status of drift correction.

Notes

Running drift_correction will end any start_recording event to function properly. Once drift correction has occured, it is safe to run start_recording.

Examples

>>> eyetracking.drift_correction()

start_recording(trial, block)[source]¶

Starts recording of Eyelink.

Parameters:	trial : `str` Trial Number. block : `str` Block Number.
Returns:	isRecording : `bool` Message indicating status of Eyelink recording.

Notes

tracker.beginRealTimeMode():: To ensure that no data is missed before the important part of the trial starts. The EyeLink tracker requires 10 to 30 milliseconds after the recording command to begin writing data. This extra data also allows the detection of blinks or saccades just before the trial start, allowing bad trials to be discarded in saccadic RT analysis. A “SYNCTIME” message later in the trial marks the actual zero-time in the trial’s data record for analysis. [see pylink.chm]
TrialID:: The “TRIALID” message is sent to the EDF file next. This message must be placed in the EDF file before the drift correction and before recording begins, and is critical for data analysis. The viewer will not parse any messages, events, or samples that exist in the data file prior to this message. The command identifier can be changed in the data loading preference settings. [see Data Viewer User Manual, Section 7: Protocol for EyeLink Data to Viewer Integration]
SYNCTIME:: Marks the zero-time in a trial. A number may follow, which is interpreted as the delay of the message from the actual stimulus onset. It is suggested that recording start 100 milliseconds before the display is drawn or unblanked at zero-time, so that no data at the trial start is lost. [see pylink.chm]

Examples

>>> eyetracking.start_recording(trial=1, block=1)

gc(bound, t_min, t_max=None)[source]¶

Creates gaze contigent event. This function needs to be run while recording.

Parameters:

Parameters:	bound : `dict` [`str`, `int`]: Dictionary of the bounding box for each region of interest. Keys are each side of the bounding box and values are their corresponding coordinates in pixels. t_min : `int` Mininum duration (msec) in which gaze contigent capture is collecting data before allowing the task to continue. t_max : `int` or `None` Maxinum duration (msec) before task is forced to go into drift correction.

bound : dict [str, int]:: Dictionary of the bounding box for each region of interest. Keys are each side of the bounding box and values are their corresponding coordinates in pixels.
t_min : int: Mininum duration (msec) in which gaze contigent capture is collecting data before allowing the task to continue.
t_max : int or None: Maxinum duration (msec) before task is forced to go into drift correction.

Examples

>>> # Collect samples within the center of the screen, for 2000 msec, 
>>> # with a max limit of 10000 msec.
>>> region = dict(left=860, top=440, right=1060, bottom=640)
>>> eyetracking.gc(bound=bound, t_min=2000, t_max=10000)

sample()[source]¶

Collects new gaze coordinates from Eyelink.

Returns:	gxy : `tuple` Gaze coordiantes. ps : `tuple` Pupil size (area). sample : `EyeLink.getNewestSample` Eyelink newest sample.

Examples

>>> eyetracking.sample(eye_used=eye_used)

send_message(msg)[source]¶

Send message to Eyelink. This allows post-hoc processing of event markers (i.e. “stimulus onset”).

Parameters:	msg : `str` Message to be recieved by eyelink.

Examples

>>> eyetracking.console(c="blue", msg="eyetracking.calibration() started")

send_variable(variables)[source]¶

send trial variable to eyelink at the end of trial.

Parameters:	variable : `dict` or None Trial-related variables to be read by eyelink.

stop_recording(trial=None, block=None, variables=None)[source]¶

Stops recording of Eyelink. Also allows transmission of trial-level variables to Eyelink.

Parameters:	trial : `int` Trial Number. block : `int` Block Number. variables : `dict` or None Dict of variables to send to eyelink (variable name, value).
Returns:	isRecording : `bool` Message indicating status of Eyelink recording.

Notes

pylink.pumpDelay():: Does a unblocked delay using currentTime(). This is the preferred delay function when accurate timing is not needed. [see pylink.chm]
pylink.msecDelay():: During calls to pylink.msecDelay(), Windows is not able to handle messages. One result of this is that windows may not appear. This is the preferred delay function when accurate timing is needed. [see pylink.chm]
tracker.endRealTimeMode():: Returns the application to a priority slightly above normal, to end realtime mode. This function should execute rapidly, but there is the possibility that Windows will allow other tasks to run after this call, causing delays of 1-20 milliseconds. This function is equivalent to the C API void end_realtime_mode(void). [see pylink.chm]
TRIAL_VAR:: Lets users specify a trial variable and value for the given trial. One message should be sent for each trial condition variable and its corresponding value. If this command is used there is no need to use TRIAL_VAR_LABELS. The default command identifier can be changed in the data loading preference settings. Please note that the eye tracker can handle about 20 messages every 10 milliseconds. So be careful not to send too many messages too quickly if you have many trial condition messages to send. Add one millisecond delay between message lines if this is the case. [see pylink.chm]
TRIAL_RESULT:: Defines the end of a trial. The viewer will not parse any messages, events, or samples that exist in the data file after this message. The command identifier can be changed in the data loading preference settings. [see Data Viewer User Manual, Section 7: Protocol for EyeLink Data to Viewer Integration]

Examples

>>> variables = dict(stimulus='face.png', event='stimulus')
>>> eyetracking.stop_recording(trial=trial, block=block, variables=variables)

finish_recording(path=None)[source]¶

Ending Eyelink recording.

Parameters:	path : `str` or `None` Path to save data. If None, path will be default from PsychoPy task.
Returns:	isFinished : `bool` Message indicating status of Eyelink recording.

Notes

pylink.pumpDelay():: Does a unblocked delay using currentTime(). This is the preferred delay function when accurate timing is not needed. [see pylink.chm]
pylink.msecDelay():: During calls to pylink.msecDelay(), Windows is not able to handle messages. One result of this is that windows may not appear. This is the preferred delay function when accurate timing is needed. [see pylink.chm]
tracker.setOfflineMode():: Places EyeLink tracker in offline (idle) mode. Wait till the tracker has finished the mode transition. [see pylink.chm]
tracker.endRealTimeMode():: Returns the application to a priority slightly above normal, to end realtime mode. This function should execute rapidly, but there is the possibility that Windows will allow other tasks to run after this call, causing delays of 1-20 milliseconds. This function is equivalent to the C API void end_realtime_mode(void). [see pylink.chm]
tracker.receiveDataFile():: This receives a data file from the EyeLink tracker PC. Source filename and destination filename should be given. [see pylink.chm]

Examples

>>> #end recording session
>>> eyetracking.finish_recording()