Developers - API

Internal configuration system

A Python module to maintain unique, run-wide aslprep 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 <aslprep_dir>/sub-<participant_id>/log/<run_unique_id>/aslprep.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:

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

Configuration sections

class environment

Read-only options regarding the platform and environment.

Crawls runtime descriptive settings (e.g., default FreeSurfer license, execution environment, nipype and ASLPrep 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.4

Free memory at start.

nipype_version = '1.8.6'

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 = '23.1.0'

The TemplateFlow client version installed.

version = '0.6.0'

ASLPrep’s version.

class execution

Configure run-level settings.

aslprep_dir = None

Root of ASLPrep BIDS Derivatives dataset.

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.

debug = []

Debug mode(s).

derivatives = []

Path(s) to search for pre-computed derivatives

fs_license_file = None

An existing file containing a FreeSurfer license.

fs_subjects_dir = None

FreeSurfer’s subjects directory.

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 = None

Utilize uncompressed NIfTIs and other tricks to minimize memory allocation.

md_only_boilerplate = False

Do not convert boilerplate from MarkDown to LaTex and HTML.

notrack = False

Do not collect telemetry information for ASLPrep.

output_dir = None

Folder where derivatives will be stored.

output_spaces = None

List of (non)standard spaces designated (with the --output-spaces flag of the command line) as spatial references for outputs.

participant_label = None

List of participant identifiers that are to be preprocessed.

reports_only = False

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

run_uuid = '20231209-202908_9827509a-24ea-45d4-ad85-6aea6a51abb4'

Unique identifier of this particular run.

sloppy = False

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

task_id = None

Select a particular task from all available in the dataset.

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

The root folder of the TemplateFlow client.

work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/aslprep/checkouts/stable/docs/work')

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 workflow

Configure the particular execution graph of this workflow.

anat_only = False

Execute the anatomical preprocessing only.

asl2t1w_dof = None

Degrees of freedom of the ASL-to-T1w registration steps.

asl2t1w_init = 'register'

Whether to use standard coregistration (‘register’) or to initialize coregistration from the ASL image-header (‘header’).

basil = False

Run BASIL, FSL utils to compute CBF with spatial regularization and partial volume correction.

cifti_output = None

Generate HCP Grayordinates, accepts either '91k' (default) or '170k'.

dummy_scans = 0

Number of label-control volume pairs to delete before CBF computation.

fmap_bspline = None

Regularize fieldmaps with a field of B-Spline basis.

fmap_demean = None

Remove the mean from fieldmaps.

force_syn = None

Run fieldmap-less susceptibility-derived distortions estimation.

hires = None

Run FreeSurfer recon-all with the -hires flag.

ignore = None

Ignore particular steps for ASLPrep.

level = 'full'

Level of preprocessing to complete. One of [‘minimal’, ‘resampling’, ‘full’].

longitudinal = False

Run FreeSurfer recon-all with the --longitudinal flag.

m0_scale = 1.0

Relative scale between ASL (delta-M) and M0.

medial_surface_nan = None

Fill medial surface with NaNs when sampling.

project_goodvoxels = False

Exclude voxels with locally high coefficient of variation from sampling.

run_msmsulc = True

Run Multimodal Surface Matching surface registration.

run_reconall = True

Run FreeSurfer’s surface reconstruction.

scorescrub = False

Run SCORE/SCRUB, Sudipto Dolui’s algorithms for denoising CBF.

skull_strip_fixed_seed = False

Fix a seed for skull-stripping.

skull_strip_t1w = 'force'

Skip brain extraction of the T1w image (default is force, meaning that ASLPrep will run brain extraction of the T1w).

skull_strip_template = 'OASIS30ANTs'

Change default brain extraction template.

smooth_kernel = 5.0

Kernel size for smoothing M0.

spaces = None

Keeps the SpatialReferences instance keeping standard and nonstandard spaces.

use_bbr = None

Run boundary-based registration for ASL-to-T1w registration.

use_ge = None

Run GE-specific processing. False means don’t, True means do, None means determine automatically.

use_syn_sdc = None

Run fieldmap-less susceptibility-derived distortions estimation in the absence of any alternatives.

class nipype

Nipype settings.

crashfile_format = 'txt'

The file format for crashfiles, either text or pickle.

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 = None

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.

resource_monitor = False

Enable resource monitor.

stop_on_first_crash = True

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 aslprep import config
config_file = config.execution.work_dir / '.aslprep.toml'
config.to_filename(config_file)
# Call build_workflow(config_file, retval) in a subprocess
with Manager() as mgr:
    from aslprep.cli.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 loggers

Keep loggers easily accessible (see init()).

cli = <Logger cli (WARNING)>

Command-line interface logging.

default = <RootLogger root (WARNING)>

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 (INFO)>

NiPype’s interface logger.

utils = <Logger nipype.utils (INFO)>

NiPype’s utils logger.

workflow = <Logger nipype.workflow (INFO)>

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.)

dumps()

Format config into toml.

from_dict(settings, init=True, ignore=None)

Read settings from a flat dictionary.

Parameters:

• setting (dict) – Settings to apply to any configuration

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

• ignore (Container) – Collection of keys in setting to ignore

get(flat=False)

Get config as a dict.

init_spaces(checkpoint=True)

Initialize the spaces setting.

load(filename, skip=None, init=True)

Load settings from file.

Parameters:

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

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

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

to_filename(filename)

Write settings to file.

aslprep.workflows: Workflows

aslprep.workflows.base	ASLprep base processing workflows.
aslprep.workflows.asl.apply	Workflows to apply changes to ASL data.
aslprep.workflows.asl.base	Preprocessing workflows for ASL data.
aslprep.workflows.asl.cbf	Workflows for calculating CBF.
aslprep.workflows.asl.confounds	Workflows for calculating confounds for ASL data.
aslprep.workflows.asl.fit	Fit workflows for ASLPrep.
aslprep.workflows.asl.hmc	Workflows for estimating and correcting head motion in ASL images.
aslprep.workflows.asl.outputs	Workflows for writing out derivative files.
aslprep.workflows.asl.plotting	Workflows for plotting ASLPrep derivatives.
aslprep.workflows.asl.reference	Workflows for generating reference images.
aslprep.workflows.asl.util	Utility workflows.

aslprep.interfaces: Interfaces

Nipype interfaces for aslprep.

aslprep.interfaces.ants	ANTS interfaces.
aslprep.interfaces.bids	Adapted interfaces from Niworkflows.
aslprep.interfaces.cbf	Interfaces for calculating CBF.
aslprep.interfaces.confounds	Interfaces for calculating and collecting confounds.
aslprep.interfaces.parcellation	Handling functional connectvity.
aslprep.interfaces.plotting	Plotting interfaces.
aslprep.interfaces.reference	Interfaces for building reference images.
aslprep.interfaces.reports	Interfaces to generate reportlets.
aslprep.interfaces.utility	Utility interfaces for ASLPrep.

aslprep.utils: Utilities

Utility functions for aslprep.

aslprep.utils.asl	Functions for working with ASL data.
aslprep.utils.atlas	Functions for working with atlases.
aslprep.utils.bids	Utilities to handle BIDS inputs.
aslprep.utils.cbf	Functions for calculating CBF.
aslprep.utils.confounds	Functions for calculating and collecting confounds.
aslprep.utils.misc	Miscellaneous utilities.
aslprep.utils.plotting	Plotting functions and classes.
aslprep.utils.sentry	Stripped out routines for Sentry.
aslprep.utils.spaces	Utilities for tracking and filtering spaces.

aslprep.data: Data resources

ASLPrep data files

load(*segments) → Path

Load package files relative to aslprep.data.

This package contains the following (top-level) files/directories:

• NOTICE

• aslprep_bids_config.json

• atlases/

• boilerplate.bib

• io_spec.json

• paper_sample.yml

• reports-spec.yml

load.readable(*segments) → Traversable

Provide read access to a resource through a Path-like interface.

This file may or may not exist on the filesystem, and may be efficiently used for read operations, including directory traversal.

This result is not cached or copied to the filesystem in cases where that would be necessary.

load.as_path(*segments) → AbstractContextManager[Path]

Ensure data is available as a Path.

This method generates a context manager that yields a Path when entered.

This result is not cached, and any temporary files that are created are deleted when the context is exited.

load.cached(*segments) → Path

Ensure data is available as a Path.

Any temporary files that are created remain available throughout the duration of the program, and are deleted when Python exits.

Results are cached so that multiple calls do not unpack the same data multiple times, but the cache is sensitive to the specific argument(s) passed.

class Loader(anchor: str | module)

A loader for package files relative to a module

This class wraps importlib.resources to provide a getter function with an interpreter-lifetime scope. For typical packages it simply passes through filesystem paths as Path objects. For zipped distributions, it will unpack the files into a temporary directory that is cleaned up on interpreter exit.

This loader accepts a fully-qualified module name or a module object.

Expected usage:

'''Data package

.. autofunction:: load_data

.. automethod:: load_data.readable

.. automethod:: load_data.as_path

.. automethod:: load_data.cached
'''

from fmriprep.data import Loader

load_data = Loader(__package__)

Loader objects implement the callable() interface and generate a docstring, and are intended to be treated and documented as functions.

For greater flexibility and improved readability over the importlib.resources interface, explicit methods are provided to access resources.

On-filesystem	Lifetime	Method
True	Interpreter	cached()
True	with context	as_path()
False	n/a	readable()

It is also possible to use Loader directly:

from fmriprep.data import Loader

Loader(other_package).readable('data/resource.ext').read_text()

with Loader(other_package).as_path('data') as pkgdata:
    # Call function that requires full Path implementation
    func(pkgdata)

# contrast to

from importlib_resources import files, as_file

files(other_package).joinpath('data/resource.ext').read_text()

with as_file(files(other_package) / 'data') as pkgdata:
    func(pkgdata)

readable(*segments) → Traversable

Provide read access to a resource through a Path-like interface.

This file may or may not exist on the filesystem, and may be efficiently used for read operations, including directory traversal.

This result is not cached or copied to the filesystem in cases where that would be necessary.

as_path(*segments) → AbstractContextManager[Path]

Ensure data is available as a Path.

This method generates a context manager that yields a Path when entered.

This result is not cached, and any temporary files that are created are deleted when the context is exited.

cached(*segments) → Path

Ensure data is available as a Path.

Any temporary files that are created remain available throughout the duration of the program, and are deleted when Python exits.

Results are cached so that multiple calls do not unpack the same data multiple times, but the cache is sensitive to the specific argument(s) passed.

aslprep.data

ASLPrep data files