Running methods

1. Install

pip install qsm-ci       # (a virtualenv or conda env is recommended)
qsm-ci doctor            # check docker / gh / deps

Runs with Docker by default; add --runner podman, --runner apptainer, or --runner local.

2. See what you can run

qsm-ci list              # every reference method, grouped by stage

Run qsm-ci from a QSM-CI checkout so it can find the algorithms/ folder.

3. Run one method

The flags a method needs depend on its stage. Run it with no inputs and it prints exactly what to provide:

qsm-ci run sharp                                    # prints the inputs this stage needs
qsm-ci run sharp --totalfield tf.nii.gz --mask m.nii.gz --params params.json

Add --truth localfield.nii.gz (and --seg dseg.nii.gz for a χ map) to score it. Uncompressed .nii is fine.

4. Acquisition parameters

Three interchangeable ways, whichever you have:

# a) a params.json          --params params.json
# b) a BIDS MEGRE sidecar   --params sub-1_echo-1_part-phase_MEGRE.json
# c) individual flags       --te 0.004 0.012 0.02 0.028 --field-strength 7 --b0-dir 0 0 1

B0 direction defaults to 0 0 1 and voxel size is read from the NIfTI header, so BFR/dipole methods often need nothing extra.

Multi-echo / BIDS: --phase and --magnitude take either one 4D file or the per-echo 3D files directly; they're stacked to 4D for you (ordered by echo-<n>):

qsm-ci run romeo-fieldmap \
  --phase sub-1_echo-*_part-phase_MEGRE.nii.gz \
  --magnitude sub-1_echo-*_part-mag_MEGRE.nii.gz \
  --mask mask.nii.gz --te 0.004 0.012 0.02 0.028 --field-strength 7

5. Chain stages into a pipeline

Each stage's output is the next one's input, so a background-removal → dipole pipeline is just two runs (mix and match any methods):

qsm-ci run lbv   --totalfield tf.nii.gz --mask m.nii.gz --params p.json -o localfield.nii.gz
qsm-ci run rts   --localfield localfield.nii.gz --mask m.nii.gz --params p.json -o chimap.nii.gz \
                 --truth chimap_groundtruth.nii.gz

Every per-method page has the exact commands for that run: open one from the leaderboard.

6. χ-separation (two source maps)

Susceptibility source separation splits net χ into paramagnetic (χ+, iron) and diamagnetic (χ−, myelin·calcium). These methods read the local field, R2′ and χ_total and write both maps into a directory, so -o is a folder (and --truth a folder of ground-truth maps):

qsm-ci run chi-sepnet \
  --localfield localfield.nii.gz --r2prime r2prime.nii.gz --chimap chimap.nii.gz \
  --magnitude magnitude.nii.gz --mask mask.nii.gz --params params.json \
  -o out/   # writes out/chi-para.nii.gz (χ+) and out/chi-dia.nii.gz (χ−)

7. Use it from a workflow engine

Every method is one qsm-ci run away, so it drops into any pipeline engine. nipype and Pydra have ready-to-import interfaces; for CWL, Snakemake, and Nextflow, qsm-ci interface generates a wrapper from the stage contract. Either way it calls qsm-ci run, so the container runs underneath.

Each tab is a complete phase → χ pipeline (romeo-fieldmap → vsharp → rts): the actual examples/workflow-engines/ files CI runs on the real challenge data. Swap any slug to mix and match methods.

pip install "qsm-ci[nipype]"
python nipype_pipeline.py --phase phase.nii.gz --magnitude mag.nii.gz \
    --mask mask.nii.gz --params params.json --out chimap.nii.gz

pip install "qsm-ci[pydra]"
python pydra_pipeline.py --phase phase.nii.gz --magnitude mag.nii.gz \
    --mask mask.nii.gz --params params.json --out chimap.nii.gz

export QSMCI_ALGORITHMS=/path/to/QSM-CI/algorithms
cwltool --preserve-environment QSMCI_ALGORITHMS pipeline.cwl \
    --phase phase.nii.gz --magnitude mag.nii.gz --mask mask.nii.gz --params params.json

# with phase/magnitude/mask/params.json in the working dir:
snakemake -c1 chimap.nii.gz

export QSMCI_ALGORITHMS=/path/to/QSM-CI/algorithms
nextflow run pipeline.nf --phase phase.nii.gz --magnitude mag.nii.gz \
    --mask mask.nii.gz --params params.json --outdir results

loading…

Regenerate or customize the declarative wrappers with qsm-ci interface <engine> --pipeline romeo-fieldmap,vsharp,rts. CWL and Nextflow run each step in an isolated work dir, so set QSMCI_ALGORITHMS for a bare slug to resolve.

8. Need test data?

Generate a phantom with qsm-forward. It forward-simulates, so it comes with ground truth:

qsm-forward simple bids/     # fields / χ / mask / dseg land under bids/derivatives/qsm-forward/

The leaderboard is scored on the Realistic In Silico Head Phantom (qsm-forward head …) from the QSM Reconstruction Challenge 2.0: Marques et al., Magn Reson Med 2021;86(1):526–542 (doi:10.1002/mrm.28716). Please cite it if you use QSM-CI results.