Detects fixations by assessing dispersion of the eye position, using a method that is similar to that proposed by Salvucci & Goldberg (1996). Evaluates the maximum dispersion (distance) between x/y coordinates across a window of data. Looks for sufficient periods in which this maximum dispersion is below the specified dispersion tolerance. NAs are considered breaks in the data and are not permitted within a valid fixation period. Runs the interpolation algorithm by default to fix small breaks in the data.
Usage
fixation_dispersion(
data,
min_dur = 150,
disp_tol = 100,
run_interp = TRUE,
NA_tol = 0.25,
progress = TRUE,
participant_ID = "participant_ID"
)Arguments
- data
A dataframe with raw data (time, x, y, trial) for one participant (the standardised raw data form for eyetools)
- min_dur
Minimum duration (in milliseconds) of period over which fixations are assessed
- disp_tol
Maximum tolerance (in pixels) for the dispersion of values allowed over fixation period
- run_interp
include a call to eyetools::interpolate on each trial
- NA_tol
the proportion of NAs tolerated within any window of samples that is evaluated as a fixation
- 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)
fixation_dispersion(data, participant_ID = "pNum")
#> pNum trial fix_n start end duration x y prop_NA min_dur disp_tol
#> 1 118 1 1 0 180 180 961 812 0.000 150 100
#> 2 118 1 2 190 433 243 959 585 0.000 150 100
#> 3 118 1 3 437 750 313 960 477 0.000 150 100
#> 4 118 1 4 783 1013 230 561 838 0.000 150 100
#> 5 118 1 5 1016 1183 167 519 829 0.000 150 100
#> 6 118 1 6 1210 1380 170 915 555 0.000 150 100
#> 7 118 1 7 1383 1720 337 951 475 0.000 150 100
#> 8 118 1 8 1736 2190 454 966 170 0.000 150 100
#> 9 118 1 9 2236 2693 457 1537 826 0.000 150 100
#> 10 118 1 10 2743 2926 183 968 355 0.000 150 100
#> 11 118 1 11 2930 3110 180 949 452 0.000 150 100
#> 12 118 1 12 3119 3356 237 966 140 0.000 150 100
#> 13 118 1 13 3359 3676 317 932 106 0.000 150 100
#> 14 118 1 14 3726 3906 180 1486 791 0.000 150 100
#> 15 118 1 15 3909 4223 314 1533 815 0.000 150 100
#> 16 118 1 16 4269 4479 210 975 338 0.000 150 100
#> 17 118 1 17 4483 4643 160 961 490 0.000 150 100
#> 18 118 1 18 4779 5339 560 956 482 0.000 150 100
#> 19 118 1 19 5379 6166 787 507 841 0.000 150 100
#> 20 118 1 20 6169 6792 623 516 872 0.000 150 100
#> 21 118 1 21 6819 6999 180 920 642 0.000 150 100
#> 22 118 1 22 7126 7356 230 1010 616 0.000 150 100
#> 23 118 1 23 7359 7602 243 937 625 0.000 150 100
#> 24 118 1 24 7632 8009 377 512 819 0.000 150 100
#> 25 118 1 25 8186 8336 150 499 871 0.239 150 100
#> 26 118 1 26 8339 9295 956 509 857 0.000 150 100
#> 27 118 1 27 9325 9529 204 937 494 0.000 150 100
#> 28 118 1 28 9532 10069 537 939 451 0.000 150 100
#> 29 118 1 29 10082 10439 357 948 130 0.000 150 100
#> 30 118 1 30 10495 10705 210 555 801 0.000 150 100
#> 31 118 1 31 10735 11122 387 941 463 0.000 150 100
#> 32 118 1 32 11129 11912 783 951 282 0.000 150 100
#> 33 118 1 33 11915 12142 227 960 430 0.000 150 100
#> 34 118 1 34 12185 12532 347 1496 824 0.000 150 100
#> 35 118 1 35 12535 12685 150 1539 820 0.000 150 100
#> 36 118 1 36 12752 12975 223 1550 840 0.000 150 100
#> 37 118 1 37 13018 13245 227 968 416 0.000 150 100
#> 38 118 1 38 13248 13461 213 936 473 0.000 150 100
#> 39 118 2 1 0 180 180 959 776 0.000 150 100
#> 40 118 2 2 183 369 186 972 632 0.000 150 100
#> 41 118 2 3 396 679 283 1470 806 0.000 150 100
#> 42 118 2 4 683 1146 463 1533 820 0.000 150 100
#> 43 118 2 5 1199 1429 230 949 396 0.000 150 100
#> 44 118 2 6 1439 1796 357 944 148 0.000 150 100
#> 45 118 2 7 1809 1986 177 942 477 0.000 150 100
#> 46 118 2 8 2019 2263 244 498 812 0.000 150 100
#> 47 118 2 9 2326 2626 300 490 823 0.000 150 100
#> 48 118 2 10 2676 2859 183 932 212 0.000 150 100
#> 49 118 2 11 2863 3109 246 947 150 0.000 150 100
#> 50 118 2 12 3122 3542 420 954 457 0.000 150 100
#> 51 118 2 13 3556 3929 373 946 183 0.000 150 100
#> 52 118 2 14 3932 4269 337 937 290 0.000 150 100
#> 53 118 2 15 4272 4859 587 936 182 0.000 150 100
#> 54 118 2 16 4862 5142 280 943 263 0.000 150 100
#> 55 118 2 17 5182 5342 160 1451 842 0.000 150 100
#> 56 118 2 18 5389 5582 193 532 838 0.000 150 100
#> 57 118 2 19 5585 5765 180 474 813 0.000 150 100
#> 58 118 2 20 5912 6232 320 944 155 0.000 150 100
#> 59 118 2 21 6282 6752 470 478 805 0.000 150 100
#> 60 118 2 22 6785 7199 414 953 475 0.000 150 100
#> 61 118 2 23 7249 7635 386 1539 809 0.000 150 100
#> 62 118 3 1 230 380 150 971 675 0.000 150 100
#> 63 118 3 2 393 683 290 963 458 0.000 150 100
#> 64 118 3 3 696 936 240 975 181 0.000 150 100
#> 65 118 3 4 976 1203 227 1499 841 0.000 150 100
#> 66 118 3 5 1250 1466 216 518 858 0.000 150 100
#> 67 118 3 6 1470 1830 360 486 820 0.000 150 100
#> 68 118 3 7 1863 2063 200 933 469 0.000 150 100
#> 69 118 3 8 2066 2273 207 963 461 0.000 150 100
#> 70 118 3 9 2283 2626 343 970 187 0.000 150 100
#> 71 118 3 10 2643 2989 346 952 476 0.000 150 100
#> 72 118 3 11 3033 3549 516 1519 850 0.000 150 100
#> 73 118 3 12 3706 3856 150 940 613 0.239 150 100
#> 74 118 3 13 3863 4116 253 963 472 0.000 150 100
#> 75 118 3 14 4126 4549 423 948 304 0.000 150 100
#> 76 118 3 15 4553 4766 213 943 441 0.000 150 100
#> 77 118 3 16 4773 5006 233 949 208 0.000 150 100
#> 78 118 3 17 5009 5193 184 961 180 0.000 150 100
#> 79 118 4 1 0 166 166 959 813 0.000 150 100
#> 80 118 4 2 186 343 157 1403 801 0.000 150 100
#> 81 118 4 3 346 543 197 1504 801 0.000 150 100
#> 82 118 4 4 576 753 177 1026 393 0.000 150 100
#> 83 118 4 5 756 920 164 963 452 0.000 150 100
#> 84 118 4 6 1110 1543 433 507 841 0.000 150 100
#> 85 118 4 7 1630 1856 226 1478 871 0.000 150 100
#> 86 118 4 8 1860 2389 529 1527 838 0.000 150 100
#> 87 118 4 9 2439 2590 151 616 811 0.000 150 100
#> 88 118 4 10 2593 3353 760 510 829 0.000 150 100
#> 89 118 4 11 3393 3693 300 981 442 0.000 150 100
#> 90 118 4 12 3706 4159 453 960 156 0.000 150 100
#> 91 118 4 13 4206 4363 157 1394 776 0.000 150 100
#> 92 118 4 14 4366 4593 227 1499 810 0.000 150 100
#> 93 118 4 15 4779 4929 150 531 864 0.239 150 100
#> 94 118 4 16 4933 5459 526 510 841 0.000 150 100
#> 95 118 4 17 5506 5656 150 894 203 0.000 150 100
#> 96 118 4 18 5659 5842 183 948 166 0.000 150 100
#> 97 118 4 19 5852 6166 314 956 473 0.000 150 100
#> 98 118 4 20 6209 6722 513 1518 864 0.000 150 100
#> 99 118 4 21 6726 8009 1283 1533 848 0.000 150 100
#> 100 118 4 22 8062 8605 543 535 899 0.000 150 100
#> 101 118 4 23 8662 8919 257 1505 866 0.000 150 100
#> 102 118 4 24 8962 9115 153 944 393 0.000 150 100
#> 103 118 4 25 9189 9365 176 950 266 0.000 150 100
#> 104 118 4 26 9369 9908 539 954 272 0.000 150 100
#> 105 118 5 1 186 439 253 643 805 0.000 150 100
#> 106 118 5 2 463 769 306 918 453 0.000 150 100
#> 107 118 5 3 803 953 150 678 808 0.000 150 100
#> 108 118 5 4 1106 1273 167 1477 868 0.000 150 100
#> 109 118 5 5 1276 1666 390 1524 833 0.000 150 100
#> 110 118 5 6 1706 1959 253 983 432 0.000 150 100
#> 111 118 5 7 1976 2319 343 950 185 0.000 150 100
#> 112 118 5 8 2326 2609 283 960 341 0.000 150 100
#> 113 118 5 9 2649 2833 184 1516 775 0.000 150 100
#> 114 118 5 10 2836 2999 163 1539 813 0.000 150 100
#> 115 118 5 11 3036 3226 190 985 346 0.000 150 100
#> 116 118 5 12 3229 3686 457 945 285 0.000 150 100
#> 117 118 5 13 3729 3926 197 1513 807 0.000 150 100
#> 118 118 5 14 3972 4276 304 956 164 0.000 150 100
#> 119 118 6 1 0 177 177 967 804 0.000 150 100
#> 120 118 6 2 340 580 240 947 438 0.000 150 100
#> 121 118 6 3 627 1160 533 1507 821 0.000 150 100
#> 122 118 6 4 1210 1526 316 534 812 0.000 150 100
#> 123 118 6 5 1710 1966 256 943 156 0.000 150 100
#> 124 118 6 6 1983 2373 390 947 467 0.000 150 100
#> 125 118 6 7 2386 2826 440 948 168 0.000 150 100
#> 126 118 6 8 2843 3330 487 936 444 0.000 150 100
#> 127 118 6 9 3406 3759 353 1528 807 0.000 150 100
#> 128 118 6 10 3813 3993 180 521 827 0.000 150 100
#> 129 118 6 11 3996 4289 293 480 810 0.000 150 100
#> 130 118 6 12 4319 4503 184 952 544 0.000 150 100
#> 131 118 6 13 4506 4666 160 966 460 0.000 150 100
#> 132 118 6 14 4669 5076 407 955 265 0.000 150 100
#> 133 119 1 1 0 229 229 971 764 0.000 150 100
#> 134 119 1 2 233 419 186 937 644 0.000 150 100
#> 135 119 1 3 429 963 534 974 420 0.000 150 100
#> 136 119 1 4 1003 1389 386 411 753 0.000 150 100
#> 137 119 1 5 1413 1563 150 803 510 0.000 150 100
#> 138 119 1 6 1579 1862 283 970 308 0.000 150 100
#> 139 119 1 7 1876 2066 190 979 577 0.000 150 100
#> 140 119 1 8 2099 3026 927 1499 765 0.000 150 100
#> 141 119 1 9 3082 3296 214 447 735 0.000 150 100
#> 142 119 1 10 3319 3482 163 960 525 0.000 150 100
#> 143 119 1 11 3486 4162 676 964 470 0.000 150 100
#> 144 119 1 12 4195 4485 290 472 748 0.000 150 100
#> 145 119 1 13 4489 4655 166 445 782 0.000 150 100
#> 146 119 1 14 4709 5005 296 1476 755 0.000 150 100
#> 147 119 1 15 5138 5289 151 391 760 0.239 150 100
#> 148 119 1 16 5292 6728 1436 412 779 0.000 150 100
#> 149 119 1 17 6732 7305 573 506 728 0.000 150 100
#> 150 119 1 18 7361 7598 237 1478 768 0.000 150 100
#> 151 119 1 19 7605 7888 283 1584 742 0.000 150 100
#> 152 119 1 20 7931 8085 154 1020 298 0.000 150 100
#> 153 119 1 21 8088 8448 360 988 336 0.000 150 100
#> 154 119 1 22 8488 8731 243 368 677 0.000 150 100
#> 155 119 1 23 8894 9111 217 968 315 0.000 150 100
#> 156 119 1 24 9148 9388 240 471 738 0.000 150 100
#> 157 119 1 25 9391 9608 217 431 816 0.000 150 100
#> 158 119 1 26 9631 9814 183 888 529 0.000 150 100
#> 159 119 1 27 9818 9988 170 939 463 0.000 150 100
#> 160 119 2 1 0 163 163 963 800 0.000 150 100
#> 161 119 2 2 190 566 376 491 749 0.000 150 100
#> 162 119 2 3 620 783 163 1430 766 0.000 150 100
#> 163 119 2 4 786 953 167 1537 742 0.000 150 100
#> 164 119 2 5 1263 1493 230 999 401 0.000 150 100
#> 165 119 2 6 1500 1680 180 953 268 0.000 150 100
#> 166 119 2 7 1716 2093 377 949 181 0.000 150 100
#> 167 119 2 8 2106 2739 633 977 451 0.000 150 100
#> 168 119 2 9 2759 2936 177 990 274 0.000 150 100
#> 169 119 2 10 2996 3213 217 935 639 0.000 150 100
#> 170 119 2 11 3243 3566 323 514 765 0.000 150 100
#> 171 119 2 12 3649 3996 347 959 285 0.000 150 100
#> 172 119 2 13 4016 4209 193 795 448 0.000 150 100
#> 173 119 2 14 4249 4462 213 519 785 0.000 150 100
#> 174 119 2 15 4516 5066 550 1472 765 0.000 150 100
#> 175 119 3 1 0 187 187 985 731 0.000 150 100
#> 176 119 3 2 213 670 457 474 753 0.000 150 100
#> 177 119 3 3 720 1163 443 1464 713 0.000 150 100
#> 178 119 3 4 1193 1647 454 969 420 0.000 150 100
#> 179 119 3 5 1667 2016 349 989 123 0.000 150 100
#> 180 119 3 6 2403 2666 263 1498 712 0.000 150 100
#> 181 119 3 7 2670 3116 446 1527 781 0.000 150 100
#> 182 119 3 8 3170 3759 589 464 759 0.000 150 100
#> 183 119 3 9 3763 3929 166 389 744 0.000 150 100
#> 184 119 3 10 3983 4296 313 1461 745 0.000 150 100
#> 185 119 3 11 4299 4753 454 1524 776 0.000 150 100
#> 186 119 3 12 4756 4989 233 1391 700 0.000 150 100
#> 187 119 3 13 5109 5689 580 399 715 0.000 150 100
#> 188 119 3 14 5736 6786 1050 981 436 0.000 150 100
#> 189 119 3 15 6882 7135 253 963 312 0.000 150 100
#> 190 119 3 16 7402 7569 167 481 776 0.000 150 100
#> 191 119 4 1 0 237 237 974 746 0.000 150 100
#> 192 119 4 2 263 533 270 502 735 0.000 150 100
#> 193 119 4 3 537 1226 689 400 752 0.000 150 100
#> 194 119 4 4 1230 1390 160 496 770 0.000 150 100
#> 195 119 4 5 1436 1856 420 1441 746 0.000 150 100
#> 196 119 4 6 1946 2526 580 539 766 0.000 150 100
#> 197 119 4 7 2530 2803 273 409 727 0.000 150 100
#> 198 119 4 8 2806 2996 190 382 777 0.000 150 100
#> 199 119 4 9 3026 3259 233 905 480 0.000 150 100
#> 200 119 4 10 3289 3753 464 493 732 0.000 150 100
#> 201 119 4 11 3756 4143 387 486 764 0.000 150 100
#> 202 119 4 12 4196 5419 1223 1455 711 0.000 150 100
#> 203 119 4 13 5472 6066 594 484 765 0.000 150 100
#> 204 119 4 14 6225 6625 400 1527 738 0.000 150 100
#> 205 119 4 15 6675 6929 254 488 776 0.000 150 100
#> 206 119 4 16 6932 7359 427 431 774 0.000 150 100
#> 207 119 4 17 7545 7749 204 968 384 0.000 150 100
#> 208 119 4 18 7762 7958 196 971 121 0.000 150 100
#> 209 119 4 19 7962 8185 223 969 167 0.000 150 100
#> 210 119 4 20 8212 8605 393 950 534 0.000 150 100
#> 211 119 4 21 8615 9052 437 959 285 0.000 150 100
#> 212 119 5 1 0 214 214 976 750 0.000 150 100
#> 213 119 5 2 240 477 237 494 736 0.000 150 100
#> 214 119 5 3 484 927 443 374 769 0.000 150 100
#> 215 119 5 4 930 1100 170 507 781 0.000 150 100
#> 216 119 5 5 1153 1997 844 1488 761 0.000 150 100
#> 217 119 5 6 2140 2723 583 1610 774 0.000 150 100
#> 218 119 5 7 2916 3390 474 458 769 0.000 150 100
#> 219 119 5 8 3446 3680 234 1469 734 0.000 150 100
#> 220 119 5 9 3683 3996 313 1548 759 0.000 150 100
#> 221 119 5 10 4003 4489 486 1432 768 0.000 150 100
#> 222 119 5 11 4563 4826 263 496 763 0.000 150 100
#> 223 119 5 12 4836 5293 457 351 779 0.000 150 100
#> 224 119 5 13 5296 5519 223 524 752 0.000 150 100
#> 225 119 5 14 5583 5779 196 1453 751 0.000 150 100
#> 226 119 5 15 5782 6396 614 1493 767 0.000 150 100
#> 227 119 5 16 6699 6909 210 546 763 0.000 150 100
#> 228 119 5 17 6912 7395 483 514 765 0.000 150 100
#> 229 119 5 18 7425 8215 790 966 418 0.000 150 100
#> 230 119 5 19 8229 9009 780 977 151 0.000 150 100
#> 231 119 5 20 9065 9565 500 471 706 0.000 150 100
#> 232 119 5 21 9595 9898 303 933 344 0.000 150 100
#> 233 119 5 22 9902 10158 256 988 309 0.000 150 100
#> 234 119 5 23 10162 10432 270 980 180 0.000 150 100
#> 235 119 5 24 10612 11101 489 429 744 0.000 150 100
#> 236 119 5 25 11105 11751 646 366 770 0.000 150 100
#> 237 119 5 26 11791 12195 404 917 319 0.000 150 100
#> 238 119 5 27 12198 12378 180 954 321 0.000 150 100
#> 239 119 5 28 12624 12834 210 352 821 0.000 150 100
#> 240 119 6 1 0 243 243 963 754 0.000 150 100
#> 241 119 6 2 246 433 187 962 619 0.000 150 100
#> 242 119 6 3 440 593 153 947 410 0.000 150 100
#> 243 119 6 4 626 1563 937 402 767 0.000 150 100
#> 244 119 6 5 1566 2269 703 429 821 0.000 150 100
#> 245 119 6 6 2273 2446 173 586 757 0.000 150 100
#> 246 119 6 7 2449 2876 427 493 743 0.000 150 100
#> 247 119 6 8 2879 3053 174 407 731 0.000 150 100
#> 248 119 6 9 3189 3629 440 1494 791 0.000 150 100
#> 249 119 6 10 3632 4092 460 1579 775 0.000 150 100
#> 250 119 6 11 4256 4429 173 1008 507 0.000 150 100
#> 251 119 6 12 4432 4609 177 979 458 0.000 150 100
#> 252 119 6 13 4669 5249 580 951 200 0.000 150 100
#> 253 119 6 14 5259 6778 1519 980 430 0.000 150 100
#> 254 119 6 15 6888 7232 344 1626 758 0.000 150 100
#> 255 119 6 16 7235 7558 323 1557 723 0.000 150 100
#> 256 119 6 17 7595 7832 237 1045 360 0.000 150 100
#> 257 119 6 18 7838 8141 303 973 243 0.000 150 100
#> 258 119 6 19 8145 9171 1026 946 165 0.000 150 100
#> 259 119 6 20 9175 9365 190 950 267 0.000 150 100
#> 260 119 6 21 9421 9684 263 1508 707 0.000 150 100
#> 261 119 6 22 9688 10094 406 1555 765 0.000 150 100
#> 262 119 6 23 10098 10288 190 1417 762 0.000 150 100
#> 263 119 6 24 10338 10561 223 516 759 0.000 150 100
#> 264 119 6 25 10564 11021 457 441 799 0.000 150 100
#> 265 119 6 26 11074 11271 197 1330 779 0.000 150 100
#> 266 119 6 27 11287 11584 297 1522 752 0.000 150 100
#> 267 119 6 28 11644 11997 353 440 728 0.000 150 100
#> 268 119 6 29 12064 12224 160 993 341 0.000 150 100
#> 269 119 6 30 12227 12671 444 986 300 0.000 150 100
# }