README.Rmd

---
output: github_document
---

# `ppi` : Psychophysiological Interaction (PPI)

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
<!-- badges: end -->

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
```{r, eval = F}
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!

```{r, message = F, warning = F}
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.

```{r}
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 <a href="https://ekarinpongpipat.com/ppi/reference/index.html#section-data-wrangling" target="_blank">these</a> data wrangling functions.

### Visualization

Visualize the data as a time series or a heatmap.

```{r}
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 (<a href="https://github.com/epongpipat/ppi/blob/master/examples/data_wrangling.rds" target="_blank">example</a>) and .json (<a href="https://github.com/epongpipat/ppi/blob/master/examples/data_wrangling.json" target="_blank">example</a>) file for continued use in R or other languages, respectively. 
```{r, eval = F}
save_data_wrangling(data_wrangling)
```

Create a report of the entire pipeline (<a href="https://ekarinpongpipat.com/ppi/data_wrangling_report.html" target="_blank">example</a>).
```{r, eval = F}
create_data_wrangling_report(data_wrangling)
```

## Under Development

#### Analysis 
```{r, eval = F}
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