diff --git a/DESCRIPTION b/DESCRIPTION index b2bbe63..9f8b611 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: eyetools Title: Tools for eye data analysis -Version: 0.6.0 +Version: 0.6.1 Authors@R: c( person("Beesley", "Tom", email = "t.beesley@lancaster.ac.uk", role = c("aut", "cre")), person("Ivory", "Matthew", email = "matthew.ivory@lancaster.ac.uk", role = "aut")) diff --git a/NEWS.md b/NEWS.md index 2e291b7..2faeebb 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,5 @@ +# eyetools 0.6.1 + # eyetools 0.6.0 # eyetools 0.5.1 diff --git a/R/AOI_seq.R b/R/AOI_seq.R index 7c6b15e..3060a04 100644 --- a/R/AOI_seq.R +++ b/R/AOI_seq.R @@ -41,7 +41,7 @@ AOI_seq <- function(data, data <- stack(split_list_names) data <- data.frame(trial = as.numeric(data$ind), - AOI = as.numeric(data$value)) + AOI = data$value) # add in entry_n by way of indexing each trial get_row_n <- function(i) { diff --git a/R/conditional_transform.R b/R/conditional_transform.R index 88cce90..5a50429 100644 --- a/R/conditional_transform.R +++ b/R/conditional_transform.R @@ -15,10 +15,14 @@ #' @export #' #' @examples -#' 3 +#' conditional_transform(example_counterbalance, flip = "x", cond_column = "cue_order", cond_values = 2) conditional_transform <- function(data, flip = c("x", "y"), cond_column, cond_values, resolution_x = 1920, resolution_y = 1080) { + if(missing(cond_column)) { + stop("missing column names. Please check your data and the documentation") + } + if(sum(colnames(data) %in% c("x", "y", cond_column)) != 3) { stop("missing column names. Please check your data and the documentation") } diff --git a/README.Rmd b/README.Rmd index db21ea4..acada8a 100644 --- a/README.Rmd +++ b/README.Rmd @@ -41,7 +41,7 @@ Available functions: | `AOI_time()` | Time on AOIs; works with rectangular and circular AOIs; works with raw and fixation data | | `combine_eyes()` | Combines binocular data (i.e., average or "best eye") | | `compare_algorithms()` | Provides a comparison between the dispersion and VTI fixation algorithms with correlations and plot | -| `conditional_transform` | Implements a single-axis flip for specific trials to normalise data with counterbalanced designs | +| `conditional_transform()` | Implements a single-axis flip for specific trials to normalise data with counterbalanced designs | | `fixation_dispersion()` | Dispersion algorithm for fixation detection | | `fixation_VTI()` | An inverse saccade algorithm for fixation detection | | `hdf5_to_csv()` | converts eyetracking data retrieved from TOBII eyetrackers to csv | @@ -146,7 +146,7 @@ comparison <- compare_algorithms(raw_data_f, min_dur = 120, disp_tol = 100, min_ ``` -The code used to produce the plots within `compare_algorithms()` is shown below +The code used to produce the plots within `compare_algorithms()` is shown below: ```{r eval=FALSE} @@ -159,6 +159,16 @@ ggplot(comparison$plot, ``` +#### Controlling for counterbalanced data + +Where the experiment includes counterbalancing of predictive and non-predictive cues, currently eyetools can normalise this data for a single axis (either a horizontal or vertical flip) using the function `conditional_transform()`. As of version 0.6.0, it cannot rotate data. `conditional_transform()` takes the data that requires data to have a column that specifies the ordering of the cues, in the example data below this is handled with the variable `cue_order` that is either a 1 or 2 depending on which side of the x midline the predictive cue is presented. The flip is specified as being across the x midline and the values to flip are also specified (note: this can take multiple values). + +```{r} + +conditional_transform(example_counterbalance, flip = "x", cond_column = "cue_order", cond_values = 2) + +``` + ### Plotting data @@ -174,7 +184,7 @@ t_raw <- dplyr::filter(example_raw_sac, trial == 9) t_fix <- fixation_dispersion(t_raw, disp_tol = 100, min_dur = 150) raw_plot <- plot_spatial(raw_data = t_raw, plot_header = TRUE) -fixation_plot <- plot_spatial(raw_data = t_raw, fixation_data = t_fix) +fixation_plot <- plot_spatial(raw_data = t_raw, fix_data = t_fix) raw_plot/fixation_plot # combined plot with patchwork @@ -217,7 +227,7 @@ t_raw <- filter(example_raw_sac, trial == 9) # single trial for plotting purpose # process fixations t_fix <- fixation_dispersion(t_raw, disp_tol = 100, min_dur = 150) -plot_spatial(raw_data = t_raw, fixation_data = t_fix, AOIs = AOI_regions) +plot_spatial(raw_data = t_raw, fix_data = t_fix, AOIs = AOI_regions) ``` @@ -237,7 +247,7 @@ t_raw <- filter(example_raw_sac, between(trial,1,10)) # process fixations t_fix <- fixation_dispersion(t_raw, disp_tol = 100, min_dur = 150) -plot_spatial(raw_data = t_raw, fixation_data = t_fix, AOIs = AOI_regions) +plot_spatial(raw_data = t_raw, fix_data = t_fix, AOIs = AOI_regions) ``` @@ -256,7 +266,7 @@ t_raw <- filter(example_raw_sac, trial == 13) # process fixations t_fix <- fixation_dispersion(t_raw, disp_tol = 100, min_dur = 150) -plot_spatial(raw_data = t_raw, fixation_data = t_fix, AOIs = AOI_regions) +plot_spatial(raw_data = t_raw, fix_data = t_fix, AOIs = AOI_regions) AOI_time(t_fix, AOIs = AOI_regions) @@ -265,7 +275,7 @@ AOI_time(t_fix, AOIs = AOI_regions) ### Processing saccades -The function `VTI_saccade()` provides a means of processing the data for saccades, based on a "velocity threshold identification" algorithm, as described in Salvucci and Goldberg (2000). As described above, it is wise to use the `smoother()` function on the data first. THe sample rate can be set if known, or can be approximated using the timestamps in the data. The threshold determines the degrees of visual angle per second needed to indicate the presence of a saccadic eye-movement. +The function `saccade_VTI()` provides a means of processing the data for saccades, based on a "velocity threshold identification" algorithm, as described in Salvucci and Goldberg (2000). As described above, it is wise to use the `smoother()` function on the data first. THe sample rate can be set if known, or can be approximated using the timestamps in the data. The threshold determines the degrees of visual angle per second needed to indicate the presence of a saccadic eye-movement. ```{r} @@ -273,7 +283,7 @@ t_raw <- filter(example_raw_sac, between(trial,1,10)) t_smooth <- smoother(t_raw) -VTI_saccade(t_smooth, sample_rate = 300) +saccade_VTI(t_smooth, sample_rate = 300) @@ -287,9 +297,9 @@ t_smooth <- filter(t_smooth, trial == 8) t_fix <- fixation_dispersion(t_smooth, disp_tol = 100, min_dur = 150) -t_sac <- VTI_saccade(t_smooth, sample_rate = 300, threshold = 100) +t_sac <- saccade_VTI(t_smooth, sample_rate = 300, threshold = 100) -plot_spatial(raw_data = t_smooth, fixation_data = t_fix, sac_data = t_sac) +plot_spatial(raw_data = t_smooth, fix_data = t_fix, sac_data = t_sac) ``` diff --git a/man/conditional_transform.Rd b/man/conditional_transform.Rd index 4c6086f..304cc73 100644 --- a/man/conditional_transform.Rd +++ b/man/conditional_transform.Rd @@ -35,5 +35,5 @@ The function takes the dataframe and performs a single axis flip based on the va The primary use of this function is to correct or normalise the data when counterbalancing stimulus placement within experiments (e.g., having a target stimulus appear on the left and right equally often) } \examples{ -3 +conditional_transform(example_counterbalance, flip = "x", cond_column = "cue_order", cond_values = 2) } diff --git a/man/explore_dispersion_tolerance.Rd b/man/explore_dispersion_tolerance.Rd new file mode 100644 index 0000000..348cf1c --- /dev/null +++ b/man/explore_dispersion_tolerance.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/explore_dispersion_tolerance.R +\name{explore_dispersion_tolerance} +\alias{explore_dispersion_tolerance} +\title{Fixation detection using inverse saccade identification} +\usage{ +explore_dispersion_tolerance( + data, + algorithm = c("dispersion", "VTI", "both"), + tolerance_min = 75, + tolerance_max = 120, + step = 5 +) +} +\arguments{ +\item{data}{A dataframe with raw data (time, x, y, trial) for one participant} + +\item{algorithm}{A string of either "dispersion", "VTI", or "both" to specify which algorithm to test} + +\item{tolerance_min}{the minimum dispersion tolerance to test} + +\item{tolerance_max}{the maximum dispersion tolerance to test} + +\item{step}{the step to take between the minimum and maximum tolerance values to explore} +} +\description{ +Description +} diff --git a/man/figures/unnamed-chunk-10-1.png b/man/figures/unnamed-chunk-10-1.png new file mode 100644 index 0000000..bbdd291 Binary files /dev/null and b/man/figures/unnamed-chunk-10-1.png differ diff --git a/man/figures/unnamed-chunk-15-1.png b/man/figures/unnamed-chunk-15-1.png new file mode 100644 index 0000000..17e1083 Binary files /dev/null and b/man/figures/unnamed-chunk-15-1.png differ diff --git a/man/figures/unnamed-chunk-16-1.png b/man/figures/unnamed-chunk-16-1.png index eea4b52..937d644 100644 Binary files a/man/figures/unnamed-chunk-16-1.png and b/man/figures/unnamed-chunk-16-1.png differ diff --git a/man/figures/unnamed-chunk-17-1.png b/man/figures/unnamed-chunk-17-1.png new file mode 100644 index 0000000..fbdcba2 Binary files /dev/null and b/man/figures/unnamed-chunk-17-1.png differ diff --git a/man/figures/unnamed-chunk-19-1.png b/man/figures/unnamed-chunk-19-1.png new file mode 100644 index 0000000..eea4b52 Binary files /dev/null and b/man/figures/unnamed-chunk-19-1.png differ