Quick start

There are two ways to drive QSMxT: interactively in the TUI (recommended) or noninteractively on the command line. Both take you from raw data to QSM maps.

The recommended way: the TUI

Launch the interactive terminal interface and do everything on screen — convert DICOMs, review the classification, configure the pipeline, and run it:

qsmxt tui

The TUI walks you through each step, with menus for every algorithm and sensible defaults pre-filled. It’s the best way to start, especially with a new dataset. See Running interactively.

No data yet? Fetch an example

qsmxt example downloads a real in-vivo subject and writes it out as a BIDS dataset, ready to run:

qsmxt example study/bids
qsmxt run study/bids

That fetches prisma-bridge-run1 (~103 MB): one subject, 5-echo 1 mm 3D gradient-echo, acquired on a Siemens MAGNETOM Prisma Fit. The archive is cached under ~/.cache/qsmxt/examples (override with $QSMXT_EXAMPLE_CACHE), so fetching it again into another directory costs nothing.

If OSF is unreachable from your network, set $QSMXT_EXAMPLE_BASE_URL to a mirror holding the archives as <id>.zip — checksums are still enforced, so a mirror serving the wrong bytes is rejected exactly as a corrupted download would be.

The data comes from a QSM harmonization acquisition in which the same subject was scanned on two Siemens 3T scanners under four protocols, three runs each. List everything available with:

qsmxt example --list

Because every acquisition is the same subject, several can share one dataset — they differ only in their BIDS ses- (scanner), acq- (protocol) and run- entities. Name more than one, or point a later call at an existing dataset to add to it:

qsmxt example --name prisma-bridge-run1 --name cima-bridge-run1 study/bids
qsmxt example --name prisma-bridge-run2 study/bids   # adds a third to the same dataset

Acquisitions already in the dataset are left alone; pass --force to rewrite them. Everything here is also available in the TUI under Input Mode → Example dataset.

Note

MagneticFieldStrength in the sidecars is the accurate field derived from the scanner’s carrier frequency (about 2.89 T), not the nominal 3.0 T. QSM scales ppm by this value, so the accurate one is the correct one. The sidecar records the ImagingFrequency it came from.

The command-line way

Prefer to script it? The same workflow in two commands.

1. Convert DICOMs to BIDS

qsmxt dicom-convert /path/to/dicoms study/bids

QSMxT scans the directory recursively, classifies each series automatically (gradient-echo magnitude and phase, echo count, individual coils, combined/derived reconstructions), and writes a BIDS dataset. Add --dry-run to preview the classification without writing anything. See DICOM → BIDS.

(Already have a BIDS dataset? Skip to step 2.)

2. Run the pipeline

qsmxt run study/bids

QSMxT discovers every phase/magnitude run in the dataset and reconstructs a QSM map for each, writing results to study/bids/derivatives/qsmxt/. With no configuration it uses sensible defaults: ROMEO unwrapping, V-SHARP background removal, and RTS dipole inversion. Pick algorithms inline or process a subset:

qsmxt run study/bids --qsm-algorithm rts --include "sub-01*"

See Running noninteractively.

What you get

Outputs land under derivatives/qsmxt/ as BIDS-compliant NIfTIs — one QSM map per run, plus any supplementary outputs you enabled (SWI, T2*, R2*, RSS-combined magnitude). A references.txt lists citations for the exact methods your data and settings used.

Next steps

• Running interactively — the TUI workflow
• Running noninteractively — every stage and option
• Configuration — save settings to a TOML file
• Input data — what your dataset needs to contain
• Algorithms — choose the right methods