Tools for Preprocessing Visual World Data

Gaze data from the Visual World Paradigm requires significant preprocessing prior to plotting and analyzing the data. This package provides functions for preparing visual world eye-tracking data for statistical analysis and plotting. It can prepare data for linear analyses (e.g., ANOVA, Gaussian-family LMER, Gaussian-family GAMM) as well as logistic analyses (e.g., binomial-family LMER and binomial-family GAMM). Additionally, it contains various plotting functions for creating grand average and conditional average plots. See the vignette for samples of the functionality. Currently, the functions in this package are designed for handling data collected with SR Research Eyelink eye trackers using Sample Reports created in SR Research Data Viewer. While we would like to add functionality for data collected with other systems in the future, the current package is considered to be feature-complete; further updates will mainly entail maintenance and the addition of minor functionality.



VWPre 0.9.5

  • None.
  • create_time_series: Internal operation of this function has changed; specifically, the application of the adjustment has been reinstated as a subtraction (addition was introduced in Version 0.9.0 when by-trial offset values were allowed via the parameter 'Adj'). As this underlying change significantly impacts the output, the parameter 'Adj' (from Version 0.9.0) has been replaced with 'Adjust' to ensure that old code will not inadvertently produce unexpected results (Thanks to John Matthews for helping to point this out). Please consult the vignettes for discussion of the operation of this function.
  • plot_avg_contour: The parameter 'Theme' has been changed to 'VWPreTheme' to conform with the parameter in other plotting functions
  • The text of the vignettes has been updated to reflect changes made to the functions.
  • The default values of required parameters have been standardized for all functions. Additionally, now if a required parameter is missing, the function will stop and throw an error. Previously some default values were not functional if the required parameter was not specified (as pointed out by Athanassios Protopapas).
  • The custom plotting theme included in the package (VWPreTheme) has been updated internally to reflect changes in the most recent version of ggplot2.
  • None.


VWPre 0.9.0

  • align_msg: Allows users to align the data manually based on a given sample message, rather than using interest periods defined in SR DataViewer.
  • check_msg_time: Allows users to examine the time values for a given sample message. It is also possible to return a data frame containing the time point value at the given message of each recording event.
  • custom_ia: Allows users to map the eye gaze data to newly defined interest areas via X and Y gaze coordinates. This requires the user to create a bounding box for each interest area per recording event.
  • check_time_series: Internal changes that allow the function to handle the output from the new alignment function. Also, it is now possible to return a data frame containing the start time of each recording event.
  • create_time_series: Internal changes that allow the function to use the output of the new alignment function. As part of this, the parameter Offset has been replaced with Adj (Adjustment), which allows the user to apply an offset in either direction using a (positive or negative) constant as well as to specify a column in the data set that contains values to be applied as the offset.
  • create_binomial: Internal changes which now allow the user to create custom binomial columns (e.g., looks to IA1 vs. looks to IA4). If this is desired, it can be specified in the parameter CustomBinom.
  • Vignettes have been updated and are now organized thematically as to be more digestible: 1) Basic preprocessing; 2) Plotting; 3) Message alignment; and 4) Interest Areas.
  • prep_data: Internal changes that now check required/optional columns needed called within package functions.
  • rename_columns: Internal changes that allow the function to handle the custom binomial columns available in create_binomial.
  • fasttrack: Changes reflect changes to the component functions.
  • None.


VWPre 0.7.0

  • check_ia: Allows users to check the interest area labels and interest area IDs present in the data. (Thanks to Athanassios Protopapas for pointing this out.)
  • recode_ia: Allows users to recode the interest area labels and/or interest area IDs to conform with the scheme necessary for preprocessing.
  • plot_tranformation_app: Shiny app that allows users to visualize the effect of number of observations on the empirical logit transformation.
  • bin_prop: Internal reorganization/streamlining of code. Now also outputs an additional column for the number of samples in each bin (now utilized by other functions) and prints a summary of bins containing fewer than expected samples (typically the last time bin).
  • transform_to_elogit: The underlying calculation has been modified to allow greater flexibility. Because the number of observations used in the calculation influences the values produced by the transformation, users can now specify how many observations on which to base the calculation. The function prints notification regarding this. To accommodate this, the parameter SamplesPerBin has been replaced with ObsPerBin (Thanks to Anne Pier Salverda for discussion on this).
  • create_binomial: Similar to transform_to_elogit, the function now allows users to scale the number of observations in each bin for creating the successes/failures column (e.g., IA_1_Looks). This scaling operates on proportions rather than counts. The function prints notifications regarding this. To accommodate this, the parameter ObsPerBin has been added.
  • The text of the vignette now indicates that the interest area IDs must be coded with numbers 1-8 (as the preprocessing functions rely on this scheme). The vignette also now includes the new functions (e.g., for recoding interest area IDs, etc). The text also reflects the other changes to the package functions.
  • Functions now use message() rather than print() to output information to the user.
  • plot_var_app: Quit button added.
  • plot_indiv_app: Quit button added. Window layout adjusted.
  • check_samples_per_bin: Internal reorganization/streamlining of code. Returns same information.
  • fasttrack: Corrected NoIA parameter input to transform_to_elogit and create_binomial. Has been updated to reflect changes in the component functions.


VWPre 0.5.0

  • None (First release)
  • None (First release)
  • None (First release)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.0.1 by Vincent Porretta, a month ago

Browse source code at

Authors: Vincent Porretta [aut, cre], Aki-Juhani Kyröläinen [aut], Jacolien van Rij [ctb], Juhani Järvikivi [ctb]

Documentation:   PDF Manual  

GPL (>= 2) license

Imports rlang, ggplot2, mgcv, shiny, tidyr, stats

Depends on dplyr

Suggests knitr, rmarkdown, gridExtra, itsadug

See at CRAN