BrainVoyager Support

documentation overview

  • Increase font size
  • Default font size
  • Decrease font size

PsychoPhysiological Interaction (PPI)

PPI plugin 1.30

The PPIplugin computes the psychophysiological interaction (PPI) predictors and confounds for one or multiple files. PPI analysis is a particular type of functional connectivity analysis. PPIs analysis investigates task-specific changes in the relationship between activity in different brain areas. A PPI analysis identifies which voxels increase their relationship with a seed region of interest (ROI) in a given psychological context, such as attention. Two areas may have a relationship which is present all the time and not influenced by your psychological context. The correlation between these two areas will be high and, therefore, their functional connectivity. In PPI analysis we are not interested in relationship present all the time but  only in relationships modulated by the task. "... a PPI aims to identify regions whose activity depends on an interaction between psychological factors (the task) and physiological factors (the time course of a region of interest). A task-specific increase in the relationship between brain regions (a PPI effect) is suggestive of a task-specific increase in the exchange of information." (O'Reilly et al., 2012).

PPI analysis was originally proposed by Friston and colleagues (1997). Gitelman and colleagues (2003) enabled PPIs to be applied to event-related designs by incorporating the haemodynamic response. Recently, McLaren and colleagues (2012) proposed a generalized PPI (gPPI) which aims to overcome two limitations of the initially proposed PPI analysis. First, a PPI analysis can only identify effects related to differences between psychological contrasts and not similarities between contrasts. Second, the standard implementation does not span the space of all conditions and as such is potentially limited to simple experiments (experiment limited to one or two conditions, or experiments that can be collapsed into two conditions) (McLaren et al., 2012). In the present plugin, you may decide to use either the standard PPI approach or the generalized PPI approach.

In short, the plugin will extract the mean activity of your seed ROI for each TR. This time course will be z-transformed before to be multiplied TR by TR with the task time course. The result will form a PPI predictor. The task time course are based on the protocol associated with the data. Before to be multiplied by the ROI time course, the task time course will be convolved with the haemodynamic response function. In the gPPI analysis, each condition, but the first assumed to be rest, will define a task time course and will be multiplied individually with the ROI time course. If you have N conditions, you will obtain N predictors. In the classic PPI analysis, you have to assign a weight to each condition in such a way that the resulting time course will be zero centered. For example, if you have only one condition and rest, you attribute a weight of 1 to your condition and -1 to the rest condition. If you want to compare two conditions, then one should have a weight of 1 and the other a weight of -1, the rest having a weight of 0. You will obtain one predictor. All predictors are saved in the design matrix.

The interaction between the psychological context and the brain activity can be modeled at the neural activity level or at the haemodynamic response function level. In the first case, the ROI time course as to be deconvolved before to be multiplied by the task time course. The results is then convolved with the haemodynamic response function. This is the approach suggested by Gitelman and colleagues (2003) and applied in SPM. The idea behind the deconvolution step is that the interaction occurs at the neural level and is therefore best computed at the neural level. However, there is no deterministic way to deconvolve the HRF if its shapes is not known exactly (O'Reilly et al., 2012). In the second case, the task time course is convolved with the haemodynamic response function before the multiplication with the ROI time course. This is the approach implemented in both BrainVoyager's PPIplugin and in FSL. This point may especially important for event-related analysis, rather than block design analysis.

If you are only interested in area which increase their relationship with your seed ROI in a given context, there are two kind of confounds you have to take into account. First, some areas may be correlated with the seed ROI time course regardless of the task. You therefore have to include the seed ROI time course as a confound predictor in your GLM analysis. Second, some areas may present an effect driven by a shared task input. We do not need a PPI analysis to find these areas. Therefore, for each PPI predictor, a psychological confound should be included. With the PPI analysis, the psychological predictor used for computing the PPI predictor and, eventually, a complementary predictor will be created (if psychological predictor was A-B, a A+B complimentary predictor).  In case of gPPI analysis, N+1 psychological confounds will be created. The plugin will compute all of the confounds and save them in the GLM matrix.

After the plugin finishes creating PPI predictors and confounds you may load the design matrix (*.sdm or *.mdm file) into BV. At this stage, you may include any regressor that model other known variance in your data (other condition, movement...). You may now run the PPI analysis.

If you are not familiar with PPI analysis, we strongly recommend reading the tutorial paper by O'Reilly and colleagues (2012) as well as the other papers in the bibliography section before starting a PPI analysis.


To install the plugin, you need to copy the PPIplugin library and the associated files (ppi_gui.js and ppi_gui.ui) to the plugin directory. The PPIplugin library has an extension .dll for windows, .dylib on Mac OS X and .so for linux. A plugin you download will usually be compressed so you need to uncompress it into the plugin driectory in order to install it. The plugin directory is slightly different depending on your operating system. The directory is automatically created during the brainvoyager installation and will be called either Plugins_32 (for 32bit Brainvoyager) or Plugins_64 (for 64bit Brainvoyager):

The plugins directory can be found in:        .....\Documents\BVQXExtensions

or .....\Documents\BVExtensions

After installing the plugin, restart BrainVoyager. The PPIplugin should appear the Plugin menu.


How to

  • 0) This plugin needs a vmr file to operate. Before to start, open a vmr file in BrainVoyager.
  • 1) Start the PPIplugin in the Plugin menu




  • 2) A new window open:




  • 3) In the top lef box you can select which method to use:
    1. - the generalized PPI approach proposed by McLaren  and colleagues (2012).
    2. - the standard PPI approach as initially proposed by Friston and colleagues (1997).
    3. If you want to select the standard PPI, you have to select it before selecting the first subject.
  • 4) In the top right box, you will find some options.
  • 4.1) You can decide to add the motion predictor by checking "Add MC predictors". These predictors can be z-transformed.
  • 4.2) If you run a multiple subjects analysis, check the "Save as MDM" to save the design matrix.
  • 4.3) You can specify a predictor name.
  • 4.4) You can specify if the protocol contains a baseline or not. In that case the first condition will be considered as the baseline.
  • 5) Click on the "Add Subject" button to add a vtc (time course) and a voi file.
  • 5.1) You will be prompted to select a vtc file.
  • 5.2) The plugin will automatically look for a protocol file (*.prt). If there is no prt file linked to your vtc, you will be prompted to select one.
  • 5.3) You will be prompted to select a voi file.
  • 5.4) If there are more than one VOI in the selected file, the plugin will ask you to select a VOI
  • selectvoi
  • 5.5) You can save the list of files by clicking on the "Save as.." button.


  • 5.6) Alternatively, you can load a previously saved list of subject by clicking on the "Load" button.


  • 6) If you select the classic PPI, you will have to drag and drop each condition into the correct box weight  (including rest)



  • 7) Click on the "Start" button to run the plugin
  • If you run a multi-subjects analysis, you will be prompted to confirm the analysis. Click "Yes".


    • If you did not select the "Save as MDM" option, the plugin will prompt you for a name to save the sdm for each subject in a separate file.
    • Otherwise, each sdm file and a mdm file will be saved automatically with a name generated by the program. Check the log for the exact name
  • 8) When the log shows
    Script> MDM file has been saved as: Z:/BRAINTRAIN/DataAcquisition/Connectivity/cFB/s07/FB1/Analyzed/MultiStudy_FROM_PPI_SCRIPT.mdm

    Script> Please load the newly created .sdm file(s) or .mdm file in the (multi-study) GLM dialog.

    the plugin has completed the processing of the data.
  • 9) You may load the design matrix and proceed with the PPI analysis


        Note: The saved files have an extension ".ppi". They are text files you can edit them easily with any file editor to add or remove subjects.


Classic PPI

PPI predictor
Psychological predictor (Fixation = 0; Passive = -1; Attention = 1)
Complementary psychological predictor (Passive = 1; Attention = 1)
Physiological predictor


Generalized PPI

First PPI predictor
Second PPI predictor
First psychological predictor
Second psychological predictor
Physiological predictor


Bibliography/Recommended reading

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.[PDF]

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. [PDF]

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. [HTML]

O’Reilly, J. X., Woolrich, M. W., Behrens, T. E., Smith, S. M., & Johansen-Berg, H. (2012). Tools of the trade: psychophysiological interactions and functional connectivity. Social cognitive and affective neuroscience, 7(5), 604-609.[HTML]