Quantitative Susceptibility Mapping (QSM)

Using the QSMxT toolbox to create whole-brain quantitative magnetic susceptibility maps

Quantitative susceptibility mapping is a computational method that uses the magnitude and phase information from a T2*-weighted gradient recalled echo (GRE) MR sequence to quantify magnetic susceptibility across the brain. This method is useful for distinguishing between different tissue types and quantifying properties like tissue iron deposition.

A recent QSM consensus paper provides extremely helpful guidance for MR protocol design and QSM analysis methods. Here, we'll highlight one analysis method using the QSMxT toolbox on Oscar.

QSM scanner protocol

Our protocol is a multi-echo (5 echoes) GRE protocol, with both the magnitude and phase data saved. Parameter choices directly follow the recommendations of the consensus paper, but further tweaks might be needed depending on your specific regions of interest, etc.

anat-MEGRE_acq-qsmconsensus.pdf

PDF · 68KB

Open

For the data to automatically be converted into BIDS format with xnat2bids, the protocol name needs to be "BIDS-ready" and begin with "anat-MEGRE".

Installing QSMxT on Oscar

We largely follow the QSMxT installation instructions for HPCs:

1. In a terminal on Oscar, change to whichever directory you would like to install the QSMxT image and scripts into (I have a "scripts" directory in my home directory, but you can put it wherever you'd like).

2. Clone the toolbox into this directory

   git clone https://github.com/astewartau/transparent-apptainer qsmxt_8.2.2_20260105

3. Change directory into this new downloaded folder and run their "transparent singularity/apptainer" script, which sets up your environment in a way that lets you use their tools from the command line, even though they're in a Singularity/Apptainer container

   cd qsmxt_8.2.2_20260105
   ./run_transparent_apptainer.sh --container qsmxt_8.2.2_20260105.simg
   source activate_qsmxt_8.2.2_20260105.simg.sh

4. Load the miniforge3 module on Oscar

   module load miniforge3
   source $MAMBA_ROOT_PREFIX/etc/profile.d/conda.sh

5. Create a conda environment in which the QSMxT toolbox is installed

   conda create -n qsmxt python=3.8
   conda activate qsmxt
   pip install qsmxt==8.2.2

Now, any time you want to use the QSMxT toolbox, you'll need to

module load miniforge3
source $MAMBA_ROOT_PREFIX/etc/profile.d/conda.sh
conda activate qsmxt

Using QSMxT on Oscar

Visit the QSMxT documentation for more details on each of these steps and possible settings, and take a look at their paper - Stewart et al., 2021 - for more information.

1. Get your data into valid BIDS format (xnat2bids can help you with this!).

2. Edit your ~/.bashrc file to:

   1. Comment out as many module load lines as possible. module load r/4.4.0-c4wv causes conflicts via py-setuptools, and other modules may as well.

   2. Add a line that says export APPTAINER_BINDPATH="/path/to/data/directory" This needs to be a full path to wherever your BIDS data directory is. For example, if my BIDS directory is in /oscar/data/myusername/xnat-exports/bnc/study-qsm, I can use export APPTAINER_BINDPATH="/oscar/data/myusername" , which will give the QSM apptainer container access to any files in my data directory.

3. Open a new terminal and activate your qsmxt environment

   module load miniforge3
   source $MAMBA_ROOT_PREFIX/etc/profile.d/conda.sh
   conda activate qsmxt

4. Launch qsmxt and give it your bids directory

   qsmxt bids

5. Follow the interactive prompts to specify your desired outputs

   
6. Choose your desired pipeline

   
7. Take a look at the resulting settings; make any changes necessary, or type run to launch the analysis

   
8. This will automatically create an output directory within your bids directory under /derivatives. If requested, you'll get a QSM map labeled _Chimap that looks like this!

example chimap