Fixation detection using a velocity threshold identification method
Source:R/fixation_VTI.R
fixation_VTI.RdDetermine fixations by assessing the velocity of eye-movements, using a method that is similar to that proposed by Salvucci & Goldberg (1996). Applies the algorithm used in VTI_saccade and removes the identified saccades before assessing whether separated fixations are outside of the dispersion tolerance. If they are outside of this tolerance, the fixation is treated as a new fixation regardless of the length of saccade separating them. Compared to fixation_dispersion(), fixation_VTI() is more conservative in determining a fixation as smaller saccades are discounted and the resulting data is treated as a continued fixation (assuming it is within the pixel tolerance set by disp_tol). Returns a summary of the fixations found per trial, including start and end coordinates, timing, duration, mean velocity, and peak velocity.
Usage
fixation_VTI(
data,
sample_rate = NULL,
threshold = 100,
min_dur = 150,
min_dur_sac = 20,
disp_tol = 100,
smooth = FALSE,
progress = TRUE,
participant_ID = "participant_ID"
)Arguments
- data
A dataframe with raw data (time, x, y, trial) for one participant
- sample_rate
sample rate of the eye-tracker. If default of NULL, then it will be computed from the timestamp data and the number of samples
- threshold
velocity threshold (degrees of VA / sec) to be used for identifying saccades.
- min_dur
Minimum duration (in milliseconds) of period over which fixations are assessed
- min_dur_sac
Minimum duration (in milliseconds) for saccades to be determined
- disp_tol
Maximum tolerance (in pixels) for the dispersion of values allowed over fixation period
- smooth
include a call to eyetools::smoother on each trial
- progress
Display a progress bar
- participant_ID
the variable that determines the participant identifier. If no column present, assumes a single participant
Value
a dataframe containing each detected fixation by trial, with mean x/y position in pixel, start and end times, and duration.
Details
It can take either single participant data or multiple participants where there is a variable for unique participant identification.
The function looks for an identifier named participant_ID by default and will treat this as multiple-participant data as default,
if not it is handled as single participant data, or the participant_ID needs to be specified
References
Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the Symposium on Eye Tracking Research & Applications - ETRA '00, 71–78.
Examples
# \donttest{
data <- combine_eyes(HCL)
data <- interpolate(data, participant_ID = "pNum")
fixation_VTI(data[data$pNum == 119,], participant_ID = "pNum")
#> pNum trialNumber fix_n start end duration x y min_dur
#> 1 119 1 1 0 223 223 972.1103 765.7244 150
#> 2 119 1 2 240 419 179 937.0440 643.6233 150
#> 3 119 1 3 439 959 520 974.6348 419.9574 150
#> 4 119 1 4 1009 1386 377 409.2640 753.4045 150
#> 5 119 1 5 1589 1856 267 971.0424 304.7891 150
#> 6 119 1 6 1889 2066 177 979.2380 581.0955 150
#> 7 119 1 7 2112 3022 910 1500.3562 765.8028 150
#> 8 119 1 8 3089 3292 203 444.7179 735.7169 150
#> 9 119 1 9 3326 4159 833 964.2701 480.0865 150
#> 10 119 1 10 4209 4652 443 460.4234 761.3488 150
#> 11 119 1 11 4715 5005 290 1477.5086 754.9841 150
#> 12 119 1 12 5059 5272 213 439.7000 686.8906 150
#> 13 119 1 13 5278 6722 1444 412.1090 779.4104 150
#> 14 119 1 14 6741 7301 560 505.3288 727.6988 150
#> 15 119 1 15 7375 7598 223 1480.4473 767.7752 150
#> 16 119 1 16 7618 7885 267 1587.2292 743.6164 150
#> 17 119 1 17 7948 8448 500 995.6632 325.6133 150
#> 18 119 1 18 8498 8848 350 343.7616 673.5203 150
#> 19 119 1 19 8904 9108 204 970.3422 314.1502 150
#> 20 119 1 20 9154 9604 450 451.2965 775.9674 150
#> 21 119 1 21 9638 9814 176 890.3137 527.7975 150
#> 22 119 1 22 9828 9984 156 941.0363 462.3133 150
#> 23 119 2 1 0 160 160 964.4077 800.0306 150
#> 24 119 2 2 200 563 363 489.4246 748.2445 150
#> 25 119 2 3 626 783 157 1432.7215 766.1448 150
#> 26 119 2 4 800 1086 286 1546.5018 746.7085 150
#> 27 119 2 5 1273 1493 220 997.7612 399.4104 150
#> 28 119 2 6 1513 2086 573 950.6969 208.1089 150
#> 29 119 2 7 2106 2963 857 979.5507 414.6998 150
#> 30 119 2 8 3006 3216 210 934.7593 642.2169 150
#> 31 119 2 9 3249 3563 314 512.3586 766.2387 150
#> 32 119 2 10 3606 3996 390 958.9479 279.0520 150
#> 33 119 2 11 4026 4212 186 792.5927 449.8534 150
#> 34 119 2 12 4256 4462 206 518.6455 786.5630 150
#> 35 119 2 13 4526 5066 540 1472.5263 764.4450 150
#> 36 119 3 1 0 184 184 985.9541 730.5059 150
#> 37 119 3 2 220 663 443 472.1210 752.5903 150
#> 38 119 3 3 730 1157 427 1464.3207 712.1701 150
#> 39 119 3 4 1207 1643 436 968.3952 420.4352 150
#> 40 119 3 5 1670 2093 423 987.8821 119.0672 150
#> 41 119 3 6 2413 3110 697 1516.4018 753.7404 150
#> 42 119 3 7 3180 3926 746 446.9097 755.2470 150
#> 43 119 3 8 3993 4749 756 1499.2257 763.7347 150
#> 44 119 3 9 4766 4989 223 1389.2216 699.5839 150
#> 45 119 3 10 5086 5689 603 400.2932 714.6202 150
#> 46 119 3 11 5746 6782 1036 981.1028 436.1339 150
#> 47 119 3 12 6802 7135 333 965.8765 299.7169 150
#> 48 119 3 13 7405 7569 164 480.4713 776.6188 150
#> 49 119 4 1 0 233 233 975.1394 746.1660 150
#> 50 119 4 2 270 1217 947 427.4524 747.2374 150
#> 51 119 4 3 1446 1850 404 1443.5337 745.5802 150
#> 52 119 4 4 1956 2523 567 537.5963 766.5012 150
#> 53 119 4 5 2546 2993 447 394.9710 748.7150 150
#> 54 119 4 6 3039 3256 217 907.8480 480.2590 150
#> 55 119 4 7 3296 4143 847 489.1409 746.8854 150
#> 56 119 4 8 4206 5416 1210 1455.0079 710.4423 150
#> 57 119 4 9 5479 6062 583 482.7405 764.8192 150
#> 58 119 4 10 6232 6622 390 1527.8785 738.6195 150
#> 59 119 4 11 6689 7355 666 450.4148 774.5962 150
#> 60 119 4 12 7559 7749 190 965.3538 383.7982 150
#> 61 119 4 13 7769 8182 413 969.9331 144.8225 150
#> 62 119 4 14 8228 8602 374 950.3255 536.0833 150
#> 63 119 4 15 8635 9052 417 959.0249 284.1379 150
#> 64 119 5 1 0 210 210 976.5170 750.1115 150
#> 65 119 5 2 250 477 227 492.1806 735.4280 150
#> 66 119 5 3 497 917 420 371.6881 770.6937 150
#> 67 119 5 4 937 1097 160 506.1086 783.0628 150
#> 68 119 5 5 1167 2033 866 1490.6202 762.1272 150
#> 69 119 5 6 2143 2720 577 1608.9363 777.1772 150
#> 70 119 5 7 2883 3386 503 456.9285 766.7936 150
#> 71 119 5 8 3456 3989 533 1515.0700 747.5654 150
#> 72 119 5 9 4009 4499 490 1430.7991 767.7693 150
#> 73 119 5 10 4569 4826 257 494.2187 762.7068 150
#> 74 119 5 11 4846 5283 437 348.8281 779.3330 150
#> 75 119 5 12 5306 5516 210 524.1386 751.4163 150
#> 76 119 5 13 5596 6599 1003 1503.1187 779.2121 150
#> 77 119 5 14 6686 7395 709 523.7418 762.9001 150
#> 78 119 5 15 7439 8212 773 966.2146 417.9438 150
#> 79 119 5 16 8239 9009 770 977.0369 149.6783 150
#> 80 119 5 17 9085 9562 477 471.5830 707.7810 150
#> 81 119 5 18 9605 10148 543 958.2060 327.6902 150
#> 82 119 5 19 10168 10425 257 980.4097 178.6096 150
#> 83 119 5 20 10625 11755 1130 392.2884 759.8224 150
#> 84 119 5 21 11801 12374 573 929.6616 319.2279 150
#> 85 119 5 22 12618 12834 216 352.4790 822.6459 150
#> 86 119 6 1 0 236 236 963.4609 755.3811 150
#> 87 119 6 2 256 430 174 962.7514 619.0616 150
#> 88 119 6 3 626 2263 1637 413.3652 790.0949 150
#> 89 119 6 4 2283 2433 150 592.6529 756.9108 150
#> 90 119 6 5 2453 3049 596 468.5629 739.4379 150
#> 91 119 6 6 3179 4086 907 1534.3101 784.0435 150
#> 92 119 6 7 4266 4605 339 991.8175 481.4887 150
#> 93 119 6 8 4672 5245 573 950.9352 199.0034 150
#> 94 119 6 9 5272 6778 1506 980.3947 430.5640 150
#> 95 119 6 10 6882 7558 676 1586.7961 735.2838 150
#> 96 119 6 11 7605 7828 223 1043.5969 359.9672 150
#> 97 119 6 12 7848 9161 1313 952.2730 181.9225 150
#> 98 119 6 13 9181 9361 180 948.9465 266.7840 150
#> 99 119 6 14 9425 10081 656 1535.9884 741.0666 150
#> 100 119 6 15 10104 10281 177 1418.5998 761.3546 150
#> 101 119 6 16 10348 11018 670 464.4767 786.1714 150
#> 102 119 6 17 11084 11278 194 1333.7384 779.3773 150
#> 103 119 6 18 11297 11581 284 1524.3373 751.4210 150
#> 104 119 6 19 11644 11994 350 440.0377 727.9646 150
#> 105 119 6 20 12067 12671 604 987.9853 309.9513 150
#> disp_tol
#> 1 100
#> 2 100
#> 3 100
#> 4 100
#> 5 100
#> 6 100
#> 7 100
#> 8 100
#> 9 100
#> 10 100
#> 11 100
#> 12 100
#> 13 100
#> 14 100
#> 15 100
#> 16 100
#> 17 100
#> 18 100
#> 19 100
#> 20 100
#> 21 100
#> 22 100
#> 23 100
#> 24 100
#> 25 100
#> 26 100
#> 27 100
#> 28 100
#> 29 100
#> 30 100
#> 31 100
#> 32 100
#> 33 100
#> 34 100
#> 35 100
#> 36 100
#> 37 100
#> 38 100
#> 39 100
#> 40 100
#> 41 100
#> 42 100
#> 43 100
#> 44 100
#> 45 100
#> 46 100
#> 47 100
#> 48 100
#> 49 100
#> 50 100
#> 51 100
#> 52 100
#> 53 100
#> 54 100
#> 55 100
#> 56 100
#> 57 100
#> 58 100
#> 59 100
#> 60 100
#> 61 100
#> 62 100
#> 63 100
#> 64 100
#> 65 100
#> 66 100
#> 67 100
#> 68 100
#> 69 100
#> 70 100
#> 71 100
#> 72 100
#> 73 100
#> 74 100
#> 75 100
#> 76 100
#> 77 100
#> 78 100
#> 79 100
#> 80 100
#> 81 100
#> 82 100
#> 83 100
#> 84 100
#> 85 100
#> 86 100
#> 87 100
#> 88 100
#> 89 100
#> 90 100
#> 91 100
#> 92 100
#> 93 100
#> 94 100
#> 95 100
#> 96 100
#> 97 100
#> 98 100
#> 99 100
#> 100 100
#> 101 100
#> 102 100
#> 103 100
#> 104 100
#> 105 100
# }