Modules

Experiment

class Experiment.Experiment(json_file, reading_method='SQL', aoi='NA')[source]

Bases: object

This is class responsible for the analysis of data of an entire experiment. The creation of a an object of this class will subsequently create create objects for each Subject. involved in the experiment (which in turn would create object for each Stimulus which is viewed by the subject).

This class also contains the analyse function which is used for the statistical analysis of the data (eg: Mixed ANOVA, RM ANOVA etc).

Parameters:
  • json_file (str) – Name of the json file that contains information regarding the experiment or the database
  • reading_method (str {"SQL", "CSV"} (optional)) – Mentions the format in which the data is being stored
  • sensors (list(str) (optional)) – Contains the names of the different sensors whose indicators are being analysed (currently only Eye Tracking can be done However in future versions, analysis of ECG and EDA may be added)
  • aoi (str {'NA', 'e', 'r', 'p'} | tuple (optional)) – If ‘NA’ then AOI is the entire display size. If ‘e’ then draw ellipse, ‘p’ draw polygon and ‘r’ draw rectangle. If type is tuple, user must specify the coordinates of AOI in the following order (start_x, start_y, end_x, end_y). Here, x is the horizontal axis and y is the vertical axis.
analyse(parameter_list={'all'}, between_factor_list=['Subject_type'], within_factor_list=['Stimuli_type'], statistical_test='Mixed_anova', file_creation=True, ttest_type=1)[source]

This function carries out the required statistical analysis.

The analysis is carried out on the specified indicators/parameters using the data extracted from all the subjects that were mentioned in the json file. There are 4 different tests that can be run, namely - Mixed ANOVA, Repeated Measures ANOVA, T Test and Simple ANOVA (both 1 and 2 way)
Parameters:
  • parameter_list (set (optional)) – Set of the different indicators/parameters (Pupil_size, Blink_rate) on which statistical analysis is to be performed, by default it will be “all” so that all the parameter are considered.
  • between_factor_list (list(str) (optional)) – List of between group factors, by default it will only contain “Subject_type”. If any additional parameter (eg: Gender) needs to be considered, then the list will be: between_factor_list = [“Subject_type”, “Gender”]. DO NOT FORGET TO INCLUDE “Subject_type”, if you wish to consider “Subject_type” as a between group factor. Eg: between_factor_list = [“factor_x”] will no longer consider “Subject_type” as a factor. Please go through the README FILE to understand how the JSON FILE is to be written for between group factors to be considered.
  • within_factor_list (list(str) (optional)) – List of within group factors, by default it will only contain “Stimuli_type” If any additional parameter, needs to be considered, then the list will be: between_factor_list = [“Subject_type”, “factor_X”]. DO NOT FORGET TO INCLUDE “Stimuli_type”, if you wish to consider “Stimuli_type” as a within group factor. Eg: within_factor_list = [“factor_x”] will no longer consider “Stimuli_type” as a factor. Please go through how the README FILE to understand how the JSON FILE is to be written for within group factors to be considered.
  • statistical_test (str {"Mixed_anova","RM_anova","ttest","anova","None"} (optional)) –
    Name of the statistical test that has to be performed.
    NOTE:
    • ttest: There are 3 options for ttest, and your choice of factors must comply with one of those options, for more information, please see description of ttest_type variable given below.
    • Welch_ttest: There are 2 options for Welch Ttest, and your choice of factors must comply with one of those options, for more information, please see description of ttest_type variable given below.
    • Mixed_anova: Only 1 between group factor and 1 within group factor can be considered at any point of time
    • anova: Any number of between group factors can be considered for analysis
    • RM_anova: Upto 2 within group factors can be considered at any point of time
  • file_creation (bool (optional)) –
    Indicates whether a csv file containing the statistical results should be created.
    NOTE: The name of the csv file created will be by the name of the statistical test that has been chosen. A directory called “Results” will be created within the Directory whose path is mentioned in the json file and the csv files will be stored within “Results” directory. If any previous file by the same name exists, it will be overwritten.
  • ttest_type (int {1,2,3} (optional)) –
    Indicates what type of parameters will be considered for the ttest and Welch Ttest
    NOTE: For ttest-
    • 1: Upto 2 between group factors will be considered for ttest
    • 2: 1 within group factor will be considered for ttest
    • 3: 1 within group and 1 between group factor will be considered for ttest

    For Welch ttest-

    • 1: Will consider the first factor in ‘between_factor_list’
    • 2: Will consider the first factor in ‘within_factor_list’

Examples

For calculating Mixed ANOVA, on all the parameters, with standardisation, NOT averaging across stimuli of the same type and considering Subject_type and Stimuli_type as between and within group factors respectively

>>> analyse(self, standardise_flag=False, average_flag=False, parameter_list={"all"}, between_factor_list=["Subject_type"], within_factor_list=["Stimuli_type"], statistical_test="Mixed_anova", file_creation = True)
OR
>>> analyse(self, standardise_flag=True) (as many of the option are present by default)

For calculating 2-way ANOVA, for “blink_rate” and “avg_blink_duration”, without standardisation with averaging across stimuli of the same type and considering Subject_type and Gender as the between group factors while NOT creating a new csv file with the results

>>> analyse(self, average_flag=True, parameter_list={"blink_rate", "avg_blink_duration"}, between_factor_list=["Subject_type", "Gender"], statistical_test="anova", file_creation = False)
columnsArrayInitialisation()[source]

The functions extracts the names of the columns that are to be analysed

Parameters:json_file (str) – Name of the json file which contains details of the experiment
Returns:columns_list – List of names of columns of interest
Return type:list(str)
drawAOI()[source]

Function that allows speicification of area of interest (AOI) for analysis.

fileWriting(writer, csvFile, pd_dataframe, values_list)[source]

This function is used to write the statistical results into a csv file

Parameters:
  • writer (file object) – File object that is used to write into a csv file
  • csvFile (str) – Name of the csv file
  • pd_dataframe (pandas DataFrame) – Statistical results
  • values_list (list) – Used for labelling the results
getMetaData(sub, stim=None, sensor='EyeTracker')[source]

Function to return the extracted features for a given subject/participant.

Parameters:
  • sub (str) – Name of the subject/participant.
  • stim (str | None) – Name of the stimulus. If ‘str’, the features of the given stimulus will be returned. If None, the features of all stimuli averaged for the different stimuli types (as mentoned in json file) is wanted.
  • sensor (str) – Name of the sensor for which the features is wanted.
Returns:

Return type:

dict

Note

  • If the stim is None, the returned dictionary is organised as follows
    {“Stim_TypeA”: {“meta1”:[], “meta2”:[], …}, “Stim_TypeB”: {“meta1”:[], “meta2”:[], …}, …}
  • If the stim is str, the returned dictionary is organised as follows
    {“meta1”:[], “meta2”:[], …}

To get the names of all the metadata/features extracted, look at the Sensor class

metaMatrixInitialisation(standardise_flag=False, average_flag=False)[source]

This function instantiates the meta_matrix_dict with values that it extracts from the aggregate_meta variable of each Subject object.

Parameters:
  • standardise_flag (bool (optional)) – Indicates whether the data being considered need to be standardised (by subtracting the control values/baseline value)
  • average_flag (bool (optional)) – Indicates whether the data being considered should averaged across all stimuli of the same type NOTE: Averaging will reduce variability and noise in the data, but will also reduce the quantum of data being fed into the statistical test
return_index(value_index, summation_array)[source]

This function is used in helping to find the corresponding stimuli for data points in certain parameters, that more than one value for a specific stimuli

Parameters:
  • value_index (int) – Index of an instance of the parameter in the value array of the meta_matrix_dict
  • summation_array (list) – list of values whose index will indicate which stimuli an instance will correspond to
Returns:

summation_index – Is the index of the stimuli to which an instance of the parameter corresponds to

Return type:

int

stimuliArrayInitialisation()[source]

This functions instantiates the dictionary stimuli with the list of names of the different stimuli by category

Parameters:json_file (str) – Name of the json file which contains details of the experiment
Returns:data_dict – Dictionary containing the names of the different stimuli categorised by type
Return type:dict
subjectArrayInitialisation(reading_method)[source]

This function initialises an list of objects of class Subject.

Parameters:reading_method (str {'SQL','CSV'}) – Specifies the database from which data extraction is to be done from
Returns:subject_list – list of objects of class Subject
Return type:list(Subject objects)
summationArrayCalculation(meta, sub_index, stimuli_index)[source]

This function is used for creating a list that will be used later for identifying the corresponding stimuli for an instance in the meta_matrix_dict

Parameters:
  • meta (str) – Is the parameter that is being considered
  • sub_index (int) – Is the index of subject with regard to meta_matrix_dict
  • sub_index – Is the index of subject with regard to meta_matrix_dict
Returns:

summation_array – list of values whose index will indicate which stimuli an instance will correspond to

Return type:

list

visualizeData()[source]

Function to open up the GUI for visualizing the data of the experiment.

This function can be invoked by an Experiment object. It opens up a window and allows the usee to visualize data such as dynamic gaze and pupil plots, fixation plots and gaze heat maps for individual subjects or aggregate heat maps for a group of subjects on a given stimulus.

welch_ttest(dv, factor, subject, data)[source]

This funtion is used to calculate the welch ttest (used when unequal variance of 2 samples exists)

Parameters:
  • dv (str) – Name of the parameter that is being considered for statistical analysis
  • factor (str) – Name of the factor on which statistical analysis is being done
  • subject (str) – Name of the subject
  • data (pandas DataFrame) – Data on which the Welch t-test is to be performed
Returns:

  • normality (pandas DataFrame) – Data regarding normality of the different categories of the ‘factor’
  • results (pandas DataFrame) – Data containing the results of the Welch t-test

class Experiment.Visualize(master, subjects, exp)[source]

Bases: object

button_click(sub=None)[source]
subFrameSetup()[source]

Sensor

class Sensor.Sensor(name, sampling_freq)[source]

Bases: object

This class represents the paramters of the sensors used during the experiment.

As of now the sensor class only support the Eye Tracker but in future versions, we plan to include EEG, ECG, EDA and Respiration as well. The class is used to store all the metadata/features extracted during analysis.

sensor_names

List of accepted sensors.

Type:list(str)
meta_cols

Dictionary of lists containing the various metadata/features of a given sensor.

Type:dict
Parameters:
  • name (str) – Name of the sensor.
  • sampling_freq (int | float) – Sampling frequency of the sensor.
meta_cols = {'EyeTracker': ['response_time', 'pupil_size', 'time_to_peak_pupil', 'peak_pupil', 'pupil_mean', 'pupil_size_downsample', 'pupil_slope', 'pupil_area_curve', 'blink_rate', 'peak_blink_duration', 'avg_blink_duration', 'fixation_count', 'max_fixation_duration', 'avg_fixation_duration', 'sacc_count', 'sacc_duration', 'sacc_vel', 'sacc_amplitude', 'ms_count', 'ms_duration', 'ms_vel', 'ms_amplitude', 'num_revisits', 'first_pass_duration', 'second_pass_duration']}
sensor_names = ['EyeTracker']

Stimulus

class Stimulus.Stimulus(path, name='id_rather_not', stim_type='doesnt_matter', sensor_names=['EyeTracker'], data=None, start_time=0, end_time=-1, roi_time=-1, json_file=None, subject_name='buttersnaps', aoi=None)[source]

Bases: object

This is the main class that performs analysis and visualization of data collected during presentation of various stimuli during the experiment.

If the framework is used in the Experiment Design objects of this class are created implicitly and the user need not worry about the internal functioning of the class methods. However, if using the Stand-alone Design, the user needs to explicitly create an object of the class and invoke the functions based on what is needed.

Parameters:
  • path (str) – This parameter is the absolute path to the experiment directory containing the json file, stimuli folder with pictures etc. For the Experiment Design, this parameter is internally handled. In the Stand-alone Design, this parameter needs to be specified while creating the object. All data and plots, if saved, will be stored in folders in this location.
  • name (str) – The name of the stimulus. For the Experiment Design, this parameter is internally handled. If using in Stand-alone Design, this parameter is optional and will default to id_rather_not.
  • stim_type (str) – The type of stimulus, if there are different classes of stimulus in the experiment. For the Experiment Design, this parameter is internally handled. If using in Stand-alone Design, this parameter is optional and will default to doesnt_matter.
  • sensor_names (list(str) | dict) – In the Experiment Design sensor_names will default to the sensors being used (as mentioned in the json_file). As of now this only supports EyeTracker. If using in Stand-alone Design, this parameter must be a dictionary of dictionaries with the details of the sensors and their attributes. The framework as of now just supports Eye Tracking so in the Stand-alone Design, sensor_names should be in this format (edit the value of the “Sampling_Freq” according to your eye tracker’s value): {“EyeTracker”: {“Sampling_Freq”:1000}}
  • data (pandas DataFrame) – The data for this stimulus as a Pandas DataFrame. For the Experiment Design, this parameter is internally handled. In the Stand-alone Design use the formatBridge.generateCompatibleFormat module to convert your data into the accepted format and then pass the csv file as a Pandas DataFrame to data. This should be the data for just a single stimulus or else the features extracted will not make sense to you. In case you wish to analyse all stimuli for 1 subject, we suggest using the Experiment Design.
  • start_time (int) – The onset of stimulus. For the Experiment Design, this parameter is internally handled and if -1, it implies that data for stimulus is missing. In the Stand-alone Design, this parameter is optional (0 by default) and need not be mentioned. However, if supplying an entire dataframe and it is desired to analyse data in a given range, supply the index value to start from. Also specify end_time or else -1 is used by default i.e end of DataFrame.
  • end_time (int) – The offset of stimulus. For the Experiment Design, this parameter is internally handled and if -1, it implies that data for stimulus is missing. In the Stand-alone Design, this parameter is optional (-1 by default) and need not be mentioned. However, if supplying an entire dataframe and it is desired to analyse data in a given range, supply the index value to end at. Also specify start_time or else 0 is used by default i.e start of DataFrame.
  • roi_time (int) –
  • json_file (str) – Desciption of experiment as JSON file. For the Experiment Design, this parameter is internally handled. In the Stand-alone Design it is not required (leave as None).
  • subject_name (str (optional)) – Name of the subject being analysed. For the Experiment Design, this parameter is internally handled. In the Stand-alone Design it is optional (Defaults to buttersnaps).
  • aoi (tuple) – Coordinates of AOI in the following order (start_x, start_y, end_x, end_y). Here, x is the horizontal axis and y is the vertical axis.
calculateMSThreshold(vel, sampling_freq, VFAC=5.0)[source]

Function to calculate velocity threshold value for X and Y directions to classify point as a microsaccade point.

Serves as a helper function. See findMicrosaccades

Parameters:
  • vel (array | list) – Gaze velocity in x or y direction
  • sampling_freq (float) – Sampling frequency of the eye tracking device
  • VFAC (float) – Scalar constant used to find threshold (Defaults to 5.0). See R. Engbert and K. Mergenthaler, “Microsaccades are triggered by low retinal image slip,” Proc. Natl. Acad. Sci., vol. 103, no. 18, pp. 7192–7197, 2006.
Returns:

radius – Threshold radius in x or y direction

Return type:

float

diff(series)[source]

Python implementation of Matlab’s ‘diff’ function.

Computes the difference between (n+1)th and (n)th elements of array. Returns (a[n+1] - a[n]) for all n.

Parameters:series (list | array (numeric)) – Numeric list, of type int or float. Must be atleast of length 2.
Returns:The size of the returned list is n-1 where n is the size of series supplied to the diff.
Return type:list | array (numeric)
findBinocularMS(msl, msr)[source]

Function to find binocular microsaccades from monocular microsaccades.

Serves as helper function. See findMicrosaccades

Parameters:
  • msl (array | list (num_ms, 9)) – Microsaccade list returned by findMonocularMS for the left eye. num_ms stands for the number of left eye microsaccades.
  • msr (array | list (num_ms, 9)) – Microsaccade list returned by findMonocularMS for the right eye. num_ms stands for the number of right eye microsaccades.
Returns:

ms – Dictionary of values containing the number of binary microsaccades, number of left eye microsaccades, number of right eye microsaccades, binary microsaccades list, left microsaccades list and right microsaccades list. - “NB” : int - “NR” : int - “NL” : int - “bin” : array | list (num_ms, 18) - “left” : array | list (num_ms, 9) - “right” : array | list (num_ms, 9)

Return type:

dict

findBlinkParams()[source]

Function to find blink parameters like count, duration and average duration

Internal function of class that uses its data member variable. Does not take any input and can be invoked by an object of the class. Serves as a helper function. See findEyeMetaData

Returns:Tuple consisting of (blink_cnt, peak_blink_duration, avg_blink_duration)
Return type:list

Finds indices of occurances of blinks and interpolates pupil size and gaze data.

Function to find blinks and return blink onset, offset indices and interpolated pupil size data. Adapted from: R. Hershman, A. Henik, and N. Cohen, “A novel blink detection method based on pupillometry noise,” Behav. Res. Methods, vol. 50, no. 1, pp. 107-114, 2018. Goto https://osf.io/jyz43/ for R and Matlab implementation.

Parameters:
  • pupil_size (array | list) – Pupil size data for left or right eye
  • gaze (dict of list) – Gaze in x and y direction. {“x” : list , “y” : list }
  • sampling_freq (float) – Sampling frequency of eye tracking hardware (Defaults to 1000).
  • concat (bool) – Concatenate close blinks/missing trials or not. False by default. See R. Hershman et. al. for more information
  • concat_gap_interval (float) – Minimum interval between successive missing samples/blinks to consider for concatenation. If concat is False this parameter does not matter. Default value is 100.
  • interpolate (bool) – Interpolate pupil and gaze data durig blinks (Defaults to False`).
Returns:

  • blinks (dict) – Blink onset and offset indices. {“blink_onset” : list , “blink_offset” : list}
  • interp_pupil_size (array | list) – Interpolated pupil size data for left or right eye after fixing blinks. If interpolate`=``False`, this is the same as pupil_size supplied to the function.
  • new_gaze (dict) – Interpolated gaze in x and y direction after fixing blinks. If interpolate`=``False`, this is the same as gaze supplied to the function. {“x” : list, “y” : list}

findEyeMetaData()[source]

Function to find all metadata/features of eye tracking data.

Internal function of class that uses its data member variable. Can be invoked by an object of the class. The metadata is stored in the sensor object of the class and can be accessed in the following manner.

Examples

The following code will return the metadata dictionary containing all meta features extracted.

>>> stim_obj.findEyeMetaData()
>>> stim_obj.sensors["EyeTracker"].metadata

This segment allows you to extract individual features

>>> stim_obj.sensors["EyeTracker"].metadata["pupil_slope"]
>>> stim_obj.sensors["EyeTracker"].metadata["fixation_count"]
findFixationParams()[source]

Function to find fixation parameters like count, max duration and average duration.

Internal function of class that uses its data member variable. Does not take any input and can be invoked by an object of the class. Serves as a helper function. See findEyeMetaData

Returns:Tuple consisting of (fixation_count, max_fixation_duration, avg_fixation_duration)
Return type:tuple
findFixations()[source]

Function to extract indices of fixation sequences.

Internal function of class that uses its data member variable to compute indices. Does not take any input and can be invoked by an object of the class. Serves as a helper function.

Returns:fixation_indices – Indices of start and end of fixations. {“start”: fixation_onset list, “end”: fixation_offset list}
Return type:dict
findMicrosaccades(sampling_freq=1000, plot_ms=False)[source]

Function to detect microsaccades within fixations.

Adapted from R. Engbert and K. Mergenthaler, “Microsaccades are triggered by low retinal image slip,” Proc. Natl. Acad. Sci., vol. 103, no. 18, pp. 7192–7197, 2006.

Parameters:
  • sampling_freq (float) – Sampling Frequency of eye tracker (Defaults to 1000)
  • plot_ms (bool) – Wether to plot microsaccade plots and main sequence or not (Defaults to False). If True, the figures will be plot and saved in the folder Subjects in the experiment folder.
Returns:

  • all_bin_MS (return value of findBinocularMS) – All the binocular microsaccades found for the given stimuli.
  • ms_count (int) – Total count of all binocular and monocular microsaccades.
  • ms_duration (list(sloat)) – List of durations of all microsaccades.
  • temp_vel (list(float)) – List of peak velocities of all microsaccades.
  • temp_amp (list(float)) – List of amplitudes of all microsaccades.

findMonocularMS(gaze, vel, sampling_freq=1000)[source]

Function to find binocular microsaccades from monocular microsaccades.

Serves as helper function. See findMicrosaccades

Parameters:
  • gaze (array | list) – Gaze positons in x or y direction
  • vel (array | list) – Gaze velocities in x or y direction
  • sampling_freq (float) – Sampling Frequency of eye tracker (Defaults to 1000)
Returns:

  • MS (array (num_ms, 9)) – Array of 9 microsaccade Parameters. These Parameters correspond to the following array indices 0. starting index 1. ending index 2. peak velocity 3. microsaccade gaze vector (x direction) 4. microsaccade gaze vector (y direction) 5. amplitude (x direction) 6. amplitude (y direction) 7. threshold radius (x direction) 8. threshold radius (y direction) num_ms = ms_count
  • ms_count (int) – Number of microsaccades
  • ms_duration (list(int)) – List of duration of each microsaccade. Contains as many values as ms_count

findPupilParams()[source]

Function to find pupil parameters like size, peak size, time to peak size, area under curve, slope, mean size, downsampled pupil size

Internal function of class that uses its data member variable. Does not take any input and can be invoked by an object of the class. Serves as a helper function. See findEyeMetaData

Returns:Tuple consisting of (pupil_size, peak_pupil, time_to_peak, pupil_AUC, pupil_slope, pupil_mean, pupil_size_downsample)
Return type:tuple
findResponseTime(sampling_freq=1000)[source]

Function to find the response time in milliseconds based on the sampling frequency of the eye tracker.

Internal function of class that uses its data member variable. Serves as a helper function. See findEyeMetaData

Parameters:sampling_freq (float) – Sampling Frequency of eye tracker (Defaults to 1000)
Returns:Response time in milliseconds
Return type:float
findSaccadeParams(sampling_freq=1000)[source]

Function to find saccade parameters like peak velocity, amplitude, count and duration.

Internal function of class that uses its data member variable. Serves as a helper function. See findEyeMetaData

Parameters:sampling_freq (float) – Sampling Frequency of eye tracker (Defaults to 1000)
Returns:Tuple consisting of (saccade_count, saccade_duration, saccade_peak_vel, saccade_amplitude).
Return type:tuple
findSaccades()[source]

Function to extract indices of saccade sequences.

Saccades are assumed to be interspersed between fixations. Internal function of class that uses its data member variable to compute indices. Does not take any input and can be invoked by an object of the class. Serves as a helper function.

Returns:saccade_indices – Indices of start and end of saccades. {“start”: saccade_onset list, “end”: saccade_offset list}
Return type:dict
gazeHeatMap(save_fig=False, show_fig=True, save_data=False)[source]

Function to plot heat map of gaze.

Internal function of class that uses its data member variable. Can be invoked by an object of the class.

Parameters:
  • save_fig (bool) – Save the heat map figure or not (Defaults to False). If True, will be saved in the Subjects folder of the experiment folder
  • show_fig (bool) – Display the heat map figure or not (Defaults to True).
  • save_data (bool) – Save the data used for plotting as a csv file.
gazePlot(save_fig=False, show_fig=True, save_data=False)[source]

Function to plot eye gaze with numbered fixations.

Internal function of class that uses its data member variable. Can be invoked by an object of the class.

Parameters:
  • save_fig (bool) – Save the gaze plot figure or not (Defaults to False). If True, will be saved in the Subjects folder of the experiment folder
  • show_fig (bool) – Display the gaze plot figure or not (Defaults to True).
  • save_data (bool) – Save the data used for plotting as a csv file.
getData(data, sensor_names)[source]

Function to extract data and store in local format.

It is invoked by __init__ when the object of the class is created. This function is used in the Experiment Design.

Parameters:
  • data (pandas DataFrame) – DataFrame containing the eye tracking data.
  • sensor_names (list (str)) – List of sensors being used for the experiment (currently supports only EyeTracker).
Returns:

extracted_data – Dictionary of extracted data to be used by the functions of the class. - “ETRows” : list, - “FixationSeq” : list, - “Gaze” : dict, - “InterpPupilSize” : list, - “InterpGaze” : dict, - “BlinksLeft” : dict, - “BlinksRight” : dict

Return type:

dict

getDataStandAlone(data, sensor_names)[source]

Function to extract data and store in local format.

It is invoked by __init__ when the object of the class is created. This function is used in the Stand-alone Design.

Parameters:
  • data (pandas DataFrame) – DataFrame containing the eye tracking data.
  • sensor_names (dict) – Dictionary of dictionaries containing list of sensors being used for the experiment (currently supports only EyeTracker) and their Parameters. See sensor_names in Stimulus for details.
Returns:

extracted_data – Dictionary of extracted data to be used by the functions of the class. - “ETRows” : list, - “FixationSeq” : list, - “Gaze” : dict, - “InterpPupilSize” : list, - “InterpGaze” : dict, - “BlinksLeft” : dict, - “BlinksRight” : dict

Return type:

dict

numberRevisits()[source]

Calculates the number of times the eye revisits within the region of interest, each instance should atleast be 4 milliseconds long

Returns:num_readings – Number of times the subject revisits the Area of Interest (1 revisit is consecutive fixations within AOI)
Return type:int
passDurationCalculation()[source]

Calculates the amount of time spent during the first and second revisit in the region of interest

Returns:
  • first_pass_duration (int) – duration spent on first visit to the Area of Interest
  • second_pass_duration (int) – duration spent on the second revisit of the Area of Interest
position2Velocity(gaze, sampling_freq)[source]

Function to calculate velocity for a gaze point based on a 6 sample window.

Serves as a helper function. See findMicrosaccades.

Parameters:
  • gaze (array | list) – Gaze positons in x or y direction.
  • sampling_freq (float) – Sampling Frequency of eye tracker.
Returns:

velocity – Gaze velocities in x or y direction.

Return type:

array | list

setAOICol(data)[source]

Function to set values based on a point being inside or outsode the AOI.

Parameters:data (list) – List of size 3 containing gaze_aoi, gaze_x and gaze_y column data.
Returns:gaze_aoi_new – Modified gaze_aoi column with the mask for points inside and outside the AOI.
Return type:list
smooth(x, window_len)[source]

Smoothing function to compute running average.

Computes the running average for a window size of window_len. For the boundary values (window_len-1 values at start and end) the window length is reduced to accommodate no padding.

Parameters:
  • x (list | array (numeric)) – Numeric list, of type int or float to compute running average for.
  • window_len (int) – Size of averaging window. Must be odd and >= 3.
Returns:

y – Smoothed version x.

Return type:

list | array (numeric)

smoothGaze(vel, gaze, sampling_freq)[source]

Function to smoothen gaze positions using running average method.

Serves as a helper function. See findMicrosaccades

Parameters:
  • vel (array | list) – Gaze velocities in x or y direction
  • gaze (array | list) – Gaze positons in x or y direction
  • sampling_freq (float) – Sampling Frequency of eye tracker
Returns:

smooth_gaze – Smoothened gaze positons in x or y direction

Return type:

array | list

visualize(show=True, save_data=False)[source]

Function to create dynamic plot of gaze and pupil size.

Internal function of class that uses its data member variable. Does not take any input and can be invoked by an object of the class.

show : bool
Open figure after plotting the data or not.
save_data : bool
Save the data used for plotting as a csv file.
Stimulus.groupHeatMap(sub_list, stim_name, json_file, save_fig=False)[source]

Function to plot aggregate heat map of gaze for a list if subjects.

Invoked by the subjectVisualize function of the Subject class.

Parameters:
  • sub_list (list (Subject)) – List of Subject class objects to plot the gaze heat map for.
  • stim_name (dict) – Dictionary containing the type of stimulus and the number of stimulus of that type. {stim_type:stim_num}
  • json_file (str) – Name of json file containing details of the experiment.
  • save_fig (bool) – Save the figure or not.

Subject

class Subject.Subject(path, name, subj_type, stimuli_names, columns, json_file, sensors, database, reading_method, aoi)[source]

Bases: object

This class deals with encapsulating all the relevant information regarding a subject who participated in an experiment. The class contains functions that help in the extraction of data from the databases (SQL or CSV) and the creation of the Stimuli objects. The class also calculates the control data for the purpose of standardisation.

Parameters:
  • name (str) – Name of the Subject
  • subj_type (str) – Type of the Subject
  • stimuli_names (list(str)) – List of stimuli that are to be considered for extraction
  • columns (list(str)) – List of columns that need to be extracted from the database
  • json_file (str) – Name of json file that contains information regarding the experiment/database
  • sensors (list(str)) – Contains the names of the different sensors whose indicators are being analysed
  • database (str | SQL object) – is the SQL object for the SQL database | name of the folder that contains the name csv files
  • manual_eeg (bool) – Indicates whether artifact removal is manually done or not
  • reading_method (str) – Mentions the format in which the data is being stored
dataExtraction(columns, json_file, database, reading_method, stimuli_names)[source]

Extracts the required columns from the data base and the required stimuli_column and returns a pandas datastructure

Parameters:
  • columns (list(str)) – list of the names of the columns of interest
  • json_file (str) – Name of the json file that contains information about the experiment
  • database (SQL object| str) – is the SQL object for the SQL database | name of the folder that contains the name csv files
  • reading_method (str {"SQL","CSV"}) – Describes which type of databse is to be used for data extraction
  • stimuli_names (list(str)) – List of stimuli that are to be considered for extraction
Returns:

df – contains the data of columns of our interest

Return type:

pandas DataFrame

getControlData()[source]

Function to find the values for standardization/normalization of the features extracte from the different stimuli.

The method is invoked implicitly by the __init__ method. It extracts the features/metadata for the stimuli mentioned in the json file under the “Control_Questions” field. If it is blank the values in the control data structure will be all 0s. During analysis, these control values will be subtracted from the values found for each stimulus.

Returns:control – Dictionary containing the standardised values for all the metadata/features. The keys of the dictionary are the different meta columns for a given sensor type. It can be found under meta_cols in Sensor.
Return type:dict
stimulusDictInitialisation(stimuli_names, columns, json_file, sensors, database, reading_method)[source]

Creates a list of objects of class Stimuli.

Parameters:
  • stimuli_names (list(str)) – list of names of different stimulus
  • columns (list(str)) – list of names of the columns of interest
  • json_file (str) – Name of json file that contains information about the experiment/database
  • sensors (object of class Sensor) – Is an object of class sensor and is used to see if EEG extraction is required
  • database (SQL object | str) – Is the SQL object that is created for accessing the SQL database | Name of the folder containing the CSV files
  • reading_method (str {"SQL","CSV"}) – Describes which type of databse is to be used for data extraction
Returns:

stimulus_object_dict – dictionary of objects of class stimulus ordered by category

Return type:

dict

subjectAnalysis(average_flag, standardise_flag)[source]

Function to find features for all stimuli for a given subject.

Does not return any value. It stores the calculated features/metadata in its aggregate_meta member variable. Can be accessed by an object of the class. For structure of this variable see Subject.

Parameters:
  • average_flag (bool) – If True, average values for a given meta variable under each stimulus type for a given stimulus.
  • standardise_flag (bool) – If True, subtract control_data values for a given meta variable for each stimulus. See getControlData for more details on control_data.
subjectVisualize(master, viz_type='individual', sub_list=None)[source]

Visualization function to open the window for stimulus and plot type selection.

It is invoked internally by the visualizaData function.

timeIndexInitialisation(stimulus_column_name, stimulus_name, df)[source]

This function that will retireve the index of the start, end and roi of a question

Parameters:
  • stimulus_column_name (str) – Name of the column where the stimuli names are present
  • stimulus_name (str) – Name of the stimulus
  • df (pandas dataframe) – Contains the data from which start, end and roi will be extracted from
Returns:

  • start (int) – The index of the start of a queation
  • end (int) – The index of the end of a question
  • roi (int) – The index when the eye lands on the region of interest

class Subject.SubjectVisualize(master, subj_name, stimuli, json_file=None, viz_type='individual', sub_list=None)[source]

Bases: object

button_click(stim, stim_num=-1)[source]

etDataReader

Detects blinks, defined as a period of missing data that lasts for at least a minimal amount of samples

Parameters:
  • x (array) – Gaze x positions
  • y (array) – Gaze y positions
  • time (array) – Timestamps
  • missing (float) – Value to be used for missing data (default = 0.0)
  • minlen (int) – Minimal amount of consecutive missing samples
Returns:

  • Sblk (list of lists) – Each containing [starttime]
  • Eblk (list of lists) – Each containing [starttime, endtime, duration]

etDataReader.fixation_detection(x, y, time, missing=0.0, maxdist=25, mindur=50)[source]

Detects fixations, defined as consecutive samples with an inter-sample distance of less than a set amount of pixels (disregarding missing data)

Parameters:
  • x (array) – Gaze x positions
  • y (array) – Gaze y positions
  • time (array) – Timestamps
  • missing (float) – Value to be used for missing data (default = 0.0)
  • maxdist (int) – Maximal inter sample distance in pixels (default = 25)
  • mindur (int) – Minimal duration of a fixation in milliseconds; detected fixation cadidates will be disregarded if they are below this duration (default = 100)
Returns:

  • Sfix (list of lists) – Each containing [starttime]
  • Efix (list of lists) – Each containing [starttime, endtime, duration, endx, endy]

etDataReader.read_edf(filename, start, stop=None, missing=0.0, debug=False, eye='B')[source]

Returns a list with dicts for every trial.

Parameters:
  • filename (str) – Path to the file that has to be read
  • start (str) – Trial start string
  • stop (str) – Trial ending string (default = None)
  • missing (float) – Value to be used for missing data (default = 0.0)
  • debug (bool) – Indicating if DEBUG mode should be on or off; if DEBUG mode is on, information on what the script currently is doing will be printed to the console (default = False)
  • eye (str {'B','L','R'}) – Which eye is being tracked? Deafults to ‘B’-Both. [‘L’-Left, ‘R’-Right, ‘B’-Both]
Returns:

data – With a dict for every trial. Following is the dictionary 0. x -array of Gaze x positions, 1. y -array of Gaze y positions, 2. size -array of pupil size, 3. time -array of timestamps, t=0 at trialstart, 4. trackertime -array of timestamps, according to the tracker, 5. events -dict {Sfix, Ssac, Sblk, Efix, Esac, Eblk, msg}

Return type:

list

etDataReader.read_idf(filename, start, stop=None, missing=0.0, debug=False)[source]

Returns a list with dicts for every trial.

Parameters:
  • filename (str) – Path to the file that has to be read
  • start (str) – Trial start string
  • stop (str) – Trial ending string (default = None)
  • missing (float) – Value to be used for missing data (default = 0.0)
  • debug (bool) – Indicating if DEBUG mode should be on or off; if DEBUG mode is on, information on what the script currently is doing will be printed to the console (default = False)
Returns:

data – With a dict for every trial. Following is the dictionary 0. x -array of Gaze x positions, 1. y -array of Gaze y positions, 2. size -array of pupil size, 3. time -array of timestamps, t=0 at trialstart, 4. trackertime -array of timestamps, according to the tracker, 5. events -dict {Sfix, Ssac, Sblk, Efix, Esac, Eblk, msg}

Return type:

list

etDataReader.read_tobii(filename, start, stop=None, missing=0.0, debug=False)[source]

Returns a list with dicts for every trial.

Parameters:
  • filename (str) – Path to the file that has to be read
  • start (str) – Trial start string
  • stop (str) – Trial ending string (default = None)
  • missing (float) – Value to be used for missing data (default = 0.0)
  • debug (bool) – Indicating if DEBUG mode should be on or off; if DEBUG mode is on, information on what the script currently is doing will be printed to the console (default = False)
Returns:

data – With a dict for every trial. Following is the dictionary 0. x -array of Gaze x positions, 1. y -array of Gaze y positions, 2. size -array of pupil size, 3. time -array of timestamps, t=0 at trialstart, 4. trackertime -array of timestamps, according to the tracker, 5. events -dict {Sfix, Ssac, Sblk, Efix, Esac, Eblk, msg}

Return type:

list

etDataReader.replace_missing(value, missing=0.0)[source]

Returns missing code if passed value is missing, or the passed value if it is not missing; a missing value in the EDF contains only a period, no numbers; NOTE: this function is for gaze position values only, NOT for pupil size, as missing pupil size data is coded ‘0.0’

Parameters:
  • value (str) – Either an X or a Y gaze position value (NOT pupil size! This is coded ‘0.0’)
  • missing (float) – The missing code to replace missing data with (default = 0.0)
Returns:

Either a missing code, or a float value of the gaze position

Return type:

float

etDataReader.saccade_detection(x, y, time, missing=0.0, minlen=5, maxvel=40, maxacc=340)[source]

Detects saccades, defined as consecutive samples with an inter-sample velocity of over a velocity threshold or an acceleration threshold

Parameters:
  • x (array) – Gaze x positions
  • y (array) – Gaze y positions
  • time (array) – Timestamps
  • missing (float) – Value to be used for missing data (default = 0.0)
  • minlen (int) – Minimal length of saccades in milliseconds; all detected saccades with len(sac) < minlen will be ignored (default = 5)
  • maxvel (int) – Velocity threshold in pixels/second (default = 40)
  • maxacc (int) – Acceleration threshold in pixels / second**2 (default = 340)
Returns:

  • Ssac (list of lists) – Each containing [starttime]
  • Esac (list of lists) – Each containing [starttime, endtime, duration, startx, starty, endx, endy]

formatBridge

formatBridge.convertToBase(filename, sensor_type, device, stim_list=None, start='START', stop=None, eye='B')[source]

Master function that calls the different converter functions to convert to bas data format.

Internally invoked by generateCompatibleFormats.

Parameters:
  • filename (str) – Full path of the data file.
  • sensor_type (str {'EyeTracker'}) – Type of sensor. Supports only ‘EyeTracker’ for now.
  • device (str {'eyelink', 'smi', 'tobii'}) – Make of the sensor. Must be a type of eye tracker.
  • stim_list (list (str) | None) – If None (default) the name of stimuli for a data file wil be generated sequentially as [“stim1”, “stim2”, “stim2”, …]. If it is a list of str, then the stimulus names will be taken from this list in the given order. Hence, the length of stim_list and number of events/trials/simuli markers in the data should be the same.
  • start (str) – The start of event marker in the data (Defaults to ‘START’).
  • stop (str) – The end of event marker in the data (Defaults to None). If None, start of new event will be considered as end of previous event.
  • eye (str {'B','L','R'}) – Which eye is being tracked? Deafults to ‘B’-Both. [‘L’-Left, ‘R’-Right, ‘B’-Both]
Returns:

The extracted data in the base format.

Return type:

pandas DataFrame

formatBridge.db_create(data_path, source_folder, database_name, dtype_dictionary=None, na_strings=None)[source]

Create a SQL database from a csv file

Parameters:
  • data_path (string) – Path to the directory where the database is to be located
  • source_folder (string) – Name of folder that contains the csv files
  • database_name (string) – Name of the SQL database that is to be created
  • dtype_dictionary (dictionary) – Dictionary mapping the names of the columns ot their data type
  • na_strings (list) – Is a list of the strings that are to be considered as null value
formatBridge.generateCompatibleFormat(exp_path, device, stim_list_mode='NA', start='START', stop=None, eye='B', reading_method='SQL')[source]

Function to convert data into the base format before starting analysis and visualization.

The function creates a directory called ‘csv_files’ inside the Data folder and stores the converted csv files in it. If reading_method is specified as ‘SQL’ then an SQL database is created inside the ‘Data’ folder but the user need not worry about it.

Parameters:
  • exp_path (str) – Absolute path to the experiment folder. If the path is a folder, the framework will assume its being run in the Experiment Design mode. If it is a path to a single data file, then the Stand-alone Design mode is assumed.
  • device (str {'eyelink', 'smi', 'tobii'}) – Make of the sensor.
  • stim_list_mode (str {'NA', 'common', 'diff'}) – See the Using PyTrack in the Introduction for details on which of the three to suply.
  • start (str) – The start of event marker in the data (Defaults to ‘START’).
  • stop (str) – The end of event marker in the data (Defaults to None). If None, start of new event will be considered as end of previous event.
  • eye (str {'B','L','R'}) – Which eye is being tracked? Deafults to ‘B’-Both. [‘L’-Left, ‘R’-Right, ‘B’-Both]
  • reading_method (str {'CSV', 'SQL'}) – ‘SQL’ (default) reading method is faster but will need extra space. This affects the internal functioning of he framework and the user can leave it as is.
formatBridge.getColHeaders()[source]

Function to return the column headers for the PyTrack base format data representation.

formatBridge.toBase(et_type, filename, stim_list=None, start='START', stop=None, eye='B')[source]

Bridge function that converts SMI, Eyelink or Tobii raw eye tracking data files to the base CSV format that the framework uses.

Parameters:
  • et_type (str {"smi","tobii", "eyelink"}) – Which eye tracker
  • filename (str) – Full file name (with path) of the data file
  • stim_list (list (str)) – Name of stimuli as a list of strings. If there are n trials/events found in the data, the length of stim_list should be n containing the names of stimuli for each trial/event.
  • start (str) – Marker for start of event in the .asc file. Default value is ‘START’.
  • stop (str) – Marker for end of event in the .asc file. Default value is None. If None, new event/trial will start when start trigger is detected again.
Returns:

df – Pandas dataframe of the data in the framework friendly base csv format

Return type:

pandas DataFrame