What is contained in this repository is the algorithm (C++) that detects (micro)saccades in eye-gaze signal.
The algorithm is built and tested with visual studio 2017 with Intel compiler 2019 on Windows 10. The GNU Scientific Library (GSL) version 2.5 and OpenMP are used in our project.
- For the installation of the GSL, please visit https://www.gnu.org/software/gsl/. (Version 2.5 or higher required)
- For the installation of the Intel compiler, please visit https://software.intel.com/en-us/parallel-studio-xe. (If not using the Intel compiler, proper configuration would be required before compiling the project due to the use of the header: omp.h)
For the detailed description regarding the theoretical background and the analytical results of our algorithm, please read our paper:
Zhu, Hongzhi, Septimiu Salcudean, and Robert Rohling. "The Neyman Pearson detection of microsaccades with maximum likelihood estimation of parameters." Journal of vision 19.13 (2019): 17-17.
If you wish to use our algorithm, please cite the aforementioned paper.
In the directory NPD-micro-saccade-detection/NPD_v5, the following files are contained:
- main.cpp
- hzhu_npd.h (The NPD for a section of the gaze signal)
- hzhu_npd_trial.h (The NPD for a trial of gaze signal)
- hzhu_mat.h (Handling GSL matrix)
- hzhu_gen.h (Handling OpenMP and auxiliary tasks)
By default, our algorithm reads in files X.csv and Y.csv, where the X and Y coordinates of the tracked eye-gaze positions are stored in each of the csv files. Data in the X.csv and Y.csv must be square matrices of same dimensions, and each trail of the tracked eye-gaze positions forms the rows of the input file. Our algorithm can perform the NPD on each row of the dataset independently.
The output of the NPD regarding the [i] trial (ith row of the data files) are the following:
-
Result_[i]_detail.csv:
The detailed detection result, a N by 10 matrix. N is the total number of detected events of the [i] trial. For detailed explanation of the meaning of each element in a row, please check file hzhu_npd.h for function hzhu_mat hzhu_npd_results(hzhu_mat &detect, hzhu_mat &result_X, hzhu_mat &result_Y). -
Result_[i]_detect.csv:
The detection result in the form of 0s and 1s, where 0 indicates there is no saccadic event and 1 indicates there is an event -
Result_[i]data_x.csv:
Same as the ith row in X.csv -
Result_[i]data_y.csv:
Same as the ith row in Y.csv -
Result_[i]noise_x_raw.csv:
Estimated variance as a function of n for horizontal movement of the eye -
Result_[i]noise_y_raw.csv:
Estimated variance as a function of n for vertical movement of the eye -
Result_[i]result_x.csv:
Unprocessed result regarding the horizontal movement of the eye, for more information please check file hzhu_npd_trial.h for function void hzhu_npd_trial::process(double x1, double x2, double y1, double y2) -
Result_[i]result_y.csv:
Same as above. -
Result_[i]SIGMA_inv_x.csv:
Covariance matrix for horizontal eye movement -
Result_[i]SIGMA_inv_y.csv:
Covariance matrix for vertical eye movement
In the directory NPD-micro-saccade-detection/example/, we have some example results from data files X.csv and Y.csv. The Matlab file ''visualizer.m'' can help visualizing the detection result from the NPD. All csv files in this directory whose name starts with ''Result'' are generated by calling the NPD.
Several parameters can be adjusted before the use of our method to detect (micro)saccades. Please refer to the file ''main.cpp'' for more information regarding the adjustable parameters. Detailed annotations are provided.