Analyses total time on defined AOI regions across trials. Works with fixation and raw data as the input (must use one or the other, not both).
Usage
AOI_time(
data,
data_type = NULL,
AOIs,
AOI_names = NULL,
sample_rate = NULL,
as_prop = FALSE,
trial_time = NULL,
participant_ID = "participant_ID"
)Arguments
- data
A dataframe of either fixation data (from fix_dispersion) or raw data
- data_type
Whether data is a fixation ("fix") or raw data ("raw")
- AOIs
A dataframe of areas of interest (AOIs), with one row per AOI (x, y, width_radius, height).
- AOI_names
An optional vector of AOI names to replace the default "AOI_1", "AOI_2", etc.
- sample_rate
Optional sample rate of the eye-tracker (Hz) for use with data. If not supplied, the sample rate will be estimated from the time column and the number of samples.
- as_prop
whether to return time in AOI as a proportion of the total time of trial
- trial_time
needed if as_prop is set to TRUE. a vector of the time taken in each trial. Equal to the length of x trials by y participants in the dataset
- participant_ID
the variable that determines the participant identifier. If no column present, assumes a single participant
Value
a dataframe containing the time on the passed AOIs for each trial. One column for each AOI separated by trial.
Details
AOI_time 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
Examples
# \donttest{
data <- combine_eyes(HCL)
fix_d <- fixation_dispersion(data, participant_ID = "pNum")
# fixation data
AOI_time(data = fix_d, data_type = "fix", AOIs = HCL_AOIs, participant_ID = "pNum")
#> pNum trial AOI time
#> 1 118 1 AOI_1 3500
#> 2 118 2 AOI_1 1400
#> 3 118 3 AOI_1 576
#> 4 118 4 AOI_1 2563
#> 5 118 5 AOI_1 253
#> 6 118 6 AOI_1 789
#> 7 118 1 AOI_2 1598
#> 8 118 2 AOI_2 1292
#> 9 118 3 AOI_2 743
#> 10 118 4 AOI_2 3574
#> 11 118 5 AOI_2 1101
#> 12 118 6 AOI_2 909
#> 13 118 1 AOI_3 5886
#> 14 118 2 AOI_3 3924
#> 15 118 3 AOI_3 2932
#> 16 118 4 AOI_3 2609
#> 17 118 5 AOI_3 2136
#> 18 118 6 AOI_3 2380
#> 19 119 1 AOI_1 3656
#> 20 119 2 AOI_1 912
#> 21 119 3 AOI_1 1959
#> 22 119 4 AOI_1 4288
#> 23 119 5 AOI_1 4805
#> 24 119 6 AOI_1 3447
#> 25 119 1 AOI_2 1743
#> 26 119 2 AOI_2 880
#> 27 119 3 AOI_2 2152
#> 28 119 4 AOI_2 2043
#> 29 119 5 AOI_2 3270
#> 30 119 6 AOI_2 2920
#> 31 119 1 AOI_3 2394
#> 32 119 2 AOI_3 1944
#> 33 119 3 AOI_3 2106
#> 34 119 4 AOI_3 1293
#> 35 119 5 AOI_3 2983
#> 36 119 6 AOI_3 4962
#raw data
AOI_time(data = data, data_type = "raw", AOIs = HCL_AOIs, participant_ID = "pNum")
#> pNum trial AOI time
#> 1 118 1 AOI_1 3653
#> 2 118 2 AOI_1 1410
#> 3 118 3 AOI_1 590
#> 4 118 4 AOI_1 2576
#> 5 118 5 AOI_1 347
#> 6 118 6 AOI_1 817
#> 7 118 1 AOI_2 1716
#> 8 118 2 AOI_2 1373
#> 9 118 3 AOI_2 797
#> 10 118 4 AOI_2 3766
#> 11 118 5 AOI_2 1156
#> 12 118 6 AOI_2 923
#> 13 118 1 AOI_3 6019
#> 14 118 2 AOI_3 4199
#> 15 118 3 AOI_3 3083
#> 16 118 4 AOI_3 2923
#> 17 118 5 AOI_3 2363
#> 18 118 6 AOI_3 2736
#> 19 119 1 AOI_1 3829
#> 20 119 2 AOI_1 953
#> 21 119 3 AOI_1 2016
#> 22 119 4 AOI_1 4366
#> 23 119 5 AOI_1 5022
#> 24 119 6 AOI_1 3506
#> 25 119 1 AOI_2 1806
#> 26 119 2 AOI_2 1047
#> 27 119 3 AOI_2 2333
#> 28 119 4 AOI_2 2120
#> 29 119 5 AOI_2 3723
#> 30 119 6 AOI_2 3136
#> 31 119 1 AOI_3 2553
#> 32 119 2 AOI_3 2180
#> 33 119 3 AOI_3 2440
#> 34 119 4 AOI_3 1520
#> 35 119 5 AOI_3 3203
#> 36 119 6 AOI_3 5059
#as proportional data
AOI_time(data = fix_d, data_type = "fix", AOIs = HCL_AOIs, participant_ID = "pNum",
as_prop = TRUE, trial_time = HCL_behavioural$RT)
#> pNum trial AOI time
#> 1 118 1 AOI_1 0.25993316
#> 2 118 1 AOI_2 0.11867805
#> 3 118 1 AOI_3 0.43713331
#> 4 118 2 AOI_1 0.17958618
#> 5 118 2 AOI_2 0.16573239
#> 6 118 2 AOI_3 0.50335441
#> 7 118 3 AOI_1 0.10936432
#> 8 118 3 AOI_2 0.14107238
#> 9 118 3 AOI_3 0.55669477
#> 10 118 4 AOI_1 0.25859894
#> 11 118 4 AOI_2 0.36060579
#> 12 118 4 AOI_3 0.26324021
#> 13 118 5 AOI_1 0.05718548
#> 14 118 5 AOI_2 0.24885855
#> 15 118 5 AOI_3 0.48279915
#> 16 118 6 AOI_1 0.15102791
#> 17 118 6 AOI_2 0.17399793
#> 18 118 6 AOI_3 0.45557215
#> 19 119 1 AOI_1 0.35980711
#> 20 119 1 AOI_2 0.17153823
#> 21 119 1 AOI_3 0.23560673
#> 22 119 2 AOI_1 0.17986747
#> 23 119 2 AOI_2 0.17355633
#> 24 119 2 AOI_3 0.38340170
#> 25 119 3 AOI_1 0.25872657
#> 26 119 3 AOI_2 0.28421623
#> 27 119 3 AOI_3 0.27814097
#> 28 119 4 AOI_1 0.47366037
#> 29 119 4 AOI_2 0.22567354
#> 30 119 4 AOI_3 0.14282716
#> 31 119 5 AOI_1 0.37422118
#> 32 119 5 AOI_2 0.25467290
#> 33 119 5 AOI_3 0.23232087
#> 34 119 6 AOI_1 0.27193121
#> 35 119 6 AOI_2 0.23035658
#> 36 119 6 AOI_3 0.39144841
# }