Skip to content

Setup

Jump to bottom
Brian Pho edited this page Nov 10, 2022 · 12 revisions

The instructions below teach you how to run the preprocessing and modeling, which are separate stages and separate programs. Due to the Healthy Brain Network (HBN) policy, the dataset isn't provided on GitHub and but can be obtained here. The preprocessing was done in MATLAB using the Automatic Analysis (AA) package and only needs to be run once on the data. The modeling was done in Python using Anaconda and Jupyter Notebook. All programs and code were run on a remote NoMachine server running Ubuntu 20.04.

Preprocessing

To preprocess the HBN data, start by downloading it. The data for this project was organized by age folders but your folder organization may differ. This isn't an issue and only requires modifying the AA script. Ensure to have the following prerequisite software packages:

I used this exact list of software packages to preprocess the data, but you can modify the code for your software setup such as newer MATLAB and AA versions. Once the prerequisite software is installed, follow these steps.

  1. Modify the paths in aa_user_bpho.m to match where your data is located and where you want to output the processed data.
  2. Modify the code in aa_user_bpho.m to read your data structure. This step isn't necessary if your data is organized by age folders.
  3. Confirm that the preprocessing modules in aap_tasklist_bpho.xml are the ones that you want to run. You may want to change some modules for your use-case.
  4. Run the script aa_user_bpho.m in MATLAB to preprocess the data. The console should output a lot of text during this process, which means the preprocessing is working.
  5. If the script encounters errors during preprocessing, you can exclude that participant by adding their ID to the bad_subject_IDs variable in the script or you can delete the participant folder. Then rerun the processing until it finishes.

Modeling

To model the HBN data, we first transform the fMRI data (outputted from preprocessing) into functional connectivity (FC) matrices based on the Power atlas. This transformation from fMRI to FC matrices only needs to be done one time because the FC matrices are stored. After FC generation, we clean the phenotypic data (WISC measures such as IQ). Next, we apply various machine learning models to the data by feeding in the FC matrices as the features (X) and the WISC measures as targets (y). Lastly, we analyze the models by extracting the model's feature weights and visualizing them. There are other methods to analyze models such as permutation feature importance and advanced visualizations. Ensure to have the following prerequisite software packages:

Initial setup

  1. Download/clone the repo to some location on your computer. If you're using the command line, run git clone https://github.com/Brian-Pho/MSc_Research-Project to clone the repo.
  2. Run conda env create -f [repo_location]/environment.yml to recreate the Anaconda environment with the correct packages and versions. This may take some time as Anaconda downloads all of the necessary packages.
  3. Run source activate venv to activate the environment. You'll know this worked if the command line now has (venv) to the left of your username.
  4. Run python -m ipykernel install --user --name venv --display-name "venv" to link Jupyter Notebook with the Anaconda environment (see this for more details).
  5. Run python [repo_location]/src/setup.py develop to install the custom Python package for this repo (see this for more details). I've been having problems with this so if this doesn't work or you don't want to do this, you can try restarting Anaconda. Another solution is to run the following Python snippet in a Jupyter notebook or the command line (make sure you're in the 'venv' environment):
import sys
custom_pkg_src = '[repo_location]/src/'
if not custom_pkg_src in sys.path:
    sys.path.insert(0, custom_pkg_src)

Running the analysis and modeling

Once the prerequisite software is installed, follow these steps.

  1. Open a terminal and run anaconda-navigator. The Anaconda GUI should pop up.
  2. Choose the virtual environment that has the prerequisite packages; this should be 'venv' if you followed the initial setup.
  3. Launch the 'Jupyter Lab' or 'Jupyter Notebook' application in Anaconda (they're functionally identical, but I prefer Jupyter Lab's UI).
  4. Navigate to the where the *.ipynb scripts are located ('src' folder in the cloned repo) and open the script that you want.
  5. Change the kernel from the default one to the Anaconda 'venv' one by going to 'Kernel' -> 'Change kernel' -> 'venv'. This ensures the script runs with the correct set of packages.
  6. Run the code blocks (cells) in the script to explore, analyze, and model the data.
  7. Generally, the cells should be run sequentially from top-down and the import cells only need to be run once every session (until the kernel is shutdown). However, there may be cases where you have to change the paths or comment out lines to get the code to run without errors.

NOTE: Some of the code is "hacky" in that if I needed to quickly change a dataset population or filename, I commented out the original code. So if the script doesn't run perfectly, know that some of the code was changed between runs and may require adjustments.

Clone this wiki locally