# -----------------------------------------------

# VWPre 1.2.3

This is a minor maintenance update related to the upcoming release of R version 4.0.0

## Major changes:

### New functions

* None

### Changes to functions

* None

### Vignettes

* None

## Minor changes:

### Changes to functions 

* rm_extra_DVcols: This function has been changed to comply with droplevels() in R 4.0.0. 

## Bug fixes:

* None.

# -----------------------------------------------

# VWPre 1.2.2

This is a minor maintenance update.

## Major changes:

### New functions

* None

### Changes to functions

* None

### Vignettes

* None

## Minor changes:

### Changes to functions 

* select_recorded_eye: This function has been changed to reflect the most recent version of SR DataViewer (4.1.1), which now labels EYE_TRACKED with "Binocular", rather than "Both". The updated code now allows for both types of input.  Thank you to Jesse Harris for bringing this to our attention. 

## Bug fixes:

* None.

# -----------------------------------------------

# VWPre 1.2.1

This update is a bug fix.

## Major changes:

### New functions

* None

### Changes to functions

* None

### Vignettes

* None

## Minor changes:

### Changes to functions 

* None

## Bug fixes:

* rm_trackloss_events: The logical operation to remove the bad events was inadvertantly reversed, this removing the good events rather than the bad. This is now corrected. Thank you to Liam Blything for bringing this to our attention.

# -----------------------------------------------

# VWPre 1.2.0

This is a fairly major update, however, it should not break any previous functionality.  The reason for this is that we have modified the functions of the package to operate with a new sister package "PupilPre" which is designed to depend on VWPre in order to prepare pupil size data collected with SR eye-trackers.  To accommodate this functionally and compatibility, there has been some internal reorganization to use helper functions that allow PupilPre to call similar subroutines. If you do not install/load PupilPre, you should not notice any difference in functionality.

## Major changes:

### New functions

* check_all_messages: This function outputs all sample messages present in the data; the result can optionally be output to a dataframe containing event-level information.
* plot_avg_cdiff: This function facilitates the plotting of difference between two conditions for a single interest area.
* mark_trackloss: This function uses blink information and/or gaze coordinates to identify samples corresponding to trackloss.
* rm_trackloss_events: This function removes events that do not meet the minimum specified criterion for the amount of quality (i.e., containing too much trackloss).

### Changes to functions

* check_ia: This function has been changed to return more verbose information regarding the encoding of interest area ID and labels. Thanks to John Matthews for helping to demonstrate the need for this extended functionality.
* check_time_series: This function has been changed to return more concise information. However, the output remains the same if returning the data to a dataframe.
* check_msg_time: This function has been changed to return more concise information. However, the output remains the same if returning the data to a dataframe.
* prep_data: This function has been changed to accommodate pupil size data processing and now underlyingly calls .prep_data_sub.
* check_eye_recording: This function has been changed to accommodate pupil size data processing and now underlyingly calls .check_eye_recording_sub.
* select_recorded_eye: This function has been changed to accommodate pupil size data processing and now underlyingly calls .select_recorded_eye_sub.
* rm_extra_DVcols: This function has been changed to accommodate pupil size data processing and now underlyingly calls .rm_extra_DVcols_sub.
* plot_avg: This function has been changed to accommodate pupil size data visualization and now underlyingly calls .plot_avg_sub.
* plot_avg_contour: This function has been changed to accommodate pupil size data visualization and now underlyingly calls .plot_avg_contour_sub.

### Vignettes

* Vignettes have been updated to reflect changes made in this update.  

## Minor changes:

### Changes to functions 
* fasttrack: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* bin_prop: Now checks to see if PupilPre is attached by calling .check_for_PupilPre and supplies additional information regarding the number of samples in each bin.
* transform_to_elogit: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* create_binomial: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* rename_columns: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* relabel_na: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* recode_ia: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* custom_ia: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* plot_transformation_app: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* plot_var_app: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* plot_indiv_app: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* make_pelogit_fnc: Now checks to see if PupilPre is attached by calling .check_for_PupilPre.
* check_samples_per_bin: Now supplies additional information regarding the number of samples in each bin and how this may affect the empirical logit transformation.

## Bug fixes:


# -----------------------------------------------

# VWPre 1.1.0

This is a fairly minor update.

## Major changes:

### New functions

* rm_extra_DVcols: This function determines if the data set contains any of the numerous DataViewer columns that are not needed for processing VWP with this package. It subsequently removes them, unless instructed otherwise (in the event the user would like to keep specific columns for other purposes).

### Changes to functions

* check_eye_recording: This function will now use the recent DataViewer column EYE_TRACKED, if present in the data set, otherwise it will fall back to the original mode of determining which eye(s) contain gaze data.
* select_recorded_eye: This function will now use the recent DataViewer column EYE_TRACKED, if present in the data set, otherwise it will fall back to the original mode of determining which eye(s) contain gaze data.

### Vignettes

* Vignettes have been updated to reflect changes made in this update.  

## Minor changes:

### Changes to functions 

## Bug fixes:

* plot_avg_diff: There was a bug associated with the usage of the dependency rlang.  This has been fixed.
* plot_indiv_app: There were bugs associated with the usage of the dependencies rlang and dplyr.  These have been fixed.


# -----------------------------------------------

# VWPre 1.0.1

This update is a bug fix.

## Major changes:

### New functions

### Changes to functions

### Vignettes

* Vignettes have been updated to reflect changes made in this update.  

## Minor changes:

### Changes to functions 

## Bug fixes:

* plot_avg: There was a bug associated with the labeling of facets and legend when conditions were specified.  This has been corrected.
* plot_avg_diff: There was a bug associated with the labeling of the legend when conditions were specified.  This has been corrected.


# -----------------------------------------------

# VWPre 1.0.0

This update brings a number of changes to VWPre.  These are meant to bring the package functions in line with the non-standard evaluation (NSE) implemented in dplyr (>=0.7.0), requiring update of the dependency dplyr (as the previous NSE functions will eventually be deprecated).  Additionally, a number of new features have been introduced to existing functions, which should not break existing code.  Lastly, one new function has been added.  All changes are elaborated below.

## Major changes:

### New functions

* make_pelogit_fnc: Creates a function that can transform empirical logit values back to probability scale using the number of samples and constant that the user specified in the original transformation. This function can then be used to backtransform empirical logit values predicted by a statistical model.

### Changes to functions

* plot_avg: Internal change related to dplyr NSE. The option to plot both pointwise and simultaneous confidence intervals has been added. For proportions, CIs are based on the Wald method. The option to calculate grand averages for the sample, subjects, or items has been added.  If a single interest area is plotted by condition, the function will now plot these conditional averages in a single frame (rather than in separate facets).
* plot_avg_diff: Internal change related to dplyr NSE. The option to plot both pointwise and simultaneous confidence intervals has been added. The option to calculate grand averages for the sample, subjects, or items has been added.
* plot_avg_contour: Internal change related to dplyr NSE and the option to calculate grand averages for the sample, subjects, or items.
* plot_indiv_app: Internal change related to dplyr NSE and to calculation (see above).
* plot_var_app: Internal change related to dplyr NSE and to SE calculation (see above).

### Vignettes

* Vignettes have been updated to reflect changes made in this update.  

## Minor changes:

### Changes to functions 

* align_msg: Internal change which allows the function to use regular expressions for selecting the sample message for alignment.
* check_msg_time: Internal change which allows the function to use regular expressions for finding the desired message.
* ds_options: Additional parameter added controlling whether all rates are output or if only whole rates (default) are output. 
* bin_prop: Internal change allowing the function to proceed for all real rates; previously only whole rates were allowed. 
* transform_to_elogit: Internal change related to dplyr NSE.
* create_binomial: Internal change related to dplyr NSE.
* prep_data: Internal change related to dplyr NSE.
* create_time_series: Internal change related to dplyr NSE and deprecated parameters removed.
* check_ia: Internal change to adjust format of output message.
* plot_transformation_app: Internal change related to dplyr NSE.

## Bug fixes:

* none.


# -----------------------------------------------

# VWPre 0.9.6

## Major changes:

### New functions

* None.

### Changes to functions

* None.

### Vignettes

* None.  

## Minor changes:

### Changes to functions 

* plot_avg: Internal change to make the function compatible with dplyr 0.7.0. 
* plot_avg_diff: Internal change to make the function compatible with dplyr 0.7.0. 
* plot_indiv_app: Internal change to make the function compatible with dplyr 0.7.0. 

## Bug fixes:

* create_binomial: Internal change to correct a bug in the creation of the optional CustomBinom column.



# -----------------------------------------------

# VWPre 0.9.5

## Major changes:

### New functions

* None.

### Changes to functions

* 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

### Vignettes

* The text of the vignettes has been updated to reflect changes made to the functions.  

## Minor changes:

### Changes to 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.

## Bug fixes:

* None.



# -----------------------------------------------

# VWPre 0.9.0

## Major changes:

### New functions

* 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.

### Changes to functions

* 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

* 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.

## Minor changes:

### Changes to functions 

* 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.

## Bug fixes:

* None.



# -----------------------------------------------

# VWPre 0.7.0

## Major changes:

### New functions

* 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.

### Changes to functions

* 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.  

## Minor changes:

### SR_Example Vignette

* 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.

### Changes to 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.

## Bug fixes:

* 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

## Major changes:

* None (First release)

## Minor changes:

* None (First release)

## Bug fixes:

* None (First release)
