Creation of Physiological Noise Regressors Using External Recordings (Python Script)

Physiological fluctuations from heartbeat and respiration are a common source of noise in fMRI data.

Here we provide a Python script ( that will use pulse and/or respiratory recordings, saved in BIDS compatible format (*_physio.tsv.gz and _physio.json) (see for more information on BIDS) as well as a corresponding BrainVoyager *.fmr file (created with BrainVoyager 21.4 and newer) to generate a set of volume-based physiological noise regressors.


This script was developed with Python 3.8 and the following Python packages installed:


Download: (version 0.1.0) (version 0.1.0)


Please note:
The can be used when multiple functional runs and their corresponding physiological datasets should be processed at the same time. It will ask for the script and for a TSV file containing the path information of the input files as specified below. For more details about the TSV file, please refer to the short description within the script
However, please note that we strongly advise to use the batch processing only after you have familiarized yourself with the script. Furthermore, and even more important, please always check the input data quality for every dataset, since the generated noise predictors are only useful when the physiological raw data is of sufficient quality!

To get a first impression feel free to download and work with our example data set.

This is only a first version of the script; any suggestions, improvements and/or bug reports are highly appreciated and can be sent to This email address is being protected from spambots. You need JavaScript enabled to view it. 



 A short description of the script

The script imports physiological recordings that follow the BIDS standard together with a corresponding FMR file. The physiological data, in form of the cardiac signal derived from a PPU (peripheral pulse unit) and the respiratory signal derived from a breathing belt, will be preprocessed, plotted and used for peak detection and the extraction of different physiological variables (e.g. heart rate, breathing rate, respiratory volume per time, etc.). Different study design matrices (SDM files) will be saved to disk, containing: (1) the filtered volume-based physiological signals (*_resp_filtz.sdm, *_cardiac_BP0.5-8Hz_z.sdm), (2) RETROICOR regressors, created based on the method proposed by Glover et al., 2000 (*_resp_RETROICOR.sdm, *_cardiac_RETROICOR.sdm, *_cardiacresp_RETROICOR.sdm), (3) and a set of physiological noise regressors, including the (shifted) heart rate (*_HR.sdm), the HR convolved with the cardiac response function (_*_HRCRF.sdm), the breathing rate (*_BR.sdm), the respiratory flow (*_RF.sdm), the (shifted) envelope of the respiratory signal (*_ENV.sdm), the (shifted) respiration variation (*_RV.sdm), the (shifted) respiration volume per time (*_RVT.sdm), RV convolved with the respiratory response function (*_RVRRF.sdm), and RVT convolved with the RRF (*_RVTRRF.sdm). If a (task) design matrix has been provided by the user, Pearson correlations of the task design with the derived physiological regressors will be computed, plotted and saved to disk. Additionally, if a stimulation protocol, specifying the experimental timing of the task, has been specified by the user, the stimulation protocol (PRT) together with the computed heart rate and/or breathing rate will be plotted and the mean HR and BR per event will be saved to disk.

 Input Files

  1. Physiological Recordings:
    One pair of *_physio.tsv.gz and _physio.json files for one functional scan. 
    Both files should use the suffix "_physio". The compressed tsv file contains the continuous physiological recordings (cardiac and/or respiratory data) without header lines and with the last column representing the scanner trigger signal (coded with 0 and 1). The json file contains the following meta data: SamplingFrequency in Hz of all the data in the recording, StartTime in seconds in relation to the acquisition start of the first functional volume, name of Columns in the compressed tsv file. 
    Importantly, as specified by the BIDS standard: "Recordings with different sampling frequencies and/or starting times should be stored in separate files." In case of separate respiratory and cardiac files, both sets of files should be selected at the same time. The following naming scheme would be beneficial: sub-id_ses-id-task-name_run-id_recording-respiratory(or cardiac)_physio.tsv.gz.
    If you have physiological signals from SIEMENS advanced physiological log or DICOM files, you can use the script together with the script (from Marcel Zwiers) to convert these data traces to the BIDS standard.

    Physio JSON 20220719                          Physio TSV 20220719
  2.  fMRI Data:
    The corresponding functional document of BrainVoyager (*.fmr). This file must have been created with BrainVoyager 21.4 or newer and will be used to extract and compare important scanning parameters.

  3. Timing Information of the Experimental Task (Optional):
    A corresponding stimulation protocol file (*.prt) can be loaded. This file will be used to plot and save the mean heart- and/or respiratory rate per stimulus condition and per event to disk.

  4. A Single-Study Design Matrix (Optional):
    A corresponding single-study design martix (*.sdm), containing the regressors of the task design or any confound regressors that the user would like to correlate with the derived physiological noise regressors. These correlations will be plotted in a correation matrix and saved to disk.

Output Files

All resulting files will be saved in a directory called 'PhysioOut', which is created in the same folder as the specified FMR file. All created files will have the same base filename as the FMR file followed by _*.

  1. Images of the Physiological Data Traces and Some Derived Noise Regressors:
    Two PNG files showing the cardiac and respiratory signal, the identified peaks, the functional scan time and some of the derived physiological noise regressors. 

    sub 01 ses 01 task mentaldrawing run 01 bold cardiac 20220719

    sub 01 ses 01 task mentaldrawing run 01 bold resp 20220719
  2. Input and Output Parameters:
    The Input, output and processing parameters will be saved in JSON files (*_InputParameters.json, *_OutputParameters.json)

    Physio InputParameters JSON 20220719                                           Physio OutputParameters JSON 20220719

  3. Resulting Physiological Noise Regressors :
    Separate design matrix files that can be used for physiological noise correction of the fMRI data will be saved to disk, including *_cardiac_BP0.5-8Hz_z.sdm, *_resp_filtz.sdm, *_cardiacresp_RETROICOR.sdm, *_HR.sdm, *_HRCRF.sdm, *_RV.sdm, *_ENV.sdm, *_RVT.sdm, *_RVTRRF.sdm, *_RVRRF.sdm). One TSV file with all physiological regressors will also be saved *_PhysiologicalNoiseRegressors.tsv 

  4. Task x Physiological Noise Correlation:
    Provided that the user specified a task design matrix files as input, a task x noise correlation matrix with the corresponding p-values is saved as *_CorrelationMatrixNoiseTaskRegressors.tsv and as *_TaskNoiseCorr.png
    sub 01 ses 01 task mentaldrawing run 01 bold TaskNoiseCorr 20220719
  5. Plotting the Experimental Design and the Heart- and/or Respiratory Rate of the Participant:
    Provided the user specified a *.prt file with the experimental timings of the functional run, the stimulation protocol together with the heart- and/or respiratory rate will be plotted and saved as *_PRT_PhysioRate.png
    sub 01 ses 01 task mentaldrawing run 01 bold PRT PhysioRate 20220917


User-Specified Parameters in the Script

The section "user-specified parameter" in the script allows to adapt some input, processing and output parameters. Most values are set to reasonable defaults and don't need to be changed. References to relevant papers can be found in the comments of the script (next to the specific parameters).

physio_1file = True

cardiac_low = 0.5
cardiac_high = 8

order_cardiac = 2
order_resp = 2
order_cardresp = 0

outlier_cardiac_threshold = 30
nIBIs = 5

min_hbi = 0.60

hr_filloutliers_window = 25
hr_filloutliers_threshold = 10

hr_shifts = np.arange(0, 25, 2)

resp_filloutliers_window = 0.25
resp_filloutliers_threshold = 3

rvt_shifts = np.arange(0, 21, 5)

rv_shifts = np.arange(-7, 8, 7)

env_shifts = np.arange(-7, 8, 7)

min_pvalue = 0.05