Extracting interpretable signatures of whole-brain dynamics through systematic comparison

This repository contains code to accompany our preprint, "Extracting interpretable signatures of whole-brain dynamics through systematic comparison". Users may follow this repo to reproduce all analyses and visualizations contained in the preprint -- broadly, this includes extracting time-series features from functional magnetic resonance imaging (fMRI) data to serve as the basis for a series of linear support vector machine (SVM) classifiers for case--control comparisons.

All code is a mixture of R and python, with shell scripts used to execute operations. Please note that the repository is structured such that some steps are designed to be run on a high-performance computing (HPC) cluster for parallelization with a PBS job scheduler.

Data availability

All resting-state fMRI data used in this study is freely accessible to the public via open sharing platforms.

• UCLA Consortium for Neuropsychiatric Phenomics (CNP) LA5c study: raw imaging volumes were accessed from OpenfMRI, accession number ds000030.
• Autism Brain Imaging Data Exchange (ABIDE) I/II study: preprocessed fMRI time series (with the Harvard-Oxford parcellation atlas) were accessed from Zenodo at Traut et al. (2020).

❗ All intermediate data files needed to replicate analysis and visuals in this repo (including those >100MB) are provided in this Zenodo repository.

Usage

Installation

First, clone this repository to your local machine:

```bash
git clone https://github.com/DynamicsAndNeuralSystems/fMRI_FeaturesDisorders.git
```

Parts of this project are in R (v4.3.0), and parts are in Python (v3.9.0). We recommend that users create a conda environment for this project, which can be accomplished as follows:

```bash
conda create -n fMRI_FeaturesDisorders python=3.9.0
conda activate fMRI_FeaturesDisorders
```

From this conda environment, install the required Python packages:

```bash
pip install -r python_requirements.txt
```

R packages required for feature extraction and classification analysis can be installed from R_requirements.txt as follows:

```bash
while IFS=" " read -r package version; do Rscript -e "devtools::install_version('"$package"', version='"$version"')"; done < "R_requirements.txt"
```

Data visualization

Additional R packages will be needed to reproduce visualizations for the manuscript in generate_all_figures.ipynb, which can be installed with the following:

```bash
while IFS=" " read -r package version; do Rscript -e "devtools::install_version('"$package"', version='"$version"')"; done < "R_requirements.txt"
```

Preparing data

After downloading the prepared data files from Zenodo as listed above, create a data folder in this repository and place the downloaded files within that folder. This will get all files into their needed locations for feature extraction, classification, and visualization described in following.

Extracting time-series features

Please refer to the extract_time_series_features.ipynb Jupyter notebook for a walkthrough of how to extract intra-regional and inter-regional time series features from each participant's blood oxygen level dependent (BOLD) time series. You can interactively click through each code chunk with a Jupyter notebook reader like VSCode (with the Jupyter extension installed) or the Jupyter Notebook app from Anaconda.

Alternatively, to run the notebook from the command line, you can use the following code:

jupyter nbconvert --to notebook --execute extract_time_series_features.ipynb --allow-errors

The --allow-errors flag allows the whole file to execute even if an error occurs, which can be helpful for debugging (and is optional if you prefer to omit the flag). This will yield the file extract_time_series_features.nbconvert.ipynb that includes all code output from the notebook.

Performing case--control classification

Once all intra- and inter-regional time-series features have been computed across all participants, we can fit linear support vector machine (SVM) classifiers for each of the five statistical representations evaluated in the manuscript:

1. A_region: represents each fMRI time series using a set of features capturing 25 dynamical properties of an individual brain region.
2. A_feature: represents each fMRI time series using a set of features that captures a single dynamical property from all brain regions (82 for SCZ, BP, and ADHD, and 48 for ASD).
3. A_{uni_combo}: represents each fMRI time series using a set of features combining the 25 time-series properties of each individual brain region.
4. A_FC: represents each fMRI time series using a set of features that capture all pairs of inter-regional coupling strengths computed using a single statistic of pairwise interactions (SPI).
5. A_{FC_combo}: represents each fMRI dataset as a set of features that capture all pairs of inter-regional coupling from a given SPI (as A_FC) as well as 25 time-series properties of all individual brain regions (as A_{uni_combo}).

These representations are all evaluated using fit_classifiers.ipynb, which can also be run interactively in a Jupyter notebook viewer or run from the command line using:

jupyter nbconvert --to notebook --execute fit_classifiers.ipynb --allow-errors

Data visualization

All figures included in the manuscript can be recreated using the Jupyter notebook generate_all_figures.ipynb. You can run this from the command line and view outputs with the following:

jupyter nbconvert --to notebook --execute fit_classifiers.ipynb --allow-errors

Contact

If you have any questions or need further assistance, please contact annie.bryant@sydney.edu.au.