/QSM

Hongfu Sun's MATLAB codes for QSM reconstruction pipeline.

Primary LanguageMATLABMIT LicenseMIT

Welcome to QSM

For deep learning-based QSM methods, check out the other github repo: deepMRI

The repository is for reconstructing Quantitative Susceptibility Mapping (QSM) images from MRI. The codes cover image recons for single-echo SWI or multiple-echo GRE sequence as well as gradient EPI sequence.

References

  • For the background field removal method RESHARP, please reference:
    H. Sun, A.H. Wilman. Background field removal using spherical mean value filtering and Tikhonov regularization. Magn Reson Med. 2014 Mar;71(3):1151-7.
  • For the POEM multi-channel coil combination method, please referece:
    H. Sun, J.O. Cleary, R. Glarin, S.C. Kolbe, R.J. Ordidge, B.A. Moffat, G.B. Pike; Extracting more for less: Multi-echo MP2RAGE for simultaneous T1-weighted imaging, T1 mapping, R2* mapping, SWI, and QSM from a single acquisition.
  • For the EPI-QSM processing pipeline, please referece:
    H. Sun, A.H. Wilman. Quantitative susceptibility mapping using single-shot echo-planar imaging. Magn Reson Med. 2015 May;73(5):1932-8.
  • For the hemorrhage-QSM method and processing pipeline, please referece:
    H. Sun, M. Kate, L.C. Gioia, D.J. Emery, K. Butcher, A.H. Wilman. Quantitative susceptibility mapping using a superposed dipole inversion method: Application to intracranial hemorrhage. Magn Reson Med. 2016 Sep;76(3):781-91.

Recon flow

  1. Extract complex img from DICOMs or raw files
  2. removal phase-offsets if multiple-echo, then combine coils
  3. extract brain mask
  4. unwrap phase maps
  5. linearly fit unwrapped phase with TE if multiple-echo
  6. background field removal
  7. dipole inversion

Support scanner platforms

  • 1.5 T (Siemens)
  • 3 T (Siemens, GE, and Philips)
  • 4.7 T (Varian)
  • 7 T (Siemens)
  • 9.4 T (Bruker)
  • Support sequences of single-echo SWI, multi-echo GRE and EPI.

Manual

  • Directory structure

    • Siemens_1p5T: recon codes for Siemens 1.5T sequences, e.g. EPI (fMRI) and SWI
      • qsm_epi15.m
      • qsm_swi15.m
      • qsm_hemo15.m
    • Varian_4p7T: recon codes for Varian 4.7T sequences, e.g. EPI (fMRI), SWI and R2*
      • qsm_epi47.m
      • qsm_swi47.m
      • qsm_r2s47.m
    • Siemens_3T: recon codes for 3T PRISMA sequences, e.g. EPI (fMRI), SWI and R2*
      • qsm_epi_prisma.m
      • qsm_swi_prisma.m
      • qsm_r2s_prisma.m
      • qsm_hemo_prisma.m
    • GE_3T: recon codes for 3T GE sequence, e.g. R2*
      • qsm_spgr_ge.m
    • Philips_3T: recon codes for 3T Philips sequence, currently only R2*
      • qsm_spgr_philips.m
    • Siemens_7T: recon codes for 7T Magnetom sequences, e.g. SWI, ME-GRE and ME-MP2RAGE
      • qsm_swi.m
      • mp2rage.m
      • qsm_7T_bipolar.m
      • qsm_7T_unipolar.m
    • Bruker_9p4T: recon codes for 9.4T Bruker 3D multi-echo sequence
      • qsm_r2s_3d_bruker.m
    • coil_combination: coils combination related codes
      • adaptive_cmb.m: adaptive filter method for single-echo, e.g. EPI, SWI
      • poem.m: POEM (Phase-Offsets Estimation from Multi-echoes) coil combination
    • background_field_removal: background field removal, including RESHARP/SHARP/ESHARP/PDF/LBV
      • sharp.m: SHARP
      • resharp.m: RESHARP method -- can tweak the ker_rad (kernel size) and tik_reg (regularization)
      • projectionontodipolefields.m: PDF
      • extendharmonicfield.m: ESHARP
      • LBV.m: LBV
      • poly2d.m: 2nd order 2D polynomial fit
      • poly3d.m: 2nd order 3D polynomial fit
    • dipole_inversion: dipole inversion with TV regularization
      • tvdi.m: total variation dipole inversion
      • tikhonov_qsm.m: Tikhonov total field inversion
    • Misc: other functions including NIFTI and other small functions

  • Usage

    • Call the main QSM function corresponding to the sequence, e.g. qsm_r2s47 is the function for QSM recon of R2* at 4.7T.

    • Function inputs are

      • Directory of the raw data for 1.5T/4.7T or directories of both magnitude and unfiltered phase DICOMs for Siemens/GE/Philips 3T)
      • User defined directory for QSM output results
      • User specified parameters "options"

    • Examples:

      ```Matlab
options.bkg_rm='resharp';
options.ph_unwrap='laplacian';
qsm_swi47('FID_DIR','OUTPUT_DIR',options);
```

    • For other advanced usage, see help, e.g. help qsm_swi_prisma

  • Common user-changed options:

    • bet_thr: threshold level for BET extracting the brain mask, by default is 0.3-0.5 depending on the sequence, smaller threshold keeps more region of the brain
    • ph_unwrap: phase unwrapping methods, can be 'prelude', 'laplacian' or 'bestpath'
    • bkg_rm: background field removal methods, can be 'sharp', 'pdf','resharp','esharp' or 'lbv', can pick multiple methods to compare, e.g. options.bkg_rm={'resharp','lbv'}
    • smv_rad: radius in mm of SHARP/RESHARP/ESHARP kernel (erosion size, ESHARP recovers some)
    • tik_reg: tikhonov regularization for RESHARP, by default 1e-4, bigger value more regularization
    • tv_reg: total variation regularization, by default 5e-4, bigger value gives smoother result