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 <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:

Example file representation of aslprep settings.
[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 = "func"
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 aslprep.config.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 = 0.6

Free memory at start.

nipype_version = '1.6.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 = '0.6.3'

The TemplateFlow client version installed.

version = '0.2.7'

aslprep’s version.

class aslprep.config.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[source]

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[source]

An existing file containing a FreeSurfer license.

fs_subjects_dir = None[source]

FreeSurfer’s subjects directory.

classmethod init()[source]

Create a new BIDS Layout accessible with layout.

layout = None

A BIDSLayout object, see init().

log_dir = None[source]

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[source]

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 = '20210307-043149_bd61f71c-a607-43eb-89d1-960768d37a6b'

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/stable/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 aslprep.config.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 aslprep.config.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.

classmethod get_plugin()[source]

Format a dictionary for Nipype consumption.

classmethod init()[source]

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 .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 aslprep.config.loggers[source]

Keep loggers easily accessible (see init()).

cli = <Logger cli (WARNING)>[source]

Command-line interface logging.

default = <RootLogger root (WARNING)>[source]

The root logger.

classmethod init()[source]

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)>[source]

NiPype’s interface logger.

utils = <Logger nipype.utils (INFO)>[source]

NiPype’s utils logger.

workflow = <Logger nipype.workflow (INFO)>[source]

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.)
aslprep.config.from_dict(settings)[source]

Read settings from a flat dictionary.

aslprep.config.load(filename)[source]

Load settings from file.

aslprep.config.get(flat=False)[source]

Get config as a dict.

aslprep.config.dumps()[source]

Format config into toml.

aslprep.config.to_filename(filename)[source]

Write settings to file.

aslprep.config.init_spaces(checkpoint=True)[source]

Initialize the spaces setting.

Workflows

ASLprep base processing workflows

aslprep.workflows.base.init_aslprep_wf()[source]

Build ASLPrep’s pipeline.

This workflow organizes the execution of aslprep, with a sub-workflow for each subject.

If FreeSurfer’s recon-all is to be run, a corresponding folder is created and populated with any needed template subjects under the derivatives folder.

Workflow Graph
(Source code)
aslprep.workflows.base.init_single_subject_wf(subject_id)[source]

Organize the preprocessing pipeline for a single subject.

It collects and reports information about the subject, and prepares sub-workflows to perform anatomical and functional preprocessing. Anatomical preprocessing is performed in a single workflow, regardless of the number of sessions. Functional preprocessing is performed using a separate workflow for each individual ASL series.

Workflow Graph
(Source code)
Parameters:subject_id (str) – Subject label for this single-subject workflow.
Inputs:subjects_dir (str) – FreeSurfer’s $SUBJECTS_DIR.

Pre-processing ASL - ASL signal workflows

Orchestrating the ASL-preprocessing workflow

aslprep.workflows.asl.base.init_asl_preproc_wf(asl_file)[source]

This workflow controls the functional preprocessing stages of aslprep.

Workflow Graph
(Source code)
Parameters:

asl_file – asl series NIfTI file

Inputs:
  • asl_file – asl series NIfTI file
  • t1w_preproc – Bias-corrected structural template image
  • t1w_mask – Mask of the skull-stripped template image
  • t1w_dseg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
  • t1w_tpms – List of tissue probability maps in T1w space
  • template – List of templates to target
  • anat2std_xfm – List of transform files, collated with templates
  • std2anat_xfm – List of inverse transform files, collated with templates
Outputs:
  • asl_t1 – asl series, resampled to T1w space
  • asl_mask_t1 – asl series mask in T1w space
  • asl_std – asl series, resampled to template space
  • asl_mask_std – asl series mask in template space
  • confounds – TSV of confounds
  • cbf_t1 – cbf times series in T1w space
  • meancbf_t1 – mean cbf in T1w space
  • scorecbf_t1 – scorecbf times series in T1w space
  • avgscorecbf_t1 – mean score cbf in T1w space
  • scrub_t1, pv_t1, basil_t1 – scrub, parital volume corrected and basil cbf in T1w space
  • cbf_std – cbf times series in template space
  • meancbf_std – mean cbf in template space
  • scorecbf_std – scorecbf times series in template space
  • avgscorecbf_std – mean score cbf in template space
  • scrub_std, pv_std, basil_std – scrub, parital volume corrected and basil cbf in template space
  • qc_file – quality control meausres

See also

aslprep.workflows.asl.base.init_asl_derivatives_wf(bids_root, metadata, output_dir, spaces, scorescrub=False, basil=False, name='asl_derivatives_wf')[source]

Set up a battery of datasinks to store derivatives in the right location.

Parameters:
  • bids_root (str) – Original BIDS dataset path.
  • metadata (dict) – Metadata dictionary associated to the ASL run.
  • output_dir (str) – Where derivatives should be written out to.
  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs (e.g., MNI152Lin, MNI152NLin6Asym, MNIPediatricAsym), nonstandard references (e.g., T1w or anat, sbref, run, etc.), or a custom template located in the TemplateFlow root directory. Each Reference may also contain a spec, which is a dictionary with template specifications (e.g., a specification of {'resolution': 2} would lead to resampling on a 2mm resolution of the space).
  • name (str) – This workflow’s identifier (default: func_derivatives_wf).

Head-Motion Estimation and Correction (HMC) of ASL images

aslprep.workflows.asl.hmc.init_asl_hmc_wf(mem_gb, omp_nthreads, name='asl_hmc_wf')[source]

Build a workflow to estimate head-motion parameters.

This workflow estimates the motion parameters to perform HMC over the input ASL image.

Workflow Graph
_images/api-4.png

(Source code, png, svg, pdf)

Parameters:
  • mem_gb (float) – Size of ASL file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • name (str) – Name of workflow (default: asl_hmc_wf)
Inputs:
  • asl_file – ASL series NIfTI file
  • raw_ref_image – Reference image to which ASL series is motion corrected
Outputs:
  • xforms – ITKTransform file aligning each volume to ref_image
  • movpar_file – MCFLIRT motion parameters, normalized to SPM format (X, Y, Z, Rx, Ry, Rz)
  • rms_file – Framewise displacement as measured by fsl_motion_outliers

Slice-Timing Correction (STC) of ASL images

aslprep.workflows.asl.stc.init_asl_stc_wf(metadata, name='asl_stc_wf')[source]

Create a workflow for STC.

This workflow performs STC over the input ASL image.

Workflow Graph
_images/api-5.png

(Source code, png, svg, pdf)

Parameters:
  • metadata (dict) – BIDS metadata for ASL file
  • name (str) – Name of workflow (default: asl_stc_wf)
Inputs:
  • asl_file – ASL series NIfTI file
  • skip_vols – Number of non-steady-state volumes detected at beginning of asl_file
Outputs:

stc_file – Slice-timing corrected ASL series NIfTI file

Generate T2* map from multi-echo ASL images

aslprep.workflows.asl.t2s.init_asl_t2s_wf(echo_times, mem_gb, omp_nthreads, name='asl_t2s_wf')[source]

Combine multiple echos of ME-EPI.

This workflow wraps the tedana T2* workflow to optimally combine multiple echos and derive a T2* map. The following steps are performed:

  1. HMC on individual echo files.
  2. Compute the T2* map
  3. Create an optimally combined ME-EPI time series
Parameters:
  • echo_times (list) – list of TEs associated with each echo
  • mem_gb (float) – Size of asl file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • name (str) – Name of workflow (default: asl_t2s_wf)
Inputs:

asl_file – list of individual echo files

Outputs:

asl – the optimally combined time series for all supplied echos

Registration workflows

aslprep.workflows.asl.registration.init_asl_reg_wf(use_bbr, asl2t1w_dof, asl2t1w_init, mem_gb, omp_nthreads, name='asl_reg_wf', sloppy=False, use_compression=True, write_report=True)[source]

Build a workflow to run same-subject, ASL-to-T1w image-registration.

Calculates the registration between a reference ASL image and T1w-space using a boundary-based registration (BBR) cost function.

Workflow Graph
_images/api-6.png

(Source code, png, svg, pdf)

Parameters:
  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
  • asl2t1w_dof (6, 9 or 12) – Degrees-of-freedom for ASL-T1w registration
  • asl2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of ASL and T1 images. If 'register', align volumes by their centers.
  • mem_gb (float) – Size of ASL file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • name (str) – Name of workflow (default: asl_reg_wf)
  • use_compression (bool) – Save registered ASL series as .nii.gz
  • use_fieldwarp (bool) – Include SDC warp in single-shot transform from ASL to T1
  • write_report (bool) – Whether a reportlet should be stored
Inputs:
  • ref_asl_brain – Reference image to which ASL series is aligned If fieldwarp == True, ref_asl_brain should be unwarped
  • t1w_brain – Skull-stripped t1w_preproc
  • t1w_dseg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
Outputs:
  • itk_asl_to_t1 – Affine transform from ref_asl_brain to T1 space (ITK format)
  • itk_t1_to_asl – Affine transform from T1 space to ASL space (ITK format)
  • fallback – Boolean indicating whether BBR was rejected (mri_coreg registration returned)
aslprep.workflows.asl.registration.init_asl_t1_trans_wf(mem_gb, omp_nthreads, scorescrub=False, basil=False, cbft1space=False, multiecho=False, use_fieldwarp=False, use_compression=True, name='asl_t1_trans_wf')[source]

Co-register the reference ASL image to T1w-space.

The workflow uses BBR.

Workflow Graph
_images/api-7.png

(Source code, png, svg, pdf)

Parameters:
  • use_fieldwarp (bool) – Include SDC warp in single-shot transform from ASLto T1
  • multiecho (bool) – If multiecho data was supplied, HMC already performed
  • mem_gb (float) – Size of ASL file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • use_compression (bool) – Save registered ASL series as .nii.gz
  • name (str) – Name of workflow (default: asl_reg_wf)
Inputs:
  • name_source – ASL series NIfTI file Used to recover original information lost during processing
  • ref_asl_brain – Reference image to which ASL series is aligned If fieldwarp == True, ref_asl_brain should be unwarped
  • ref_asl_mask – Skull-stripping mask of reference image
  • t1w_brain – Skull-stripped bias-corrected structural template image
  • t1w_mask – Mask of the skull-stripped template image
  • asl_split – Individual 3D ASL volumes, not motion corrected
  • hmc_xforms – List of affine transforms aligning each volume to ref_image in ITK format
  • itk_asl_to_t1 – Affine transform from ref_asl_brain to T1 space (ITK format)
  • fieldwarp – a DFM in ITK format
Outputs:
  • ASL_t1 – Motion-corrected ASL series in T1 space
  • asl_t1_ref – Reference, contrast-enhanced summary of the motion-corrected ASL series in T1w space
  • asl_mask_t1 – ASL mask in T1 space
aslprep.workflows.asl.registration.init_bbreg_wf(use_bbr, asl2t1w_dof, asl2t1w_init, omp_nthreads, name='bbreg_wf')[source]

Build a workflow to run FreeSurfer’s bbregister.

This workflow uses FreeSurfer’s bbregister to register a ASL image to a T1-weighted structural image.

It is a counterpart to init_fsl_bbr_wf(), which performs the same task using FSL’s FLIRT with a BBR cost function. The use_bbr option permits a high degree of control over registration. If False, standard, affine coregistration will be performed using FreeSurfer’s mri_coreg tool. If True, bbregister will be seeded with the initial transform found by mri_coreg (equivalent to running bbregister --init-coreg). If None, after bbregister is run, the resulting affine transform will be compared to the initial transform found by mri_coreg. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.

Workflow Graph
_images/api-8.png

(Source code, png, svg, pdf)

Parameters:
  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
  • asl2t1w_dof (6, 9 or 12) – Degrees-of-freedom for ASL-T1w registration
  • asl2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of ASL and T1 images. If 'register', align volumes by their centers.
  • name (str, optional) – Workflow name (default: bbreg_wf)
Inputs:
  • in_file – Reference ASL image to be registered
  • fsnative2t1w_xfm – FSL-style affine matrix translating from FreeSurfer T1.mgz to T1w
  • subjects_dir – FreeSurfer SUBJECTS_DIR
  • subject_id – FreeSurfer subject ID (must have folder in SUBJECTS_DIR)
  • t1w_brain – Unused (see init_fsl_bbr_wf())
  • t1w_dseg – Unused (see init_fsl_bbr_wf())
Outputs:
  • itk_asl_to_t1 – Affine transform from ref_asl_brain to T1 space (ITK format)
  • itk_t1_to_asl – Affine transform from T1 space to ASL space (ITK format)
  • out_report – Reportlet for assessing registration quality
  • fallback – Boolean indicating whether BBR was rejected (mri_coreg registration returned)
aslprep.workflows.asl.registration.init_fsl_bbr_wf(use_bbr, asl2t1w_dof, asl2t1w_init, sloppy=False, name='fsl_bbr_wf')[source]

Build a workflow to run FSL’s flirt.

This workflow uses FSL FLIRT to register a ASL image to a T1-weighted structural image, using a boundary-based registration (BBR) cost function. It is a counterpart to init_bbreg_wf(), which performs the same task using FreeSurfer’s bbregister.

The use_bbr option permits a high degree of control over registration. If False, standard, rigid coregistration will be performed by FLIRT. If True, FLIRT-BBR will be seeded with the initial transform found by the rigid coregistration. If None, after FLIRT-BBR is run, the resulting affine transform will be compared to the initial transform found by FLIRT. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.

Workflow Graph
_images/api-9.png

(Source code, png, svg, pdf)

Parameters:
  • use_bbr (bool or None) – Enable/disable boundary-based registration refinement. If None, test BBR result for distortion before accepting.
  • asl2t1w_dof (6, 9 or 12) – Degrees-of-freedom for ASL-T1w registration
  • asl2t1w_init (str, ‘header’ or ‘register’) – If 'header', use header information for initialization of ASL and T1 images. If 'register', align volumes by their centers.
  • name (str, optional) – Workflow name (default: fsl_bbr_wf)
Inputs:
  • in_file – Reference ASL image to be registered
  • t1w_brain – Skull-stripped T1-weighted structural image
  • t1w_dseg – FAST segmentation of t1w_brain
Outputs:
  • itk_asl_to_t1 – Affine transform from ref_asl_brain to T1w space (ITK format)
  • itk_t1_to_asl – Affine transform from T1 space to ASL space (ITK format)
  • out_report – Reportlet for assessing registration quality
  • fallback – Boolean indicating whether BBR was rejected (rigid FLIRT registration returned)

Resampling workflows

aslprep.workflows.asl.resampling.init_asl_surf_wf(mem_gb, surface_spaces, medial_surface_nan, name='asl_surf_wf')[source]

Sample functional images to FreeSurfer surfaces.

For each vertex, the cortical ribbon is sampled at six points (spaced 20% of thickness apart) and averaged. Outputs are in GIFTI format.

Workflow Graph
_images/api-10.png

(Source code, png, svg, pdf)

Parameters:
  • surface_spaces (list) – List of FreeSurfer surface-spaces (either fsaverage{3,4,5,6,} or fsnative) the functional images are to be resampled to. For fsnative, images will be resampled to the individual subject’s native surface.
  • medial_surface_nan (bool) – Replace medial wall values with NaNs on functional GIFTI files
Inputs:
  • source_file – Motion-corrected ASL series in T1 space
  • t1w_preproc – Bias-corrected structural template image
  • subjects_dir – FreeSurfer SUBJECTS_DIR
  • subject_id – FreeSurfer subject ID
  • t1w2fsnative_xfm – LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
Outputs:

surfaces – ASL series, resampled to FreeSurfer surfaces

aslprep.workflows.asl.resampling.init_asl_std_trans_wf(mem_gb, omp_nthreads, spaces, scorescrub=False, basil=False, name='asl_std_trans_wf', use_compression=True, use_fieldwarp=False)[source]

Sample ASL into standard space with a single-step resampling of the original ASL series.

Important

This workflow provides two outputnodes. One output node (with name poutputnode) will be parameterized in a Nipype sense (see Nipype iterables), and a second node (outputnode) will collapse the parameterized outputs into synchronous lists of the output fields listed below.

Workflow Graph
_images/api-11.png

(Source code, png, svg, pdf)

Parameters:
  • mem_gb (float) – Size of ASL file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • spaces (SpatialReferences) – A container for storing, organizing, and parsing spatial normalizations. Composed of Reference objects representing spatial references. Each Reference contains a space, which is a string of either TemplateFlow template IDs.
  • name (str) – Name of workflow (default: asl_std_trans_wf)
  • use_compression (bool) – Save registered ASL series as .nii.gz
  • use_fieldwarp (bool) – Include SDC warp in single-shot transform from ASL to MNI
Inputs:
  • anat2std_xfm – List of anatomical-to-standard space transforms generated during spatial normalization.
  • asl_mask – Skull-stripping mask of reference image
  • asl_split – Individual 3D volumes, not motion corrected
  • fieldwarp – a DFM in ITK format
  • hmc_xforms – List of affine transforms aligning each volume to ref_image in ITK format
  • itk_asl_to_t1 – Affine transform from ref_asl_brain to T1 space (ITK format)
  • name_source – ASL series NIfTI file Used to recover original information lost during processing
  • templates – List of templates that were applied as targets during spatial normalization.
Outputs:
  • asl_std – ASL series, resampled to template space
  • cbf_std, *cbf – cbf series, resampled to template space
  • asl_std_ref – Reference, contrast-enhanced summary of the ASL series, resampled to template space
  • asl_mask_std – ASL series mask in template space
  • template – Template identifiers synchronized correspondingly to previously described outputs.
aslprep.workflows.asl.resampling.init_asl_preproc_trans_wf(mem_gb, omp_nthreads, name='asl_preproc_trans_wf', use_compression=True, use_fieldwarp=False, split_file=False, interpolation='LanczosWindowedSinc')[source]

Resample in native (original) space.

This workflow resamples the input fMRI in its native (original) space in a “single shot” from the original asl series.

Workflow Graph
_images/api-12.png

(Source code, png, svg, pdf)

Parameters:
  • mem_gb (float) – Size of asl file in GB
  • omp_nthreads (int) – Maximum number of threads an individual process may use
  • name (str) – Name of workflow (default: asl_std_trans_wf)
  • use_compression (bool) – Save registered asl series as .nii.gz
  • use_fieldwarp (bool) – Include SDC warp in single-shot transform from asl to MNI
  • split_file (bool) – Whether the input file should be splitted (it is a 4D file) or it is a list of 3D files (default False, do not split)
  • interpolation (str) – Interpolation type to be used by ANTs’ applyTransforms (default 'LanczosWindowedSinc')
Inputs:
  • asl_file – Individual 3D volumes, not motion corrected
  • asl_mask – Skull-stripping mask of reference image
  • name_source – asl series NIfTI file Used to recover original information lost during processing
  • hmc_xforms – List of affine transforms aligning each volume to ref_image in ITK format
  • fieldwarp – a DFM in ITK format
Outputs:
  • asl – asl series, resampled in native space, including all preprocessing
  • asl_mask – asl series mask calculated with the new time-series
  • asl_ref – asl reference image: an average-like 3D image of the time-series
  • asl_ref_brain – Same as asl_ref, but once the brain mask has been applied

Calculate asl confounds

aslprep.workflows.asl.confounds.init_asl_confs_wf(mem_gb, metadata, name='asl_confs_wf')[source]

Build a workflow to generate and write out confounding signals.

This workflow calculates confounds for a asl series, and aggregates them into a TSV file, for use as nuisance regressors in a GLM. The following confounds are calculated, with column headings in parentheses:

  1. DVARS - original and standardized variants (dvars, std_dvars)
  2. Framewise displacement, based on head-motion parameters (framewise_displacement)
  3. Estimated head-motion parameters, in mm and rad (trans_x, trans_y, trans_z, rot_x, rot_y, rot_z)
Workflow Graph
_images/api-13.png

(Source code, png, svg, pdf)

Parameters:
  • mem_gb (float) – Size of asl file in GB - please note that this size should be calculated after resamplings that may extend the FoV
  • metadata (dict) – BIDS metadata for asl file
  • name (str) – Name of workflow (default: asl_confs_wf)
Inputs:
  • asl – asl image, after the prescribed corrections (STC, HMC and SDC) when available.
  • asl_mask – asl series mask
  • movpar_file – SPM-formatted motion parameters file
  • skip_vols – number of non steady state volumes
  • t1w_mask – Mask of the skull-stripped template image
  • t1w_tpms – List of tissue probability maps in T1w space
  • t1_asl_xform – Affine matrix that maps the T1w space into alignment with the native asl space
Outputs:
  • confounds_file – TSV of all aggregated confounds
  • confounds_metadata – Confounds metadata dictionary.