Configuration

Anything you can set on the qsmxt run command line can also live in a TOML configuration file. A config file makes runs reproducible and is the cleanest way to drive batch and HPC processing.

Generate a starting config

qsmxt init > pipeline.toml

qsmxt init writes a configuration pre-populated with the default settings, ready to edit. Run qsmxt init --help for options.

Use it

qsmxt run study/bids --config pipeline.toml

Command-line flags take precedence over values in the file, so you can keep a base config and override individual settings per run:

qsmxt run study/bids --config pipeline.toml --qsm-algorithm tgv

What’s in it

The configuration captures the choice of algorithm at each pipeline stage along with that algorithm’s parameters — masking, phase-offset removal, unwrapping, background-field removal, dipole inversion, and referencing. Because each algorithm has its own parameters, the config is the place to tune things like regularisation weights and iteration counts that aren’t exposed as top-level flags.

No default depends on the method: a file runs the methods and settings it says, and choosing a method never changes another setting. Where a chosen method’s reference pipeline uses something else (PDF background removal for MEDI, for example), QSMxT says so in the log, in qsmxt run --dry and in the methods text’s Note, and the TUI offers it (see Recommendations).

Multi-orientation reconstruction lives in its own [multi_orientation] section, off unless group_by names a pattern:

[multi_orientation]
group_by = "*acq-dir*"   # entity name, glob, re:<regex> or runs:<groups> — empty = off
reference = ""           # glob or word picking each group's reference — empty = first by name
algorithm = "cosmos"     # or "sti"
lambda = 0.0

See multi-orientation for what the pattern matches and what will be refused.

The combined magnitude is published unless pipeline.do_magnitude = false (--no-magnitude); it is still made, and kept with the run’s intermediates, for SMWI, segmentation and the inversions that weight by it.

The inhomogeneity correction’s method is masking.inhomogeneity_method, and each method’s settings have their own section: [homogeneity] for makehomogeneous and [n4] for N4:

[masking]
inhomogeneity_correction = true
inhomogeneity_method = "n4"   # or "makehomogeneous" (the default)
n4_geometry = "scanner"       # or "make-nii" (QSMART's axis-aligned header)

[n4]
shrink_factor = 4
max_iterations = [50, 50, 50, 50]   # one entry per fitting level
convergence_threshold = 0.0
mesh = [1, 1, 1]
spline_order = 3
bias_field_fwhm = 0.15
wiener_noise = 0.01
histogram_bins = 200

See inhomogeneity correction for what each does.

The Tukey window on the echoes is pipeline.tukey_window, its taper ratio (--tukey-window; 0, the default, applies none):

[pipeline]
tukey_window = 0.4   # as the χ-separation toolbox uses; 0 for Philips

With two-pass artefact reduction, the reliable mask’s sections and how they combine are masking.two_pass_sections and masking.two_pass_combine ("or" or "and"; left out, it is the main mask’s masking.combine):

[masking]
two_pass = true
two_pass_combine = "and"

Laplacian unwrapping’s settings are in [field_mapping]:

[field_mapping]
unwrapping_algorithm = "laplacian"
laplacian_solver = "mirror"   # or "dct" (the default), "fft"
laplacian_unmasked = true     # the raw phase over the whole volume (default false)

laplacian_unmasked = true is --laplacian-unmasked. PRELUDE’s are in [field_mapping.prelude]:

[field_mapping]
unwrapping_algorithm = "prelude"

[field_mapping.prelude]
labelling = "volume"          # or "auto" (the default), "slices"; --prelude-labelling
num_phase_partitions = 6      # default 8; --prelude-partitions

MEDI’s region growing, unwrapping_algorithm = "medi-region-growing", has no settings. See phase unwrapping for what each does.

A method that converts the field to phase at one echo time has a te setting naming it: "first", "last", "spacing" (TE2 − TE1), "sum" (of the echo times), or a given time in seconds. On the command line the same choice is first, last, spacing, sum, or a time in ms:

[inversion.star]
pad = [8, 8, 20]          # zero-padding per side, voxels (x y z)
te = "sum"                # or "first", "last", "spacing", or { seconds = 0.03 }

[inversion.medi]
te = "spacing"            # or "first", "last", "sum", or { seconds = 0.02 }

[inversion.whqsm]
weight = "flat"           # or "flat-in-mask", "max-normalised", "in-vivo"

[inversion.ndi]
weight_norm = "global-max"  # or "mask-p999"

[bg_removal.harperella]
rim = "whole"             # or "sti" (iHARPERELLA's default)

[bg_removal]
erode_voxels = 0          # erode the mask by N voxels before background removal; --bf-erode-voxels
polish_mask = false       # STI Suite's PolishMask after background removal; --bf-polish-mask

HEIDI after the inversion (HEIDI streaking reduction) is a switch under [inversion.heidi]; LSQR+HEIDI, HEIDI as published, is LSQR with it on:

[inversion]
algorithm = "lsqr"

[inversion.heidi]
enabled = true            # --heidi; with "lsqr", the same as --qsm-algorithm heidi
cone_threshold = 0.1

A file from an earlier QSMxT with algorithm = "heidi" reads as the above.

te = { seconds = 0.03 } under [inversion.star] is --star-te 30, and te = { seconds = 0.02 } under [inversion.medi] is --medi-te 20. A setting the method derives from its others (inversion.tv.rho, inversion.nltv.rho, FANSI’s mu1, alpha0 and mu0, L1-QSM’s mu1, HD-QSM’s mu1_l2, iSMV’s radius, χ-sep iLSQR’s and χ-sep MEDI’s dr_pos and dr_neg) is left out of the file to take the derived value; on the command line it is auto. So is a limit that is off by default (iSMV’s max_iter, DECOMPOSE’s lsqcurvefit.max_function_evaluations).

Recommendations you chose not to follow (see Recommendations) are kept in the file, each with the value of its setting at the time. Only recommended, suggested and discouraged findings are kept; one for a reference-pipeline difference is dropped when the file is read. A change to the setting brings the recommendation back:

[[dismissed_recommendations]]
rule = "fansi.te-spacing"   # the rule's id, as `qsmxt run --dry` lists it
chosen = "first"            # the setting's value it was dismissed for

On the command line this is --dismiss-recommendation fansi.te-spacing=first. A file without dismissed_recommendations has none.

Tip

Rather than writing flags or TOML by hand, configure interactively in the TUI — it shows the equivalent qsmxt run command live. Set things up once, then reuse the command on the CLI and on the cluster; the pipeline_config.toml every run writes to derivatives/qsmxt/ is a config file you can pass back with --config.

Files from earlier versions

A config file QSMxT writes starts with schema_version, the layout it was written in. A file without it is read as follows, and what changed is logged:

• A full config file an earlier QSMxT wrote (qsmxt init, or a run’s pipeline_config.toml) holds every setting, so it would otherwise keep the defaults of the release that wrote it as though they had been chosen. A setting holding one of an earlier release’s defaults takes today’s default instead. Any other value is kept.
• Any other file (written by hand, or a changed-settings file) holds what its author chose, so nothing is reset.
• Settings whose meaning changed are refused when they hold anything but today’s default and their method runs: TGV’s alpha0/alpha1 (now in radians at the echo time inversion.tgv.te picks, the first by default, and the field strength), MEDI’s and TFI’s lambda (now MEDI_L1’s data weight), and field_mapping.phase_offset_sigma (now phase_offset_sigma_mm, in mm). The message says what changed. Give the value in the new terms and add schema_version with the current version at the top, or remove the setting to use the default. When the method does not run, the value is dropped with a note.
• QSMART’s vessel sizes (inversion.qsmart.vasc_sphere_radius and the Frangi scales) were in mm and are now in voxels by default (vessel_size_units). Sizes given without vessel_size_units keep their meaning, in mm, with a warning when QSMART runs; in a full config file, sizes at the earlier defaults take today’s.
• Settings an earlier file does not have (each method’s echo time te, WH-QSM’s weight, NLTV’s rho and tol_newton, RTS’s tau and gamma, PDF’s n_cg, space and n_pad, LBV’s depth, peel, n1, n2, n3 and precision, HARPERELLA’s and iHARPERELLA’s pad and rim, NDI’s weight_norm) take today’s defaults. LBV’s tol is kept as written: an earlier file’s 1e-6 (the old solver’s relative tolerance) now stops the multigrid’s coarsest grid at 1e-6 radians, and the recommendations suggest LBV.m’s 0.01.
• Settings that no longer exist are ignored, with a warning where that changes what a run does (for example bg_removal.msmv_refine: mSMV is now MEDI’s option, inversion.medi.msmv).
• field_mapping.linear_fit.reliability_threshold_percentile never changed the field map and is no longer a setting: it is dropped with a note, whatever it holds, also from a file that has schema_version.
• bg_removal.vsharp.min_radius was also the step between V-SHARP’s radii. A value kept from such a file brings that step with it as bg_removal.vsharp.radius_step, so the radii stay the same.
• TFI’s merit did nothing in earlier files; it is now MERIT, on by default. An earlier value is dropped, with a warning where it turned MERIT off for a TFI run; keep it, with schema_version at the top, to turn MERIT off.

Validate before you run

qsmxt validate study/bids

validate checks that your dataset has the phase/magnitude pairs and sidecar metadata the pipeline needs, so problems surface before a long run starts.