A browser-based anomaly detection framework for diffusion MRI using Tractometry. This repository contains the scripts used in Chamberland et al. 2021. If using, please cite the following:
Chamberland, M., Genc, S., Tax, C.M.W. et al. Detecting microstructural deviations in individuals with deep diffusion MRI tractometry. Nat Comput Sci 1, 598–606 (2021). https://doi.org/10.1038/s43588-021-00126-8
- 🌟 Click here for Detect (simply hit Run!)
- 🌟 Click here for Inspect (simply hit Run!)
Note: Streamlit servers may sometimes be overloaded - in this case, try refreshing the page.
This requires:
as well as plotting libraries described in the requirements.txt file. Run:
git clone https://github.com/chamberm/Detect
cd Detect
#Create a new environment
conda create --name Detect python=3.7
conda activate Detect *OR* source activate Detect
pip install -r requirements.txt
pip install -e .
The input demographic data that consists of comma-separated values (.csv) where each row represents a subject (ID). Example demographics columns include: group, age, gender or clinical scores.
The microstructural tractometry data format consist of a .xlsx spreadsheet, where each sheet represents a dMRI measure (e.g., FA, MD, AFD, RISH, etc.). As per the demographic data, subjects are stacked individually on each rows. The first column denotes the ID of each subject. The remaining columns follow the following convention: BUNDLE_HEMI_SECTION where BUNDLE is the white matter bundle of interest, HEMI is the hemisphere (i.e., left or right and void for commissural tracts), and SECTION is the along-tract portion (e.g., from 1 to 20).
The framework offers three main script: Detect, Inspect and Relate. Both Detect and Inspect scripts allow the visualization of tract profiles. Finally, Relate is a simple visual interface to correlate the anomaly scores obtained by the previous commands with clinical scores.
Detect allows for group comparisons using cross-validated AUCs computed over N iterations, by means of Z-score, PCA or AE. The output is a robust, bootstrapped anomaly score for each subject.
python ./bin/detect.py --i DATA.xlsx --demog DEMOG.csv
- Load your dataset
- Input a savename on the left (e.g., my_analysis).
- Choose a metric from the dropdown menu (e.g., RISH0).
- Choose a patient group (when multiple groups are present).
- Choose an anomaly detection method (e.g., AutoEncoder).
- Choose the number of iterations to bootstrap over (e.g., 50, 100).
- You can visualize the tract-profiles using the options on the main page (remember to turn them off before lauching the analysis).
- Choose the desired features (tracts) to include in the analysis.
- Hit the Run button on the bottom left panel.
The global anomaly scores of each subject will be saved as: tests/scores_METRIC_METHOD_SAVENAME.csv and the ROC AUC under tests/auc_METRIC_METHOD_SAVENAME.csv
On the other hand, Inspect allows the user to select a single subject and to compare it with the rest of the population. Here, anomalies in the features are highlighted using a leave-one-out cross-validation approach.
python ./bin/inspect.py --i DATA.xlsx --demog DEMOG.csv
- Load your dataset
- Input a savename on the left (e.g., my_analysis).
- Choose a metric from the dropdown menu (e.g., RISH0).
- Choose a patient group (when multiple groups are present).
- Choose subject to inspect.
- You can visualize the tract-profiles using the options on the main page. Remember to turn them off before lauching the analysis.
- If you desire, the Run all option will iterate over all subjects to test them against the healthy controls.
- Hit the Run button on the bottom left panel.
The overall anomaly score of that subject will be saved as: tests/p-val_METRIC_SAVENAME.csv and the along-tract profile figure under figures/SUBJECT_profile_METRIC.png.
Note: the examples directory contains notebooks with code used to generate the results and figures from the paper.
Please note that Detect is for research use only.
Maxime Chamberland Website