Quantitative Susceptibility Mapping
This tutorial was created by Steffen Bollmann and Ashley Stewart.
Getting Setup with NeurodeskFor more information on getting set up with a Neurodesk environment, see here
An example notebook can be found here: https://github.com/NeuroDesk/example-notebooks/blob/main/books/structural_imaging/qsmxt_example.ipynb
Quantitative Susceptibility Mapping in Neurodesk with QSMxT
Neurodesk provides QSMxT, an end-to-end pipeline that automates the reconstruction, segmentation and analysis of QSM data across large groups of participants, from scanner images (DICOMs) through to susceptibility maps and quantitative outputs.
QSMxT provides pipelines implemented in Python that:
- Automatically convert unorganised DICOM or NIfTI data to the Brain Imaging Data Structure (BIDS)
- Automatically reconstruct QSM, including steps for:
- Phase unwrapping
- Background field removal
- Dipole inversion
- Multi-echo combination
- Automatically generate a common group space for the cohort, as well as average magnitude and QSM images that facilitate group-level analyses.
- Automatically segment T1w data and register them to the QSM space to extract quantitative values in anatomical regions of interest.
- Export quantitative data to CSV for all subjects using the automated segmentations, or a custom segmentation in the group space (we recommend ITK-SNAP to perform manual segmenations).
For a list of algorithms QSMxT uses, see the Reference List on the GitHub page.
Start QSMxT v1.3.3 from the applications menu in the desktop (Neurodesk > Quantitative Imaging > qsmxt)
Download test DICOMs
Start by downloading the test DICOM data we provide for QSMxT:
osf -p ru43c clone qsmxt-demo unzip qsmxt-demo/osfstorage/GRE_2subj_1mm_TE20ms/sub1/GR_M_5_QSM_p2_1mmIso_TE20.zip -d qsmxt-demo/0_dicoms unzip qsmxt-demo/osfstorage/GRE_2subj_1mm_TE20ms/sub1/GR_P_6_QSM_p2_1mmIso_TE20.zip -d qsmxt-demo/0_dicoms unzip qsmxt-demo/osfstorage/GRE_2subj_1mm_TE20ms/sub2/GR_M_5_QSM_p2_1mmIso_TE20.zip -d qsmxt-demo/0_dicoms unzip qsmxt-demo/osfstorage/GRE_2subj_1mm_TE20ms/sub2/GR_P_6_QSM_p2_1mmIso_TE20.zip -d qsmxt-demo/0_dicoms
Convert DICOMs to BIDS
Next, we need to sort the DICOMs into the structure QSMxT expects (by subject, session, and series), and then convert to the Brain Imaging Data Structure (BIDS) by running the following:
cd qsmxt-demo run_0_dicomSort.py 0_dicoms 1_dicoms_sorted run_1_dicomConvert.py 1_dicoms_sorted 2_bids
The conversion to BIDS will prompt you to enter which sequence matches your QSM data. For the demo data, you can simply enter
1 when prompted:
The demo data comes without a structural scan (automatically recognised if
t1w is in the protocol name.
Run QSM pipeline
Finally, we can run the QSM pipeline using:
run_2_qsm.py 2_bids 3_qsm
You will first be prompted to choose an initial premade pipeline. Simply press ENTER to use the default pipeline, or choose one of the other premade pipelines (e.g.
fast for QSMxT’s fastest reconstruction pipeline):
QSMxT then allows you to adjust any relevant reconstruction settings. The defaults should be fine for this data, so simply enter ‘run’:
The reconstruction may take some time, though QSMxT will attempt to run various processes in parallel wherever possible.
View QSM results
When the processing is finished, you can open a viewer (Visualization -> mricrogl -> mricroglGUI) and you can find the QSM outputs in /neurodesktop-storage/qsmxt-demo/3_qsm:
Please note that the demo dataset does not have a T1w scan for anatomical segmentation, and therefore the subsequent steps in QSMxT (e.g.
run_3_segment.py 2_bids 4_segmentation) will NOT work.