Module separation 

Susceptibility source separation

This module provides algorithms for separating total magnetic susceptibility into paramagnetic (χ+, primarily iron) and diamagnetic (χ-, primarily myelin) components using local field maps and R2’ relaxation data.

Methods

• chi_sep_ilsqr: the SNU χ-separation toolbox’s chi_sep_iLSQR (LSQR, streaking removal and NNLS from a QSM)
• chi_sep_medi: the SNU χ-separation toolbox’s chi_sep_MEDI (edge-masked L1 Gauss-Newton from a QSM, with a CSF term)
• r2star_qsm: closed-form separation from a QSM + R2* (Dimov 2022, no R2’ needed)
• wavesep: wavelet-L1 proximal-gradient separation from a QSM + R2’ (Fang 2023)
• decompose: signal-domain 3-compartment per-voxel fit from a QSM + multi-echo magnitude (Chen 2021)
• hc_chisep: hollow-cylinder χ-separation with signal-derived fiber orientation from a QSM + R2’ + multi-echo magnitude (Wharton & Bowtell model)

Reference

Shin, H., et al. (2021). “χ-separation: Magnetic susceptibility source separation toward iron and myelin mapping in the brain.” NeuroImage, 240:118371.

Re-exports

pub use chi_sep_ilsqr::chi_sep_ilsqr;

pub use chi_sep_ilsqr::chisep_toolbox_ilsqr;

pub use chi_sep_ilsqr::ChiSepIlsqrInputs;

pub use chi_sep_ilsqr::ChiSepIlsqrParams;

pub use chi_sep_ilsqr::NNLS_ITER_MAX;

pub use chi_sep_ilsqr::NNLS_TOL;

pub use chi_sep_medi::chi_sep_medi;

pub use chi_sep_medi::ChiSepMediInputs;

pub use chi_sep_medi::ChiSepMediParams;

pub use chi_sep_medi::CHI_SEP_MEDI_MIN_ITER;

pub use chi_sep_medi::toolbox_default_dr;

pub use chi_sep_medi::TOOLBOX_DR_REFERENCE_TESLA;

pub use chi_sep_medi::TOOLBOX_GYRO_HZ_PER_T;

pub use decompose::decompose;

pub use decompose::DecomposeChiBound;

pub use decompose::DecomposeParams;

pub use decompose::DecomposeStageSolver;

pub use decompose::DecomposeStageSolvers;

pub use hc_chisep::hc_chisep;

pub use hc_chisep::HcChisepParams;

pub use r2star_qsm::r2star_qsm;

pub use r2star_qsm::r2star_qsm_from_magnitude;

pub use r2star_qsm::R2starQsmParams;

pub use wavesep::wavesep;

pub use wavesep::WaveSepParams;

pub use susep_net::SusepNetNorm;

pub use susep_net::SusepNetParams;

pub use chisepnet::ChiSepNetNorm;

pub use chisepnet::ChiSepNetParams;

pub use chisepnet::ChiSepNetR2;

pub use chisepnet::ChiSepNetRoute;

pub use chisepnet::ChiSepNetToolboxModels;

pub use susep_net::susep_net;

pub use chisepnet::chisepnet;

pub use chisepnet::chisepnet_toolbox;

Modules

chi_sep_ilsqr

χ-separation (iLSQR): the SNU χ-separation toolbox’s chi_sep_iLSQR

chi_sep_medi

χ-separation (MEDI): the SNU χ-separation toolbox’s chi_sep_MEDI

chisepnet

χ-sepnet deep-learning χ-separation (onnx feature).

decompose

DECOMPOSE-QSM: signal-domain paramagnetic/diamagnetic source separation.

hc_chisep

HC-ChiSep: hollow-cylinder χ-separation with signal-derived fiber orientation.

r2star_qsm

R2*-QSM: susceptibility source separation from gradient-echo data alone.

susep_net

SUSEP-Net deep-learning χ-separation (onnx feature).

wavesep

WaveSep: wavelet-based susceptibility source separation.

Constants

DR_KIM_2025_COSMOS

χ-separation’s relaxometric constant D_r re-measured against COSMOS, in Hz/ppm.

DR_SHIN_2021

χ-separation’s relaxometric constant D_r, in Hz/ppm, as published by Shin et al. 2021.

Functions

sources_from_magnitudes 🔒

One voxel of a network’s de-normalised source magnitudes, as (χ+, χ−, χ_total) in the crate’s order: χ+ and |χ−| are set to 0 where they are negative, χ− is returned signed (≤ 0), and χ_total is the sum of the two after that.

Type Aliases

ChiSepMaps

The three maps every separation method returns, in the crate’s standard order: (chi_pos, chi_neg, chi_total) in ppm, where chi_pos >= 0, chi_neg <= 0, and chi_total is their sum. Named because the bare triple is otherwise indistinguishable from any other three volumes at a call site.