Quick Start Tutorial¶
This page describes the basic steps to run
ASLPrep on a BIDS dataset.
ASLPrep is containerized and available via
pip, and thus can be run in a variety of ways. Here, we provide the most basic and user friendly workflow.
ASLPrep requires a valid BIDS dataset, like this example of a BIDS dataset on openneuro. Using Chrome, you can download the data via the browser. Note that you might have to create a new folder into which you can download the data. You can also acquire data using using
The BIDS dataset should include the following datatypes in order to run ASLPrep:
sub-01/anat/sub-01_T1w.nii.gz sub-01/anat/sub-01_T1w.json sub-01/perf/sub-01_asl.jnii.gz sub-01/perf/sub-01_asl.json sub-01/perf/sub-01_aslcontext.tsv
There are two ways to install ASLPrep:
- Installation through Docker or Singularity (recommended)
We recommend using Docker or Singularity to run ASLPrep. The docker image can be pulled from the ASLPrep DockerHub using the command line:
docker pull pennlinc/aslprep:latest
To use singularity, a singularity image must be installed directly on the system using the following command:
singularity build aslprep.sif docker://pennlinc/aslprep:latest
This requires installation of Singularity version >= 2.5
Installation is available via
python -m pip install aslprep
This method is not recommended, because it requires external dependencies to be installed.
ASLPrep will require a freesurfer license file (you do not actually need Freesurfer, though), which can be requested here. Move this license to a folder in your
$HOME directory (to find the path to your home directory in the terminal, echo $HOME) and call it license.
In the Docker desktop application, please select Preferences > Resources > Advanced and select at least 12GB for RAM. Restart Docker.
Move the data directory to your
$HOME directory (again, to find this location out, run this in the terminal: echo $HOME). Make sure it is called ds000240.
The following command, which should run in about 8 hours, can be called for a single participant:
docker run -ti -m 12GB --rm -v $HOME/license.txt:/license/license.txt -v $HOME/ds000240:/data:ro -v $HOME/ds000240-results:/out:rw -v $HOME/tmp/ds000240-workdir:/work:rw pennlinc/aslprep /data /out participant --participant-label 01 --fs-license-file /license/license.txt -w /work
Here is a breakdown of this command:
docker run -ti -m 12GB --rm # attach to the container interactively -v $HOME/license.txt:/license/license.txt # mount the freesurfer license directory -v $HOME/ds000240:/data:ro # mount the data directory to the container directory -v $HOME/ds000240-results:/out:rw # mount the output directory to the container directory -v $HOME/tmp/ds000240-workdir:/work # mount working directory pennlinc/aslprep # the container name: aslprep /data # the data directory /out/aslprep # the output directory participant # analysis type: participant --participant-label 01 # select participant 01 --fs-license-file /license/license.txt # setting freesurfer license file -w /work # setting working directory
For additional options, see usage notes > Usage Notes
After a successful run, ASLPrep generates preprocessed ASL data, computed CBF maps, confound quality metrics, preprocessed structural images, as well as one HTML report per subject that provides visual assessment of the preprocessed data. See Outputs of ASLPrep for more information.