Installation

There are two ways to install ASLPrep:

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.10)

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.10 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.10, 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:

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.