This vignette contains detailed information regarding optional steps in the preprocessing pipeline, namely, interpolation of missing data and filtering. These are presented sequentially, because in order for the filter to be carried out appropriately, it is necessary to ensure each event is not missing data.
Interpolation
Once cleaning is done, it is possible to interpolate the missing values, if desired.
Currently the function interpolate_NAs uses either linear interpolation or cubic spline interpolation as implemented in the package zoo. It is also possible to interpolate the X and Y gaze coordinates, if needed for the analysis, by setting XandY to TRUE. By default, this function requires a minimum of two data points in the event in order to carry out the interpolation (else the function may fail). Futher, please note that if the missing values occur at the beginning or the end of the time series, the missing data cannot be interpolated as there is no beginning (or end) value between which to interpolate.
Linear
datlinear <- interpolate_NAs(dat, Method = "linear", XandY = T, MinData = 2)
## Checking for minimum required data: 2 data points per event
## Applying linear interpolation to pupil size data
## Applying linear interpolation to gaze coordinates
## Pupil summary:
## 5 events interpolated
## 0 events skipped due to insufficient data
## Gaze coordinate summary:
## 5 events interpolated
## 0 events skipped due to insufficient data
Splines
datspline <- interpolate_NAs(dat, Method = "spline", XandY = T, MinData = 2)
## Checking for minimum required data: 2 data points per event
## Applying cubic spline interpolation to pupil size data
## Applying cubic spline interpolation to gaze coordinates
## Pupil summary:
## 5 events interpolated
## 0 events skipped due to insufficient data
## Gaze coordinate summary:
## 5 events interpolated
## 0 events skipped due to insufficient data
Again, the function plot_compare_app can be useful in visualizing the effect of the interpolation.
Filtering
Once interpolation is done, it is possible to filter the data, if desired.
Currently a Butterworth filter is available as is implemented in the function butter in the package signal. The filter allows for low-pass, high-pass, stop-band (band-reject), or pass-band filtering.
Determining the parameters
The filter requires a number of parameters be set: n (the filter order, i.e., integer value), W (the critical frequency(ies) of the filter, i.e., the cut-off frequencies between 0 and 1 where 1 is the Nyquist frequency), and type (the filter type, e.g., “low”, etc.). In this example, we will use a data set containing linear interpolation.
butter_filter_app(datlinear)
In addition to the parameters of the filter, there are inputs for excluding a specific number of milliseconds from the beginning and the end of the timeseries.
This is included as the user will notice that the filter can create artifacts at the edges. These inputs place vertical bars to aide the use in later decisions regarding data trimming.
Applying the filter
Once the parameters have been selected, it is necessary to apply the filter to the data, using the function apply_butter.
datfilter <- apply_butter(datlinear, n = 1, W = 0.1, type = "low", plane = "z")
## Applying Butterworth filter to eligible events
##
## 5 events filtered
## 0 events skipped due to the presence of NAs
Notice that the function outputs a summary of how many events were filtered and how many were skipped due to the presence of missing data. These skipped events can easily be removed from the data using the function below.
Trimming the data
The function trim_filtered allows the user to quickly remove both skipped events as well as artifacts created by the filter. As noted above, the filter skips events that contained missing values. These skipped events can be removed by setting RmSkipped to TRUE. As noticed when using the function plot_filter_app, the filter can create artifacts at the edges of the timeseries. These artifacts can be removed from the data by providing RmEdges with the number of milliseconds to remove from the beginning of the timeseries (i.e., the first number in the vector), and from the end of the timeseries (i.e., the second number in the vector).
dattrim <- trim_filtered(data = datfilter, RmSkipped = TRUE, RmEdges = c(75, 75))
## Removing skipped events.
## Marking data points for trimming.
##
## Removing edges from the data.
