Usage Notes

Execution and the BIDS format

The main input to ASLPREP is the path of the dataset that needs processing.

Note

The official BIDS Specification for ASL is currently in its final stages of development. We have created a simple tool for converting ASL data into currently valid BIDS, available at PennLINC. Note that some of the parameters necessary for running ASLPrep cannot be extracted directly from the DICOM header — to obtain these parameters, we recommend consulting the MRI physicist/technician at the scanner. The conversion of ASL into BIDS on Flywheel using fw-heudiconv is described here at fw-heudiconv.

The input dataset is required to be in valid BIDS format, and it must include at least one T1w structural image. We highly recommend that you validate your dataset with the free, online BIDS Validator.

The exact command to run ASLPrep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. For example:

aslprep data/bids_root/ out/ participant -w work/

Command-Line Arguments

ASLPrep: ASL PREProcessing workflows v0.2.7

usage: aslprep [-h] [--version] [--skip_bids_validation]
               [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [--echo-idx ECHO_IDX] [--bids-filter-file FILE]
               [--anat-derivatives PATH] [--nprocs NPROCS]
               [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_GB] [--low-mem]
               [--use-plugin FILE] [--anat-only] [--boilerplate_only]
               [--md-only-boilerplate] [-v]
               [--ignore {fieldmaps,slicetiming,sbref} [{fieldmaps,slicetiming,sbref} ...]]
               [--longitudinal]
               [--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
               [--asl2t1w-init {register,header}] [--asl2t1w-dof {6,9,12}]
               [--force-bbr] [--force-no-bbr] [--m0_scale M0_SCALE]
               [--random-seed RANDOM_SEED] [--dummy-vols DUMMY_VOLS]
               [--smooth_kernel SMOOTH_KERNEL] [--scorescrub] [--basil]
               [--skull-strip-template SKULL_STRIP_TEMPLATE]
               [--skull-strip-fixed-seed]
               [--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
               [--fmap-no-demean] [--use-syn-sdc] [--force-syn]
               [--fs-license-file FILE] [-w WORK_DIR] [--clean-workdir]
               [--resource-monitor] [--reports-only] [--run-uuid RUN_UUID]
               [--write-graph] [--stop-on-first-crash] [--notrack] [--sloppy]
               bids_dir output_dir {participant}

Positional Arguments

bids_dir the root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).
output_dir the output path for the outcomes of preprocessing and visual reports
analysis_level

Possible choices: participant

processing stage to be run, only “participant” in the case of ASLPREP (see BIDS-Apps specification).

Named Arguments

--version show program’s version number and exit

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation
 assume the input dataset is BIDS compliant and skip the validation
--participant-label, --participant_label
 a space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)
--echo-idx select a specific echo to be processed in a multiecho series
--bids-filter-file
 a JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://aslprep.readthedocs.io/en/0.2.7/faq.html#how-do-I-select-only-certain-files-to-be-input-to-ASLPrep
--anat-derivatives
 Reuse the anatomical derivatives from another ASLPrep run or calculated with an alternative processing tool (NOT RECOMMENDED).

Options to handle performance

--nprocs, --nthreads, --n_cpus, --n-cpus
 maximum number of threads across all processes
--omp-nthreads maximum number of threads per-process
--mem, --mem_mb, --mem-mb
 upper bound memory limit for ASLPrep processes
--low-mem attempt to reduce memory usage (will increase disk usage in working directory)
--use-plugin, --nipype-plugin-file
 nipype plugin configuration file
--anat-only run anatomical workflows only
--boilerplate_only
 generate boilerplate only
--md-only-boilerplate
 skip generation of HTML and LaTeX formatted citation with pandoc
-v, --verbose increases log verbosity for each occurence, debug level is -vvv

Workflow configuration

--ignore

Possible choices: fieldmaps, slicetiming, sbref

ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)

--longitudinal treat dataset as longitudinal - may increase runtime
--output-spaces
 Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form <SPACE>[:cohort-<label>][:res-<resolution>][...], where <SPACE> is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. Important to note, the res-* modifier does not define the resolution used for the spatial normalization. To generate no ASL outputs, use this option without specifying any spatial references.
--asl2t1w-init

Possible choices: register, header

Either “register” (the default) to initialize volumes at center or “header” to use the header information when coregistering ASL to T1w images.

--asl2t1w-dof

Possible choices: 6, 9, 12

Degrees of freedom when registering ASL to T1w images. 6 degrees (rotation and translation) are used by default.

--force-bbr Always use boundary-based registration (no goodness-of-fit checks)
--force-no-bbr Do not use boundary-based registration (no goodness-of-fit checks)
--m0_scale relative scale between asl and M0.
--random-seed Initialize the random seed for the workflow
--dummy-vols Number of initial volumes to ignore
--smooth_kernel
 Smoothing kernel for the M0 image(s)
--scorescrub
Sudipto algoritms for denoising CBF
--basil
FSL’s CBF computation with spatial regularization and partial volume correction

Specific options for ANTs registrations

--skull-strip-template
 select a template for skull-stripping with antsBrainExtraction
--skull-strip-fixed-seed
 do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1 and matching –random-seed <int>
--skull-strip-t1w
 

Possible choices: auto, skip, force

determiner for T1-weighted skull stripping (‘force’ ensures skull stripping, ‘skip’ ignores skull stripping, and ‘auto’ applies brain extraction based on the outcome of a heuristic to check whether the brain is already masked).

Specific options for handling fieldmaps

--fmap-bspline fit a B-Spline field using least-squares (experimental)
--fmap-no-demean
 do not remove median (within mask) from fieldmap

Specific options for SyN distortion correction

--use-syn-sdc EXPERIMENTAL: Use fieldmap-free distortion correction
--force-syn EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available

Specific options for FreeSurfer preprocessing

--fs-license-file
 Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

Other options

-w, --work-dir path where intermediate results should be stored
--clean-workdir
 Clears working directory of contents. Use of this flag is notrecommended when running concurrent processes of aslprep.
--resource-monitor
 enable Nipype’s resource monitoring to keep track of memory and CPU usage
--reports-only only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
--run-uuid Specify UUID of previous run, to include error logs in report. No effect without –reports-only.
--write-graph Write workflow graph.
--stop-on-first-crash
 Force stopping on first crash, even if a work directory was specified.
--notrack Opt-out of sending tracking information of this run to the aslprep developers. This information helps to improve aslprep and provides an indicator of real world usage crucial for obtaining funding.
--sloppy Use low-quality tools for speed - TESTING ONLY

The FreeSurfer license

ASLPRep uses FreeSurfer tools, which require a license to run.

To obtain a FreeSurfer license, simply register for free at https://surfer.nmr.mgh.harvard.edu/registration.html.

When using manually-prepared environments or singularity, FreeSurfer will search for a license key file first using the $FS_LICENSE environment variable and then in the default path to the license key file ($FREESURFER_HOME/license.txt). If using the --cleanenv flag and $FS_LICENSE is set, use --fs-license-file $FS_LICENSE to pass the license file location to ASLPrep.

It is possible to run the docker container pointing the image to a local path where a valid license file is stored. For example, if the license is stored in the $HOME/.licenses/freesurfer/license.txt file on the host system:

$ docker run -ti --rm \
    -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out \
    -v $HOME/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    pennlinc/aslprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps

Troubleshooting

Logs and crashfiles are written to the <output dir>/aslprep/sub-<participant_label>/log directory. Information on how to customize and understand these files can be found on the nipype debugging page.

Support and communication.

The documentation of this project is found here: http://aslprep.readthedocs.org/en/latest/.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/pennlinc/aslprep/issues.