Material for the OHBM 2023 Educational Course Tutorial, "One person's noise is another person's signal: hands-on tutorial to model cerebrovascular reactivity in BOLD fMRI data"

This repository contains the example code to follow along with the OHBM 2023 Educational Course Tutorial One person's noise is another person's signal: hands-on tutorial to model cerebrovascular reactivity in BOLD fMRI data, part of the Educational Course Physiologic fMRI signals: friend or foe? How and why to measure, model, and account for physiology. See here for the other tutorials in the same Educational Course.

Thank you to Stefano Moia for preparing these instructions! If you setup your laptop and followed along with his tutorial in this course (see here), you will only need to install phys2cvr.

❗Note that building wxPython may take 30-45 minutes depending on your system, so plan accordingly!❗

Laptop setup

To follow this tutorial, you will need a laptop, requiring a little bit of setup beforehand.

0. Prerequisites

You will need a laptop with python installed, as well as pip. Python version should be 3.7 or above. You also need to download the files in this repository, either zipped in a package or by locally cloning the repository.

1. Optional - Set up a virtual environment

The best way to ensure the software functioning without changing anything in your system is using a virtual environment. For that, first install virtualenv:

pip install -U virtualenv

(Note you might need to use pip3 instead of pip, depending on your OS and setup, to work with python 3)

Then, create and activate the virtual environment - in this case I called it ohbm23cvr, but you can use a different name:

virtualenv ohbm23cvr
source ohbm23cvr/bin/activate

Note that the first command above will create a folder where you called it from, and the second command assumes this is the case - if you want you can specify a different path though.

Once you activated the virtual environment, you can proceed with package installation

2. Package installation

You will need to install a few python packages. First and foremost, wxPython. Its installation depends on the OS you are using. While you can find detailed instructions here, following is the summary.

Install wxPython on Windows and macOS

pip install -U wxPython

(Note you might need to use pip3 instead of pip, depending on your OS and setup, to work with python 3)

Install wxPython on Linux

Check this folder for the right python package, depending on the version of GTK you are using, as well as your OS, then using the link to the right folder, install wxPython version 4.2.0, if possible. In this example, I will assume we're working with GTK3 on Ubuntu 20.04:

pip install -U \
    -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04 \
    wxPython==4.2.0

(Note you might need to use pip3 instead of pip, depending on your OS and setup, to work with python 3)

Install all other packages

You also need to install peakdet and phys2cvr. Optionally, you can also install ipython, a nice CLI environment to work with python.

The fastest option is to use the requirements.txt file in this repository:

pip install -U -r path/to/requirements.txt

(Note you might need to use pip3 instead of pip, depending on your OS and setup, to work with python 3)

Alternatively, you can install directly what you need. Please ensure to install matplotlib version 3.6.3 or below, otherwise you will incur a deprecation error:

pip install -U peakdet phys2cvr matplotlib==3.6.3 ipython

(Note you might need to use pip3 instead of pip, depending on your OS and setup, to work with python 3)

3. Check the installation

Within the virtual environment, you can either call pip to list your packages (pip list or pip3 list), or open ipython and import peakdet and phys2cvr

import peakdet
import phys2cvr

If you have no issues doing that, you're all good to go!

Note that peakdet's GUI might not work in GUI-like environments like Jupyter notebooks or Spyder

4. Download files for the tutorial

You can downlaod some files that contain data for the tutorial - we will be using these files during the live tutorial.

All the files can be downloaded in a zip folder here.

This folder includes BOLD fMRI data, associated physiological data including CO2, motion parameters, brain mask, and gray matter mask.

In this repository

• prep_co2.py: Python script that uses peakdet to identify end-tidal CO2. The outputs of this script are needed to run the lagged-GLM with phys2cvr. You can run this script in an IDE like Spyder, or line-by-line from the terminal with iPython.
• run_phys2cvr.sh: executable shell script that can be used to automate phys2cvr. You will need to change the input directory to where your input files are * located, and the output directory to the path where you want the phys2cvr outputs saved.
• viridis_pos.cmap: half of viridis colormap that can be loaded to fsleyes for visualizing lag maps. Set as the negative colorbar in fsleyes.
• viridis_neg.cmap: half of viridis colormap that can be loaded to fsleyes for visualizing lag maps. Set as the positive colorbar in fsleyes.