# Interpolation and Filtering of Pupil Size Data

#### Aki Kyröläinen and Vincent Porretta

#### 2025-12-19

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). Further, 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.

## Proceed with preprocessing

At this point it is possible to proceed with preprocessing as usual. Please refer back to the Basic Preprocessing vignette and continue by performing baseline correction.