xQSM

xQSM: Quantitative Susceptibility Mapping with Octave Convolutional and Noise-Regularized Neural Networks

NMR Biomed 2021  |  arXiv  |  data & checkpoints  |  deepMRI collection

xQSM is an octave convolutional neural network for QSM dipole inversion, with built-in noise regularization. Both MATLAB and PyTorch implementations are provided.

Update (March 2025): New user-friendly MATLAB wrappers for xQSM/xQSM+/iQSM+/iQSM/iQFM with simpler syntax — see the iQSM+ repo.

Note (Nov 2022): Minor bugs in the Python version and checkpoints have been corrected.

---

Overview

Framework

Fig. 1: Overview of xQSM. Octave convolution introduces an X-shaped operation for communication between feature maps of different resolutions, built on a U-net backbone with a noise-adding layer.

Representative Results

Fig. 2: Comparison of QSM methods on 10 in vivo local field maps (five 0.6 mm at 7T, five 1 mm at 3T). Yellow arrows indicate DGM susceptibility contrast loss relative to COSMOS.

---

Requirements

• Python 3.7+, PyTorch 1.4+
• NVIDIA GPU (CUDA 10.0+)
• MATLAB R2019a+ (for MATLAB implementation)

Tested on: CentOS 7.8 (Tesla V100), Windows 10 / Ubuntu 19.10 (GTX 1060).

---

Quick Start

MATLAB demo

% Navigate to the matlab/eval folder
cd matlab/eval
run_demo   % compares 4 QSM networks on demo data using COSMOS as ground truth

Download demo data from Dropbox.

Python demo

# Open the Jupyter notebook
jupyter notebook python/eval/run_demo.ipynb

---

Installation

git clone https://github.com/sunhongfu/xQSM.git
cd xQSM

conda create -n xQSM python=3.8
conda activate xQSM
conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
conda install scipy nibabel

---

Reconstruction on Your Own Data

Prepare your local field map in NIfTI format and replace the demo data in the scripts. Key parameters to update:

• lfs / lfs_path — local field map
• mask — brain mask
• vox — voxel size in mm
• z_prjs — B0 direction (z-projections)

---

Training

Training scripts are provided for both implementations:

% MATLAB
cd matlab/training
% edit training parameters then run training script

# Python
cd python/training
python train_xQSM.py

---

Citation

@article{xqsm2021,
  title={xQSM: quantitative susceptibility mapping with octave convolutional and noise-regularized neural networks},
  journal={NMR in Biomedicine},
  year={2021},
  doi={10.1002/nbm.4461}
}

---

⬆ top  |  deepMRI collection