API

Internal configuration system

A Python module to maintain unique, run-wide QSIPrep settings.

This module implements the memory structures to keep a consistent, singleton config. Settings are passed across processes via filesystem, and a copy of the settings for each run and subject is left under <output_dir>/sub-<participant_id>/log/<run_unique_id>/qsiprep.toml. Settings are stored using ToML. The module has a to_filename() function to allow writing out the settings to hard disk in ToML format, which looks like:

Example file representation of QSIPrep settings.

[environment]
cpu_count = 1
exec_env = "docker"
free_mem = 52.2
overcommit_policy = "heuristic"
overcommit_limit = "50%"
nipype_version = "1.9.1"
templateflow_version = "23.1.0"
version = "1.0.0rc2.dev29+gdee1425.d20250113"

[execution]
bids_dir = "/tmp/src/qsiprep/.circleci/data/forrest_gump"
bids_database_dir = "/tmp/src/qsiprep/.circleci/work/forrest_gump/20250113-154517_1f7046f7-c5b1-4151-84ca-755a96dfbb55/bids_db"
bids_description_hash = "86891931159357fa937a6724ac27013f79ca56859100547ed9793245866312cd"
boilerplate_only = false
sloppy = true
debug = []
layout = "BIDS Layout: ...ep/.circleci/data/forrest_gump | Subjects: 1 | Sessions: 1 | Runs: 0"
log_dir = "/tmp/src/qsiprep/.circleci/out/forrest_gump/logs"
log_level = 15
low_mem = false
notrack = true
output_dir = "/tmp/src/qsiprep/.circleci/out/forrest_gump"
reports_only = false
run_uuid = "20250113-154517_1f7046f7-c5b1-4151-84ca-755a96dfbb55"
participant_label = [ "01",]
processing_list = [ "01:forrestgump",]
skip_anat_based_spatial_normalization = false
templateflow_home = "/home/qsiprep/.cache/templateflow"
work_dir = "/tmp/src/qsiprep/.circleci/work/forrest_gump"
write_graph = true

[workflow]
anat_modality = "T1w"
anatomical_template = "MNI152NLin2009cAsym"
b0_threshold = 100
denoise_method = "none"
distortion_group_merge = "none"
dwi2anat_dof = 6
dwi_biascorrect = "none"
dwidenoise_window = "auto"
force_syn = false
hmc_method = "eddy"
ignore = []
infant = false
dwiref_construction_iters = 2
dwiref_definition = "distortion-group"
dwiref_construction_transform = "BSplineSyN"
subject_anatomical_reference = "first-lex"
no_b0_harmonization = false
output_resolution = 5.0
sdc_method = "topup"
separate_all_dwis = false
use_syn_sdc = false
spaces = "MNI152NLin2009cAsym"

[nipype]
crashfile_format = "txt"
get_linked_libs = false
nprocs = 4
omp_nthreads = 4
plugin = "MultiProc"
remove_unnecessary_outputs = true
resource_monitor = false
stop_on_first_crash = true

[seeds]
master = 20506
ants = 2720
numpy = 32806

[execution.derivatives]

[execution.dataset_links]
raw = "/tmp/src/qsiprep/.circleci/data/forrest_gump"
templateflow = "/home/qsiprep/.cache/templateflow"

[nipype.plugin_args]
maxtasksperchild = 1
raise_insufficient = false

[execution.bids_filters.t1w]
reconstruction = "autobox"

[execution.bids_filters.t2w]
reconstruction = "autobox"

This config file is used to pass the settings across processes, using the load() function.

Configuration sections

class qsiprep.config.environment

Read-only options regarding the platform and environment.

Crawls runtime descriptive settings (e.g., execution environment, nipype and QSIPrep versions, etc.). The environment section is not loaded in from file, only written out when settings are exported. This config section is useful when reporting issues, and these variables are tracked whenever the user does not opt-out using the --notrack argument.

cpu_count = 2

Number of available CPUs.

exec_docker_version = None

Version of Docker Engine.

exec_env = 'posix'

A string representing the execution platform.

free_mem = 6.0

Free memory at start.

mrtrix3_home = None

Absolute path of the MRtrix3 installation selected by --mrtrix-version, or None when the platform declares no MRtrix3 installations.

mrtrix3_version = None

Version of the MRtrix3 installation selected by --mrtrix-version, or None when the platform declares no MRtrix3 installations.

nipype_version = '1.11.0'

Nipype’s current version.

overcommit_limit = '50%'

Linux’s kernel virtual memory overcommit limits.

overcommit_policy = 'heuristic'

Linux’s kernel virtual memory overcommit policy.

templateflow_version = '25.1.2'

The TemplateFlow client version installed.

version = '26.2.0.dev12+gff4f8cdf9'

QSPrep’s version.

class qsiprep.config.execution

Configure run-level settings.

bids_database_dir = None

Path to the directory containing SQLite database indices for the input BIDS dataset.

bids_description_hash = None

Checksum (SHA256) of the dataset_description.json of the BIDS dataset.

bids_dir = None

An existing path to the dataset, which must be BIDS-compliant.

bids_filters = None

A dictionary of BIDS selection filters.

boilerplate_only = False

Only generate a boilerplate.

dataset_links = {}

A dictionary of dataset links to be used to track Sources in sidecars.

debug = []

Debug mode(s).

derivatives = {}

Path(s) to search for pre-computed derivatives.

classmethod init()

Create a new BIDS Layout accessible with layout.

layout = None

A BIDSLayout object, see init().

log_dir = None

The path to a directory that contains execution logs.

log_level = 25

Output verbosity.

low_mem = False

Utilize uncompressed NIfTIs and other tricks to minimize memory allocation.

notrack = False

Do not collect telemetry information for QSIPrep.

output_dir = '/tmp/qsiprep_docs_2marihp7'

Folder where derivatives will be stored.

output_layout = None

Layout of derivatives within output_dir.

participant_label = None

List of participant identifiers that are to be preprocessed.

processing_list = []

List of (subject_id, [session_label, …]) to be preprocessed together.

report_output_level = 'auto'

Directory level at which the HTML reports should be written.

reports_only = False

Only build the reports, based on the reportlets found in a cached working directory.

run_uuid = '20261010-155006_64454284-6aa4-429f-b794-d2387e05f192'

Unique identifier of this particular run.

session_label = None

List of session identifiers that are to be preprocessed.

skip_anat_based_spatial_normalization = False

Should we skip normalizing the anatomical data to a template?

sloppy = False

Run in sloppy mode (meaning, suboptimal parameters that minimize run-time).

templateflow_home = PosixPath('/home/docs/.cache/templateflow')

The root folder of the TemplateFlow client.

work_dir = '/tmp/qsiprep_docs_2marihp7'

Path to a working directory where intermediate results will be available.

write_graph = False

Write out the computational graph corresponding to the planned preprocessing.

class qsiprep.config.workflow

Configure the particular execution graph of this workflow.

anat_biascorrect = 'n4'

n4, auto or none.

Type:

Whether to N4-correct anatomicals

anat_modality = 'T1w'

Modality to use as the anatomical reference. Images of this contrast will be skull stripped and segmented for use in the visual reports. If –infant, T2w is forced.

anatomical_template = 'MNI152NLin2009cAsym'

Anatomical template to use. This field doesn’t include the cohort.

b0_threshold = 100

Any value in the .bval file less than this will be considered a b=0 image.

denoise_config = None

Configuration JSON for dwidenoise2 or svht_denoise (--denoise-config).

denoise_method = 'dwidenoise'

“dwidenoise” (MRtrix3), “dwidenoise2”, “patch2self” (DIPY), “svht” (svht_denoise) or “none”.

Type:

Image-based denoising method

diffprep_config = None

Configuration JSON for running TORTOISE DIFFPREP.

distortion_group_merge = 'concat'

How to combine images across distortion groups (concatenate, average or none).

dwi2anat_dof = 6

6 or 12.

Type:

Degrees of freedom for DWI-to-anatomical coregistration

dwi_biascorrect = 'n4'

n4, auto or none.

Type:

Whether to N4-correct DWIs

dwidenoise_window = 'auto'

Window size in voxels for image-based denoising, integer or “auto”.

dwiref_construction_iters = 2

Number of iterations for dwiref template construction.

dwiref_construction_transform = 'BSplineSyN'

Transformation used for building the dwiref template.

dwiref_definition = 'distortion-group'

distortion-group or subject.

Type:

Which dwiref coregistration targets

eddy_config = None

Configuration for running Eddy.

force = []

Forced processing choices (see --force).

force_nocsf_synthstrip = False

the nonlinear registration to the anatomical template uses a SynthStrip --no-csf mask as its moving-image mask (derived from force by the parser). The saved brain masks and the AC-PC alignment keep the default SynthStrip mask.

Type:

--force no-csf-synthstrip was given

force_sdc_anat_reference = False

the anatomical SDC reference overrides the fieldmap application for every DWI series (derived from force by the parser).

Type:

--force sdc-anat-reference was given

gpu = None

Tasks to run on the GPU (see qsiprep.utils.gpu).

gradient_file = None

Gradient nonlinearity coefficient file or displacement field.

hmc_method = 'eddy'

eddy, shoreline or tortoise.

Type:

Which software corrects head motion

hmc_transform = None

Affine or Rigid. Derived from --shoreline-config; None unless hmc_method is shoreline.

Type:

Transformation SHORELine optimizes during head motion correction

ignore = []

Ignore particular steps for QSIPrep.

infant = False

Configure pipelines specifically for infant brains.

classmethod init()

Put the MRtrix3 installation selected by --mrtrix-version first on PATH.

dwibiascorrect is a Python script that resolves mrcalc, dwiextract, mrmath, mrconvert and N4BiasFieldCorrection through its own PATH lookup, so ordering PATH is the only way to keep a single node on a single MRtrix3 version.

mrtrix_version = 'stable'

“stable” (a released version) or “dev” (the development branch, which is required for complex-valued mrdegibbs).

Type:

Which MRtrix3 installation to use

no_b0_harmonization = False

Skip re-scaling dwi scans to have matching b=0 intensities.

output_resolution = 2.0

Isotropic voxel size for outputs.

sdc_anat_reference = 'none'

Which anatomical-derived image serves as the reference for fieldmap-less susceptibility distortion correction, as a fallback for DWI series no fieldmap reaches: none (default), auto, synb0, t2w or invt1w.

sdc_method = 'auto'

Which tool corrects susceptibility distortion for PEPOLAR data: topup, drbuddi or topup+drbuddi (the parser resolves auto).

separate_all_dwis = False

Process all dwis separately - do not attempt concatenation.

shoreline_config = None

Configuration JSON for SHORELine (--shoreline-config).

shoreline_iters = None

How many iterations to run SHORELine. Derived from --shoreline-config; None unless hmc_method is shoreline.

shoreline_model = None

Signal model SHORELine uses to predict motion-correction targets: 3dshore, tensor or none. Derived from --shoreline-config; None unless hmc_method is shoreline.

subject_anatomical_reference = 'first-lex'

sessionwise, unbiased or first-lex.

Type:

How should the anatomical space be defined

tortoise_gpu_cpu_ratio = None

Volumes the GPU takes per DIFFPREP pass; None leaves TORTOISE’s default.

unringing_method = 'none'

Method for Gibbs-ringing removal. Either “none”, “mrdegibbs”, “rpg” or “svht”.

class qsiprep.config.nipype

Nipype settings.

crashfile_format = 'txt'

The file format for crashfiles, either text (txt) or pickle (pklz).

get_linked_libs = False

Run NiPype’s tool to enlist linked libraries for every interface.

classmethod get_plugin()

Format a dictionary for Nipype consumption.

classmethod init()

Set NiPype configurations.

memory_gb = None

Estimation in GB of the RAM this workflow can allocate at any given time.

nprocs = 2

Number of processes (compute tasks) that can be run in parallel (multiprocessing only).

omp_nthreads = 1

Number of CPUs a single process can access for multithreaded execution.

plugin = 'MultiProc'

NiPype’s execution plugin.

plugin_args = {'maxtasksperchild': 1, 'raise_insufficient': False}

Settings for NiPype’s execution plugin.

remove_unnecessary_outputs = True

Clean up unused outputs after running.

resource_monitor = False

Enable resource monitor.

stop_on_first_crash = False

Whether the workflow should stop or continue after the first error.

Usage

A config file is used to pass settings and collect information as the execution graph is built across processes.

from qsiprep import config
config_file = config.execution.work_dir / '.qsiprep.toml'
config.to_filename(config_file)
# Call build_workflow(config_file, retval) in a subprocess
with Manager() as mgr:
    from .workflow import build_workflow
    retval = mgr.dict()
    p = Process(target=build_workflow, args=(str(config_file), retval))
    p.start()
    p.join()
config.load(config_file)
# Access configs from any code section as:
value = config.section.setting

Logging

class qsiprep.config.loggers

Keep loggers easily accessible (see init()).

cli = <Logger cli (IMPORTANT)>

Command-line interface logging.

default = <RootLogger root (IMPORTANT)>

The root logger.

classmethod init()

Set the log level, initialize all loggers into loggers.

• Add new logger levels (25: IMPORTANT, and 15: VERBOSE).

• Add a new sub-logger (cli).

• Logger configuration.

interface = <Logger nipype.interface (IMPORTANT)>

NiPype’s interface logger.

utils = <Logger nipype.utils (IMPORTANT)>

NiPype’s utils logger.

workflow = <Logger nipype.workflow (IMPORTANT)>

NiPype’s workflow logger.

Other responsibilities

The config is responsible for other conveniency actions.

• Switching Python’s multiprocessing to forkserver mode.

• Set up a filter for warnings as early as possible.

• Automated I/O magic operations. Some conversions need to happen in the store/load processes (e.g., from/to Path <-> str, BIDSLayout, etc.)

qsiprep.config.dumps()

Format config into toml.

qsiprep.config.from_dict(settings, init=True, ignore=None)

Read settings from a flat dictionary.

Parameters:

• settings (dict) – Settings to apply to any configuration.

• init (bool or Container, optional) – Initialize all, none, or a subset of configurations.

• ignore (Container or None, optional) – Collection of keys in settings to ignore.

qsiprep.config.get(flat=False)

Get config as a dict.

qsiprep.config.load(filename, skip=None, init=True)

Load settings from file.

Parameters:

• filename (os.PathLike) – TOML file containing QSIPrep configuration.

• skip (dict or None, optional) – Sets of values to ignore during load, keyed by section name.

• init (bool or Container, optional) – Initialize all, none, or a subset of configurations.

qsiprep.config.to_filename(filename)

Write settings to file.

Library API

• qsiprep.workflows package
  • Subpackages
  • Submodules
• qsiprep package
  • Subpackages
  • Submodules