Installation
There are two ways to install ASLPrep:
using Container Technologies (RECOMMENDED)
within a Manually Prepared Environment (Python 3.8+), also known as bare-metal installation
ASLPrep is not just a Python package; it also depends on a number of other neuroimaging libraries written in other languages. As such, in order to install ASLPrep you also need to install these other dependencies (with the right versions). Container software makes this straightforward, while the bare-metal approach is much more complicated and error-prone.
As such, we strongly recommend installing ASLPrep with Docker or Singularity.
Container Technologies
ASLPrep is ideally run via a Docker or Singularity container. If you are running ASLPrep locally, we suggest Docker. However, for security reasons, many HPCs do not allow Docker containers, but do allow Singularity containers. The improved security for multi-tenant systems comes at the price of some limitations and extra steps necessary for execution.
Docker Installation
Tip
ASLPrep’s image will take up ~30 GB of space on your machine. Please make sure to allocate Docker enough space to house the ASLPrep image before pulling it.
For every new version of ASLPrep that is released, a corresponding Docker image is generated and deployed to DockerHub.
In order to run ASLPrep via Docker, the Docker Engine must be installed.
If you have used ASLPrep via Docker in the past, you might need to pull down a more recent version of the image:
docker pull pennlinc/aslprep:<version>
The image can also be found here: https://registry.hub.docker.com/r/pennlinc/aslprep, and a full list of available tags (versions) can be found here: https://hub.docker.com/r/pennlinc/aslprep/tags.
In most cases, you will want to install the latest released version, which is the tag latest
.
Less frequently, you might want the latest unreleased version
(i.e., the version which corresponds to the main
branch on GitHub),
in which case you should use the tag unstable
.
ASLPrep can be run interacting directly with the Docker Engine via the docker run
command,
or through a lightweight wrapper that was created for convenience.
Singularity Installation
Singularity version >= 2.5: If the version of Singularity installed on your HPC system is modern enough, you can create a Singularity image directly on the system using the following command:
singularity build aslprep-<version>.simg docker://pennlinc/aslprep:<version>
where <version>
should be replaced with the version of ASLPrep that you want to download.
Manually Prepared Environment (Python 3.8+)
Warning
This method is not recommended! Please use container alternatives described above instead.
ASLPrep requires some External Dependencies.
These tools must be installed and their binaries available in the system’s $PATH
.
On a functional Python 3.8 (or above) environment with pip
installed,
ASLPrep can be installed using the command:
pip install git+https://github.com/pennlinc/aslprep.git
Check your installation with the --version
argument:
aslprep --version
External Dependencies
ASLPrep is written using Python 3.8 (or above), is based on nipype, and requires some other neuroimaging software tools that are not handled by Python’s packaging system (PyPi) used to deploy the ASLPrep package:
FSL (version 6.0.2)
ANTs (version 2.2.0 - NeuroDocker build)
AFNI (version Debian-16.2.07)
C3D (version 1.0.0)
FreeSurfer (version 6.0.1)
bids-validator (version 1.1.0)
Connectome Workbench (version Debian-1.3.2)
Modifying ASLPrep
If you would like to make changes to ASLPrep’s source code, but do not wish to directly contribute to the package, we recommend following the instructions in Contributing to ASLPrep.