geom_flat_violin_HELPER2

Description

Borrowed from Ben Marwick. Original author David Robinson.

Baseline pupil data to the average pupil size within a window

Description

This function is for use with the PupillometryR package to baseline each participant's pupil size to the mean pupil size within a window. This may not be necessary if you are doing purely within-subject analyses, but it is convenient for comparison across subjects, and makes results more uniform.

Usage

baseline_data(data, pupil, start, stop)

Arguments

Value

A PupillometryR dataframe, with baselined pupil

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)

Calculate a mean size across two pupils over time

Description

This function is useful when you have left and right eye eyetracking data, and a mean of the two would be useful.

Usage

calculate_mean_pupil_size(data, pupil1, pupil2)

Arguments

Value

A PupillometryR dataframe with a mean pupil column

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data, pupil1 = RPupil, pupil2 = LPupil)

Calculate the missing data amount

Description

This function can be used to assess the amount of samples that have problematic data from each trial, which helps assess cleaning parameters

Usage

calculate_missing_data(data, pupil)

Arguments

Value

A summary table with number of missing samples in each trial

Examples

data(pupil_data)
Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
new_data <- downsample_time_data(data = Sdata,
pupil = LPupil,
timebin_size = 50,
option = 'mean')
calculate_missing_data(data = new_data, pupil = LPupil)

Clean missing data above an acceptable threshold

Description

This function can be used to remove trials and participants who do not meet the threshold for a study. Note that there are two parameters for cleaning, one to remove trials above a threshold, the second to remove participants who drop more than a certain amount of trials.

Usage

clean_missing_data(
  data,
  pupil,
  trial_threshold = 1,
  subject_trial_threshold = 1
)

Arguments

Value

A cleaned PupillometryR dataframe

Examples

data(pupil_data)
Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
new_data <- downsample_time_data(data = Sdata,
pupil = LPupil,
timebin_size = 50,
option = 'mean')
calculate_missing_data(data = new_data, pupil = LPupil)

Create a difference data frame when dealing with a condition column with 2 levels

Description

The difference data frame is used when creating a dataframe to do the functional t-test analysis. This function would be the first step in that analysis, after doing the pre-processing. It creates a frame where it treats the condition data as level2 - level1. It will throw an error if there are more than two conditions.

Usage

create_difference_data(data, pupil)

Arguments

Value

A Pupil_difference_data data frame

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
mean_data <- calculate_mean_pupil_size(data = Sdata,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
differences <- create_difference_data(data = base_data, pupil = mean_pupil)
plot(differences, pupil = mean_pupil, geom = 'line')

Makes a functional data with splines from a Pupil_difference_data dataframe.

Description

This function turns difference data into fitted splines in order to carry out functional data analysis. Under the hood this passes basis and order to fda::Data2fd, and fda::create.bspline.basis, and is mandatory before running run_functional_t_test. It is recommended to read the documentation for package fda for further information.

Usage

create_functional_data(data, pupil, basis, order)

Arguments

Value

A Pupil_difference_data dataframe fitted with b-splines.

See Also

fda package

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data, pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
differences <- create_difference_data(data = base_data, pupil = mean_pupil)
spline_data <- create_functional_data(data = differences, pupil = mean_pupil, basis = 10, order = 4)

Make PupillometryR dataframe into multiple time windows for easy analysis

Description

This function creates a single collapsed data frame for easy analysis with an anova or model, per condition. By comparison create_window_data allows collapsing all into a single time window.

Usage

create_time_windows(data, pupil, breaks)

Arguments

Value

a Pupil_window_data dataframe

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
time_window <- create_time_windows(data = base_data, pupil = mean_pupil,
breaks = c(1000, 2000))

Make PupillometryR dataframe into a single collapsed window for easy analysis

Description

This function creates a single collapsed data frame for easy analysis with a t-test or anova, per condition. By comparison create_time_windows allows dividing it into multiple windows per time.

Usage

create_window_data(data, pupil)

Arguments

Value

a Pupil_window_data dataframe

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
window <- create_window_data(data = base_data, pupil = mean_pupil)
p <- plot(window, pupil = mean_pupil, windows = FALSE, geom = 'boxplot')
p

detect blinks by a pre-existing labelled blink column that comes from the eyetracker

Description

This allows the user to remove anything classed as a blink as a result of eyetracker output.

Usage

detect_blinks_by_column(
  data,
  pupil,
  column,
  extend_forward = 0,
  extend_back = 0,
  .tag = 1
)

Arguments

Value

returns dataframe with blinks removed including forward and back, and data in blink column.

Examples

## Not run: 
Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)

Sdata2 <- detect_blinks_by_column(data = Sdata,
pupil = LPupil,
column = data_in_blink,
extend_forward = 0,
extend_back = 0)

## End(Not run)

detect blinks by a change in pupil size

Description

This allows the user to set a threshold for pupil size and remove anything classed as a blink as a result

Usage

detect_blinks_by_size(
  data,
  pupil,
  threshold = 2.5,
  extend_forward = 0,
  extend_back = 0
)

Arguments

Value

returns dataframe with blinks removed including forward and back, and data in blink column.

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)

Sdata2 <- detect_blinks_by_size(data = Sdata,
pupil = LPupil,
threshold = 2.5,
extend_forward = 0,
extend_back = 0)

detect blinks by a change in velocity

Description

This allows the user to set a threshold for velocity and remove anything classed as a blink as a result

Usage

detect_blinks_by_velocity(
  data,
  pupil,
  threshold = 0.1,
  extend_forward = 0,
  extend_back = 0
)

Arguments

Value

returns dataframe with blinks removed including forward and back, and data in blink column.

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)

Sdata2 <- detect_blinks_by_velocity(data = Sdata,
pupil = LPupil,
threshold = 0.1,
extend_forward = 0,
extend_back = 0)

Downsample frequency to reduce number of samples and data size

Description

This function is useful if you were sampling at a very high frequency (eg 500Hz) causing the data size to be hard to manage, and high autocorrelation. Careful decisions should be made about the time bin size and appropriateness of this function, with respect to the data type.

Usage

downsample_time_data(data, pupil, timebin_size, option = c("mean", "median"))

Arguments

Value

A downsampled dataframe of class PupillometryR

Examples

data(pupil_data)
Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
new_data <- downsample_time_data(data = Sdata,
pupil = LPupil,
timebin_size = 50,
option = 'mean')

Run a filter on the data to smooth it out.

Description

filter_data allows three different options for filtering, a butterworth lowpass filter, a hanning filter, or a median filter. You can also set the degree of this filter; we recommend a default of 11. This filters on one pupil, it can be re-run on a second pupil if needed. Lowpass makes use of the butterworth filter and filtfilt from package signal, median makes use of runmed.

Usage

filter_data(
  data,
  pupil,
  filter = c("median", "hanning", "lowpass"),
  degree = 11
)

Arguments

Value

filtered pupil data

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
mean_data <- calculate_mean_pupil_size(data = Sdata,
pupil1 = RPupil, pupil2 = LPupil)
filtered_data <- filter_data(data = mean_data,
pupil = mean_pupil,
filter = 'hanning',
degree = 11)

ggplot Flat Violin

Description

ggplot Flat Violin

Usage

geom_flat_violin(
  mapping = NULL,
  data = NULL,
  stat = "ydensity",
  position = "dodge",
  trim = TRUE,
  scale = "area",
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

Copy-pasted from https://gist.githubusercontent.com/benmarwick/2a1bb0133ff568cbe28d/raw/fb53bd97121f7f9ce947837ef1a4c65a73bffb3f/geom_flat_violin.R somewhat hackish solution to: https://twitter.com/EamonCaddigan/status/646759751242620928 based mostly on copy/pasting from ggplot2 geom_violin source: https://github.com/hadley/ggplot2/blob/master/R/geom-violin.r The original seems to be: sourced from: https://gist.github.com/dgrtwo/eb7750e74997891d7c20, Author is David Robinson. A key internal function for the raincloud plots used as a plotting option in this package. For information on raincloud plots see: Allen, M., Poggiali, D., Whitaker, K., Marshall, T. R., & Kievit, R. A. (2019). Raincloud plots: a multi-platform tool for robust data visualization. Wellcome open research, 4, 63. doi:10.12688/wellcomeopenres.15191.1

Examples

ggplot(diamonds, aes(cut, carat)) +
  geom_flat_violin() +
  coord_flip()

geom_flat_violin_HELPER1

Description

Borrowed from https://gist.githubusercontent.com/benmarwick/2a1bb0133ff568cbe28d/raw/fb53bd97121f7f9ce947837ef1a4c65a73bffb3f/geom_flat_violin.R. Original author David Robinson, from https://gist.github.com/dgrtwo/eb7750e74997891d7c20

Interpolate across the gaps in data

Description

Once data is smoothed, it is important to deal with missing observations, such as blinks. This allows simple interpolation over missing values, either linear, or cubic. Depending on the analysis planed, this may not be a necessary option, but it is strongly recommended for the functional analyses planned in this package.

Usage

interpolate_data(data, pupil, type = c("linear", "cubic"))

Arguments

Value

interpolated pupillometry data

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
mean_data <- calculate_mean_pupil_size(data = Sdata,
pupil1 = RPupil, pupil2 = LPupil)
filtered_data <- filter_data(data = mean_data,
pupil = mean_pupil,
filter = 'hanning',
degree = 11)
int_data <- interpolate_data(data = filtered_data,
pupil = mean_pupil,
type = 'linear')

Prepare data for pre-processing in PupillometryR

Description

This should be the first function you run as part of using PupillometryR. This will make sure your data is in the right format for processing. This package is designed to deal with data at it comes out of the eyetracker in a long-form csv style format. Thus data input here would be a long dataframe, wherein each row is a single frame collected by the eyetracker.

Usage

make_pupillometryr_data(data, subject, trial, time, condition, other)

Arguments

Value

A dataframe ready to use in PupillometryR

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)

Helper function mean2

Description

Somewhat useful function for ignoring NAs

Usage

mean2(x)

Arguments

Pre-prepared plots of PupillometryR data

Description

The plot functions are designed to run with just data and pupil selections, with some additional options for fun with plotting. To see these plots, you must first use create_difference_data.

Usage

## S3 method for class 'Pupil_difference_data'
plot(x, pupil, geom = c("point", "line"), colour = "black", ...)

Arguments

Value

A ggplot object

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
differences <- create_difference_data(data = base_data,
pupil = mean_pupil)
p <- plot(differences, pupil = mean_pupil, geom = 'line')
p

Pre-prepared plots of PupillometryR data

Description

The plot functions are designed to run with just data and pupil selections, with some additional options for fun with plotting. To see these plots, you must first use one of the run_functional tests.

Usage

## S3 method for class 'Pupil_test_data'
plot(x, show_divergence = TRUE, colour = "black", fill = "grey", ...)

Arguments

Value

A ggplot object

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
differences <- create_difference_data(data = base_data,
pupil = mean_pupil)
spline_data <- create_functional_data(data = differences, pupil = mean_pupil, basis = 10, order = 4)
ft_data <- run_functional_t_test(data = spline_data,
pupil = mean_pupil)
p <- plot(ft_data, show_divergence = TRUE, colour = 'red', fill = 'orange')
p

Pre-prepared plots of PupillometryR data

Description

The plot functions are designed to run with just data and pupil selections, with some additional options for fun with plotting. To see these plots, you must first use create_window_data.

Usage

## S3 method for class 'Pupil_window_data'
plot(
  x,
  pupil,
  windows = c(FALSE, TRUE),
  geom = c("raincloud", "violin", "boxplot"),
  ...
)

Arguments

Value

A ggplot object

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
window <- create_window_data(data = base_data,pupil = mean_pupil)
p <-plot(window, pupil = mean_pupil, windows = FALSE, geom = 'boxplot')
p

Pre-prepared plots of PupillometryR data

Description

The plot functions are designed to run with just data and pupil selections, with some additional options for fun with plotting. This allows to see raw data as points, grouped by either subject or condition.

Usage

## S3 method for class 'PupillometryR'
plot(
  x,
  pupil,
  group = c("none", "condition", "subject"),
  geom = c("point", "line", "pointrange"),
  model = NULL,
  ...
)

Arguments

Value

A ggplot object

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
Sdata2 <- downsample_time_data(data = Sdata,
pupil = LPupil,
timebin_size = 100,
option = 'median')
p <- plot(Sdata2, pupil = LPupil, group = 'subject')
p

Data collected in a pupillometry study by Sylvain Sirois

Description

Data from a simple study measuring pupil dilation as participants answer hard or easy maths problems. Original data sourced and reformatted from Sylvain Sirois' Pupillometry tutorial available at https://oraprdnt.uqtr.uquebec.ca/pls/public/gscw031?owa_no_site=314&owa_no_fiche=3&owa_bottin=)

Usage

pupil_data

Format

A data frame with 28800 rows and 7 variables:

ID

Uniaue participant ID

Trial

Unique trial code (also unique for each participant)

RPupil

Right pupil size

LPupil

Left Pupil Size

Timebin

Ordered timebin within each trial

Time

Elapsed time within trial

Type

Hard or easy trial?

...

Source

(https://oraprdnt.uqtr.uquebec.ca/pls/public/gscw031?owa_no_site=314&owa_no_fiche=3&owa_bottin=)

Regress one pupil against another for extra smoothing

Description

regress_data runs a simple linear regression of pupil1 against pupil2 and the reverse. This can help to account for small amount of bumpiness in the data. The regression runs over each participant and each trial, per time.

Usage

regress_data(data, pupil1, pupil2)

Arguments

Value

a PupillometryR dataframe with smoothed pupil values

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
regressed_data <- regress_data(data = Sdata,
pupil1 = RPupil,
pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data,
pupil1 = RPupil, pupil2 = LPupil)

replaces missing observations if you have some degree of incomplete observations

Description

This is a useful function if you have a dataset where certain timepoints have been removed for whatever reason, but you want continuous time data. This will make assumptions about trials being the same length though, so may not be appropriate for all data types. This should only be run after running make_pupillometry_data.

Usage

replace_missing_data(data)

Arguments

Value

A time-stepped data frame

Examples

data(pupil_data)
Sdata <- make_pupillometryr_data(data = pupil_data,
subject = ID,
trial = Trial,
time = Time,
condition = Type)
new_data <- replace_missing_data(data = Sdata)

Run a functional t-test on a dataframe previously fitted with b-splines.

Description

This allows running of a functional t-test for a given alpha on pupil data that has been fitted with b-splines. This is only appropriate for functional difference data, as it assumes we are dealing with condition A - condition B.

Usage

run_functional_t_test(data, pupil, alpha = 0.05)

Arguments

Value

A Pupil_test_data dataframe

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
regressed_data <- regress_data(data = Sdata, pupil1 = RPupil, pupil2 = LPupil)
mean_data <- calculate_mean_pupil_size(data = regressed_data, pupil1 = RPupil, pupil2 = LPupil)
base_data <- baseline_data(data = mean_data, pupil = mean_pupil, start = 0, stop = 100)
differences <- create_difference_data(data = base_data, pupil = mean_pupil)
spline_data <- create_functional_data(data = differences, pupil = mean_pupil, basis = 10, order = 4)
ft_data <- run_functional_t_test(data = spline_data, pupil = mean_pupil, alpha = 0.05)

Subset data to provide start and finish time windows

Description

subset_data can be used on a PupillometryR dataframe to subset the time into relevant chunks. This, ideally should be one of the first runctions run, before anything analytical. Use this to indicate a start and stop time to create a new resized dataframe.

Usage

subset_data(data, start = NULL, stop = NULL, rezero = T, remove = T)

Arguments

Value

a subsetted PupillometryR dataframe

Examples

Sdata <- make_pupillometryr_data(data = pupil_data,
                               subject = ID,
                               trial = Trial,
                               time = Time,
                               condition = Type)
subset_data(Sdata, start = 100, stop = 10000, rezero = TRUE, remove = TRUE)