Quantitative Susceptibility Mapping

This tutorial was created by Steffen Bollmann and Ashley Stewart.

Github: @stebo85; @astewartau Web: mri.sbollmann.net Twitter: @sbollmann_MRI

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:

1. Automatically convert unorganised DICOM or NIfTI data to the Brain Imaging Data Structure (BIDS)
2. Automatically reconstruct QSM, including steps for:
   1. Masking
   2. Phase unwrapping
   3. Background field removal
   4. Dipole inversion
   5. Multi-echo combination
3. Automatically generate a common group space for the cohort, as well as average magnitude and QSM images that facilitate group-level analyses.
4. Automatically segment T1w data and register them to the QSM space to extract quantitative values in anatomical regions of interest.
5. 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.

Open QSMxT

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.