> For the complete documentation index, see [llms.txt](https://docs.ccv.brown.edu/bnc-user-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ccv.brown.edu/bnc-user-manual/analysis-pipelines/quantitative-susceptibility-mapping-qsm.md).

# 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](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.30006) provides extremely helpful guidance for MR protocol design and QSM analysis methods. Here, we'll highlight one analysis method using the [QSMxT toolbox](https://qsmxt.github.io/QSMxT/) 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](https://onlinelibrary.wiley.com/action/downloadSupplement?doi=10.1002%2Fmrm.29048\&file=mrm29048-sup-0001-Supinfo.pdf), but further tweaks might be needed depending on your specific regions of interest, etc.

{% file src="/files/9lHZ7sN42rRGtJuYRDkA" %}

For the data to automatically be converted into BIDS format with [xnat2bids](https://docs.ccv.brown.edu/bnc-user-manual/xnat-to-bids-intro/xnat2bids-software.md), the protocol name needs to be "[BIDS-ready](https://docs.ccv.brown.edu/bnc-user-manual/xnat/bids-compliant-protocols.md)" and begin with "anat-MEGRE".

## Installing QSMxT on Oscar

The QSMxT toolbox has [recently been fully re-written](https://qsmxt.github.io/QSMxT/getting-started/coming-from-8x/) and is now much easier to install on Oscar:

1. In a terminal on Oscar, download and run the qsmxt installation script\
   `curl -fsSL https://raw.githubusercontent.com/QSMxT/QSMxT/main/install.sh | sh`
2. Close the terminal and open a new one, so that the toolbox is added to your path and ready to use
3. Check that the toolbox is installed correctly

   ```bash
   qsmxt --version
   qsmxt --help
   ```

## Using QSMxT on Oscar

Visit the [QSMxT documentation](https://qsmxt.github.io/QSMxT/getting-started/quick-start/) for more details on each of these steps and possible settings, and take a look at [their paper - Stewart et al., 2021 -](https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.29048) for more information.

1. Get your data into valid BIDS format ([xnat2bids](https://docs.ccv.brown.edu/bnc-user-manual/xnat-to-bids-intro/using-oscar/oscar-utility-script.md) can help you with this!).&#x20;

2. For this first participant, we'll be running the analysis locally on Oscar, so open an OOD Desktop session with at least 15GB of memory.

3. Open a terminal and launch the qsmxt [interactive terminal user interface](https://qsmxt.github.io/QSMxT/guides/running-interactively/) (TUI)

   ```bash
   qsmxt tui
   ```

4. Follow the interactive prompts in the Input tab to specify your BIDS directory. By default, the output directory will be in bids/derivatives/qsmxt, but you can specify a different output directory if you'd like. If you only want to analyze a subset of the data in your BIDS directory, you can set "Include" and/or "Exclude" filters to limit the data that is selected.

   <figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2FQjQLVbuT6KDnsfLnqakG%2Fqsmxt_bids.png?alt=media&amp;token=2b6bb548-6427-4082-a2ea-d164bf7bf36e" alt="enter the full path to the bids directory under &#x22;BIDS directory&#x22;"><figcaption></figcaption></figure>

5. The defaults in the Preprocessing, QSM, and χ-separation tabs are reasonable, so we'll leave them. In the future, you can tailor these further to your analysis needs if you'd like.

6. Choose any additional outputs you'd like the toolbox to create. Our MEGRE protocol is sufficient for the creation of SWI, SMWI, T2\*, and R2\* maps, segmentation, and the calculation of per-structure statistics. Take a look at the [toolbox documentation](https://qsmxt.github.io/QSMxT/getting-started/quick-start/) for more information on each of these outputs.

   <figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2FF7AA2RdSYtC7MOwHcPBX%2FScreenshot%202026-11-10%20at%2011.55.35%E2%80%AFAM.png?alt=media&amp;token=e323a504-96cf-4e6a-87f8-a090e27c8816" alt=""><figcaption><p>selecting the SWI/SMWI output options</p></figcaption></figure>

   <figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2FUnWLQxscHhPpl325hGq8%2FScreenshot%202026-11-10%20at%2011.56.04%E2%80%AFAM.png?alt=media&amp;token=8d906637-493a-4090-9253-4935627b203d" alt=""><figcaption><p>selecting the relaxometry output options</p></figcaption></figure>

   <figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2Fgv48mCEwtEVNJN2ZKnyY%2FScreenshot%202026-11-10%20at%2011.56.25%E2%80%AFAM.png?alt=media&amp;token=46d3c89e-62eb-422c-ae7a-7553db085184" alt=""><figcaption><p>selecting the segmentation output options</p></figcaption></figure>

7. Select "Run" under the "Execution" tab. Keep an eye on your terminal window to monitor progress; you should see the message "All runs completed successfully" when it completes.

8. Check out the outputs! Unless you specified otherwise, all output files will be in /bids/derivatives/qsmxt.&#x20;

   <figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2FF39byAIcs0g1hrIPtE95%2FScreenshot%202026-11-10%20at%2012.21.15%E2%80%AFPM.png?alt=media&amp;token=bd72335f-7517-4eea-8e55-5ecb8e781aff" alt=""><figcaption></figcaption></figure>

9. The outputs are [described in the qsmxt documentation here](https://qsmxt.github.io/QSMxT/reference/outputs/).&#x20;

<figure><img src="https://4276957606-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtSg7ZEM6EHbi9iE84a%2Fuploads%2F5fOwDEvslXjGtLKVAOdp%2FScreenshot%202024-12-10%20at%201.31.15%20PM%20copy.png?alt=media&amp;token=44164af8-474c-4a7b-ac48-4c5929f59b04" alt="An example chimap of the brain, output from qsmxt. This chimpa is overlaid onto the anatomical scan and is viewed from the three planes (coronal, transverse, and sagittal)."><figcaption><p>example chimap</p></figcaption></figure>
