aslprep.config module
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
<output_dir>/sub-<participant_id>/log/<run_unique_id>/aslprep.toml
.
Settings are stored using ToML.
The module has a to_filename()
function to allow writting out
the settings to hard disk in ToML format, which looks like:
[environment]
cpu_count = 8
exec_env = "posix"
free_mem = 2.3
overcommit_policy = "heuristic"
overcommit_limit = "50%"
nipype_version = "1.5.0"
templateflow_version = "0.6.3"
version = "0.2.2+39.gaf10e8d.dirty"
[execution]
bids_dir = "ds000240/"
bids_description_hash = "d1cefcd38b7b3ab51fa1b78d5cf34a8efb1d07fc3208b8042fc105491bd9b2df"
boilerplate_only = false
debug = false
fs_license_file = "/opt/freesurfer/license.txt"
fs_subjects_dir = "/storage/testxcp/test/freesurfer"
log_dir = "/storage/testxcp/test/aslprep/logs"
log_level = 25
low_mem = false
md_only_boilerplate = false
notrack = false
output_dir = "/tmp"
output_spaces = "asl"
reports_only = false
run_uuid = "20200811-002648_12faeae6-6667-482b-a7a7-1bae99e79aa0"
participant_label = [ "01",]
templateflow_home = "~/.cache/templateflow"
work_dir = "/work/"
write_graph = false
[workflow]
anat_only = false
asl2t1w_dof = 6
asl2t1w_init = "register"
cifti_output = false
fmap_bspline = false
force_syn = false
hires = true
ignore = []
longitudinal = false
medial_surface_nan = false
run_reconall = true
skull_strip_fixed_seed = false
skull_strip_template = "OASIS30ANTs"
skull_strip_t1w = "force"
spaces = "func MNI152NLin2009cAsym"
use_bbr = true
use_syn_sdc = false
dummy_vols = 0
smooth_kernel = 5
[nipype]
crashfile_format = "txt"
get_linked_libs = false
nprocs = 24
omp_nthreads = 8
plugin = "MultiProc"
resource_monitor = false
stop_on_first_crash = false
[seeds]
master = 23622
ants = 9945
[nipype.plugin_args]
maxtasksperchild = 1
raise_insufficient = false
This config file is used to pass the settings across processes,
using the load()
function.
Configuration sections
- class environment[source]
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 = 3.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 = '0.8.1'
The TemplateFlow client version installed.
- version = '0.3.0'
aslprep’s version.
- class execution[source]
Configure run-level settings.
- anat_derivatives = None
A path where anatomical derivatives are found to fast-track sMRIPrep.
- 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 = False
Run in sloppy mode (meaning, suboptimal parameters that minimize run-time).
- echo_idx = None
Select a particular echo for multi-echo EPI datasets.
- fs_license_file = None
An existing file containing a FreeSurfer license.
- fs_subjects_dir = None
FreeSurfer’s subjects directory.
- layout = None
A
BIDSLayout
object, seeinit()
.
- 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 monitor aslprep using Sentry.io.
- 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 = '20230407-180344_2b0e7821-ba41-44bb-88ba-664a6d7f135b'
Unique identifier of this particular run.
- task_id = None
Select a particular task from all available in the dataset.
- templateflow_home = PosixPath('/home/docs/.cache/templateflow')[source]
The root folder of the TemplateFlow client.
- work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/aslprep/checkouts/0.3.0/docs/work')[source]
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[source]
Configure the particular execution graph of this workflow.
- anat_only = False
Execute the anatomical preprocessing only.
- asl2t1w_dof = 6
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 regularilization and partial volume correction
- dummy_vols = 0
pair for label-control volume to be deleted 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 with the
-hires
flag.
- ignore = None
Ignore particular steps for aslprep.
- longitudinal = False
Run with the
-logitudinal
flag.
- m0_scale = 1.0
relative scale between asl and M0.
- random_seed = None
Master random seed to initialize the Pseudorandom Number Generator (PRNG)
- scorescrub = False
run scorescrub, Sudipto’s alogrothims for denoisng 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_syn_sdc = None
Run fieldmap-less susceptibility-derived distortions estimation in the absence of any alternatives.
- class nipype[source]
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.
- 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 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
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.)
- class environment[source]
Bases:
_Config
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 = 3.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 = '0.8.1'
The TemplateFlow client version installed.
- version = '0.3.0'
aslprep’s version.
- class execution[source]
Bases:
_Config
Configure run-level settings.
- anat_derivatives = None
A path where anatomical derivatives are found to fast-track sMRIPrep.
- 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 = False
Run in sloppy mode (meaning, suboptimal parameters that minimize run-time).
- echo_idx = None
Select a particular echo for multi-echo EPI datasets.
- fs_license_file = None
An existing file containing a FreeSurfer license.
- fs_subjects_dir = None
FreeSurfer’s subjects directory.
- layout = None
A
BIDSLayout
object, seeinit()
.
- 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 monitor aslprep using Sentry.io.
- 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 = '20230407-180344_2b0e7821-ba41-44bb-88ba-664a6d7f135b'
Unique identifier of this particular run.
- task_id = None
Select a particular task from all available in the dataset.
- templateflow_home = PosixPath('/home/docs/.cache/templateflow')[source]
The root folder of the TemplateFlow client.
- work_dir = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/aslprep/checkouts/0.3.0/docs/work')[source]
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 loggers[source]
Bases:
object
Keep loggers easily accessible (see
init()
).
- class nipype[source]
Bases:
_Config
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.
- 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.
- class seeds[source]
Bases:
_Config
Initialize the PRNG and track random seed assignments.
- ants = None
Seed used for antsRegistration, antsAI, antsMotionCorr
- master = None
Master seed used to generate all other tracked seeds
- class workflow[source]
Bases:
_Config
Configure the particular execution graph of this workflow.
- anat_only = False
Execute the anatomical preprocessing only.
- asl2t1w_dof = 6
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 regularilization and partial volume correction
- dummy_vols = 0
pair for label-control volume to be deleted 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 with the
-hires
flag.
- ignore = None
Ignore particular steps for aslprep.
- longitudinal = False
Run with the
-logitudinal
flag.
- m0_scale = 1.0
relative scale between asl and M0.
- random_seed = None
Master random seed to initialize the Pseudorandom Number Generator (PRNG)
- scorescrub = False
run scorescrub, Sudipto’s alogrothims for denoisng 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_syn_sdc = None
Run fieldmap-less susceptibility-derived distortions estimation in the absence of any alternatives.