imhr.Webgazer.classify¶

Classes

class imhr.Webgazer.classify.Classify(isLibrary=False)[source]¶

Bases: object

Analysis methods for imhr.processing.preprocesing.

Methods

Methods

Acceleration(time, data_x[, data_y])	Calculate the acceleration (deg/sec/sec) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.
Velocity(time, config, d_x[, d_y])	Calculate the instantaneous velocity (degrees / second) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.
VisualAngle(g_x, g_y, config)	Convert pixel eye-coordinates to visual angle.
hmm(data, filter_type, config)	Hidden Makov Model, adapted from https://gitlab.com/nslr/nslr-hmm.
idt(data, dis_threshold, dur_threshold)	Identification with Dispersion Threshold.
ivt(data, v_threshold, config)	Identification with Velocity Threshold.
savitzky_golay(y, window_size, order[, …])	Smooth (and optionally differentiate) data with a Savitzky-Golay filter.
simple(df, missing, maxdist, mindur)	Detects fixations, defined as consecutive samples with an inter-sample distance of less than a set amount of pixels (disregarding missing data).

Acceleration(time, data_x[, data_y])	Calculate the acceleration (deg/sec/sec) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.
Velocity(time, config, d_x[, d_y])	Calculate the instantaneous velocity (degrees / second) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.
VisualAngle(g_x, g_y, config)	Convert pixel eye-coordinates to visual angle.
hmm(data, filter_type, config)	Hidden Makov Model, adapted from https://gitlab.com/nslr/nslr-hmm.
idt(data, dis_threshold, dur_threshold)	Identification with Dispersion Threshold.
ivt(data, v_threshold, config)	Identification with Velocity Threshold.
savitzky_golay(y, window_size, order[, …])	Smooth (and optionally differentiate) data with a Savitzky-Golay filter.
simple(df, missing, maxdist, mindur)	Detects fixations, defined as consecutive samples with an inter-sample distance of less than a set amount of pixels (disregarding missing data).

classmethod VisualAngle(g_x, g_y, config)[source]¶

Convert pixel eye-coordinates to visual angle.

Parameters:	g_x,g_y : numpy.ndarray List of gaze coordinates. drift : dict Counter of drift correct runs. config : dict Configuration data for data analysis. i.e. trial number, location.

Notes

• Stimulus positions (g_x,g_y) are defined in x and y pixel units, with the origin (0,0) being at the center of the display, as to match the PsychoPy pix unit coord type.
• The pix2deg method is vectorized, meaning that is will perform the pixel to angle calculations on all elements of the provided pixel position numpy arrays in one numpy call.
• The convertion process can use either a fixed eye to calibration plane distance, or a numpy array of eye distances passed as eye_distance_mm. In this case the eye distance array must be the same length as g_x, g_y arrays.

classmethod Velocity(time, config, d_x, d_y=None)[source]¶

Calculate the instantaneous velocity (degrees / second) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.

Parameters:	time : numpy.ndarray Timestamp of each coordinate. d_x,d_y : numpy.ndarray List of gaze coordinates. config : dict Configuration data for data analysis. i.e. trial number, location.

Notes

Numpy arrays time, d_x, and d_y must all be 1D arrays of the same length. If both d_x and d_y are provided, then the euclidian distance between each set of points is calculated and used in the velocity calculation. Time must be in seconds.msec units, while d_x and d_y are expected to be in visual degrees. If the position traces are in pixel coordinate space, use the VisualAngleCalc class to convert the data into degrees.

classmethod Acceleration(time, data_x, data_y=None)[source]¶

Calculate the acceleration (deg/sec/sec) for data points in d_x and (optionally) d_y, using the time numpy array for time delta information.

Parameters:	time : numpy.ndarray Timestamp of each coordinate. d_x,d_y : numpy.ndarray List of gaze coordinates. config : dict Configuration data for data analysis. i.e. trial number, location.

classmethod savitzky_golay(y, window_size, order, deriv=0, rate=1)[source]¶

Smooth (and optionally differentiate) data with a Savitzky-Golay filter.

The Savitzky-Golay filter removes high frequency noise from data. It has the advantage of preserving the original shape and features of the signal better than other types of filtering approaches, such as moving averages techniques.

Parameters:	y : numpy.ndarray, shape (N,) the values of the time history of the signal. window_size : int the length of the window. Must be an odd integer number. order : int the order of the polynomial used in the filtering. Must be less then window_size - 1. deriv : int the order of the derivative to compute (default = 0 means only smoothing)
Returns:	ys : numpy.ndarray, shape (N) the smoothed signal (or it’s n-th derivative).

Notes

The Savitzky-Golay is a type of low-pass filter, particularly suited for smoothing noisy data. The main idea behind this approach is to make for each point a least-square fit with a polynomial of high order over a odd-sized window centered at the point. For more information, see: http://wiki.scipy.org/Cookbook/SavitzkyGolay.

Examples

>>> t = np.linspace(-4, 4, 500)
>>> y = np.exp( -t**2 ) + np.random.normal(0, 0.05, t.shape)
>>> ysg = savitzky_golay(y, window_size=31, order=4)
>>> import matplotlib.pyplot as plt
>>> plt.plot(t, y, label='Noisy signal')
>>> plt.plot(t, np.exp(-t**2), 'k', lw=1.5, label='Original signal')
>>> plt.plot(t, ysg, 'r', label='Filtered signal')
>>> plt.legend()
>>> plt.show()

References

[1]	A. Savitzky, Golay, M. (1964). Smoothing and Differentiation of Data by Simplified Least Squares Procedures. Analytical Chemistry. 36(8), pp 1627-1639.

[2]	S.A. Teukolsky, W.T. Vetterling, B.P. Flannery Numerical Recipes 3rd Edition: The Art of Scientific Computing. W.H. Press,Cambridge University Press ISBN-13: 9780521880688.

classmethod ivt(data, v_threshold, config)[source]¶

Identification with Velocity Threshold.

In the I-VT model, the velocity value is computed for every eye position sample. The velocity value is then compared to the threshold. If the sampled velocity is less than the threshold, the corresponding eye-position sample is marked as part of a fixation, otherwise it is marked as a part of a saccade.

Parameters:	data : numpy.ndarray, shape (N,) the smoothed signal (or it’s n-th derivative). v_threshold : str Velocity threshold in pix/sec. config : dict Configuration data for data analysis. i.e. trial number, location.
Returns:	ys : numpy.ndarray, shape (N,) the smoothed signal (or it’s n-th derivative).

Notes

From https://github.com/ecekt/eyegaze. Formula from: https://dl.acm.org/citation.cfm?id=355028

classmethod hmm(data, filter_type, config)[source]¶

Hidden Makov Model, adapted from https://gitlab.com/nslr/nslr-hmm.

Parameters:	data : pandas.DataFrame Pandas dataframe of x,y and timestamp positions. filter_type : dict Types of filters to use. config : dict Configuration data for data analysis. i.e. trial number, location.
Attributes:	data : numpy.ndarray The smoothed signal (or it’s n-th derivative). dr_th : str Data threshold.

Notes

Definitions

• Saccade: The saccade is a ballistic movement, meaning it is pre-programmed and does not change once it has started. Saccades of amplitude 40° peak at velocities of 300–600°/s and last for 80–150 ms.
• Fixation: The point between any two saccades, during which the eyes are relatively stationary and virtually all visual input occurs. Regular eye movement alternates between saccades and visual fixations, the notable exception being in smooth pursuit.
• Smooth pursuit: Smooth pursuit movements are much slower tracking movements of the eyes designed to keep a moving stimulus on the fovea. Such movements are under voluntary control in the sense that the observer can choose whether or not to track a moving stimulus. (Neuroscience 2nd edition).

References

[1]	Pekkanen, J., & Lappi, O. (2017). A new and general approach to signal denoising and eye movement classification based on segmented linear regression. Scientific Reports, 7(1). doi:10.1038/s41598-017-17983-x.

classmethod idt(data, dis_threshold, dur_threshold)[source]¶

Identification with Dispersion Threshold.

Parameters:	data : numpy.ndarray The smoothed signal (or it’s n-th derivative). dr_th : str Fixation duration threshold in pix/msec di_th : str Dispersion threshold in pixels
Returns:	ys : numpy.ndarray The smoothed signal (or it’s n-th derivative).

Notes

The I-DT algorithm has two parameters: a dispersion threshold and the length of a time window in which the dispersion is calculated. The length of the time window is often set to the minimum duration of a fixation, which is around 100-200 ms.

classmethod simple(df, missing, maxdist, mindur)[source]¶

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

Parameters:	df : pandas.DataFrame Pandas dataframe of x,y and timestamp positions missing : str Value to be used for missing data (default = 0.0) maxdist : str Maximal inter-sample distance in pixels (default = 25) mindur : str Minimal duration of a fixation in milliseconds; detected fixation cadidates will be disregarded if they are below this duration (default = 100).
Returns:	Sfix : numpy.ndarray shape (N) list of lists, each containing [starttime] Efix : numpy.ndarray shape (N) list of lists, each containing [starttime, endtime, duration, endx, endy]

Notes

From https://github.com/esdalmaijer/PyGazeAnalyser/blob/master/pygazeanalyser/detectors.py