Merge pull request #5 from tombeesley/develop

patch for AOI_seq fix

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"))

NEWS.md

@@ -1,3 +1,5 @@
+# eyetools 0.6.1
+
 # eyetools 0.6.0
 
 # eyetools 0.5.1

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) {

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")
   }

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,15 +275,15 @@ 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}
 
 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)
 
 ```