In epongpipat/ppi: Psychophysiological Interaction (PPI)

ppi : Psychophysiological Interaction (PPI)

A neuroimaging package to "easily" perform PPI analyses for task functional magnetic resonsnace imaging (fMRI).

Note: This package is still being developed and will likely change a lot. Please use cautiously.

Installation

devtools::install_github("epongpipat/ppi")

Data Wrangling

Go from a 3-column format events file (i.e., columns of onset, duration, trial_type) and a physiological time series from a region of interest to a PPI design matrix in seconds!

library(ppi)
library(dplyr)

# define hrf ----
hrf <- create_hrf_afni(hrf = "spmg1", tr = 3, upsample_factor = 16)

# load events file ----
psy_url <- "https://openneuro.org/crn/datasets/ds000171/snapshots/00001/files/sub-control01:func:sub-control01_task-music_run-1_events.tsv"
psy_events <- readr::read_tsv(url(psy_url)) %>%
  mutate(trial_type = as.factor(trial_type))

# define contrast code ----
# orthogonal contrast code:
# 1. stimulus vs response
# 2. music vs tones
# 3. positive music vs negative music
psy_contrast_table <- cbind(stimulus_vs_response = c(1, 1, -3, 1)/4,
                            music_vs_tones = c(1, 1, 0, -2)/3,
                            positive_music_vs_negative_music = c(-1, 1, 0, 0)/2)

# load physiological time series data from region of interest ----
phys_file <- "examples/sub-control01_task-music_run-1_bold_space-subj_vox-32-24-38.csv"
phys_data <- readr::read_csv(phys_file, col_names = F)

tictoc::tic()
data_wrangling <- data_wrangling(psy_events_data = psy_events, 
                                 psy_unlabeled_trial_type = "response", 
                                 psy_contrast_table = psy_contrast_table, 
                                 phys_data = phys_data, 
                                 detrend_factor = 2,
                                 hrf = hrf, 
                                 tr = 3, 
                                 n_volumes = 105, 
                                 upsample_factor = 16, 
                                 deconvolve = TRUE,
                                 afni_quiet = TRUE)
tictoc::toc()

Everything is saved as a list, which includes the input parameters and every single step of the data wrangling pipeline.

Hmisc::list.tree(data_wrangling, depth = 3)

Need more flexibility?

You can create each individual set of variables using create_psy_var(), create_phys_var(), and create_ppi_var() or create every step of each variable using these data wrangling functions.

Visualization

Visualize the data as a time series or a heatmap.

visualize_time_series(data = data_wrangling$design_matrix, 
                      scales = "free_y")
visualize_time_series_heatmap(data = data_wrangling$design_matrix, 
                              scale_data = "min-max",
                              title = "design matrix",
                              caption = "Note: Each predictor has been scaled to min-max for visualization.",
                              reverse_volume_axis = T,
                              palette = "Greys", 
                              palette_direction = 1,
                              transpose = T)

Save and Report

Save the output as both an .rds (example) and .json (example) file for continued use in R or other languages, respectively.

save_data_wrangling(data_wrangling)

Create a report of the entire pipeline (example).

create_data_wrangling_report(data_wrangling)

Under Development

Analysis

tictoc::tic()
model <- model_glm_roi2roi(data_wrangling$phys$detrend, data_wrangling$design_matrix)
tictoc::toc()

model
Hmisc::list.tree(model, depth = 3)

Acknowledgements

This package relies on a variety of R packages (i.e., tidyverse, afnir, furrr) and neuroimaging programs (i.e, AFNI and FSL).

Note: AFNI and FSL functions will eventually (hopefully) be replaced so that the package only uses R.

PPI References:

Friston, K. J., Buechel, C., Fink, G. R., Morris, J., Rolls, E., & Dolan, R. J. (1997). Psychophysiological and modulatory interactions in neuroimaging. NeuroImage, 6(3), 218–229. https://doi.org/10.1006/nimg.1997.0291

Gitelman, D. R., Penny, W. D., Ashburner, J., & Friston, K. J. (2003). Modeling regional and psychophysiologic interactions in fMRI: The importance of hemodynamic deconvolution. NeuroImage, 19(1), 200–207. https://doi.org/10.1016/S1053-8119(03)00058-2

McLaren, D. G., Ries, M. L., Xu, G., & Johnson, S. C. (2012). A generalized form of context-dependent psychophysiological interactions (gPPI): A comparison to standard approaches. NeuroImage, 61(4), 1277–1286. https://doi.org/10.1016/j.neuroimage.2012.03.068

Cisler, J. M., Bush, K., & Steele, J. S. (2014). A comparison of statistical methods for detecting context-modulated functional connectivity in fMRI. NeuroImage, 84, 1042–1052. https://doi.org/10.1016/j.neuroimage.2013.09.018

Di, X., Reynolds, R. C., & Biswal, B. B. (2017). Imperfect (de)convolution may introduce spurious psychophysiological interactions and how to avoid it. Human Brain Mapping, 38(4), 1723–1740. https://doi.org/10.1002/hbm.23413

epongpipat/ppi documentation built on Jan. 31, 2024, 1:02 p.m.