Installation instructions
Before starting
1. Resources
- 8GB of RAM.
- Disk Space :
- 0.1GB for Atlas and Seeds Folder
- 5.32GB for HALFpipe container (23GB if running with Docker)
- ~500 MB for a working directory for one subject, one task, and one session.
Estimated with a sample size of n=155 and n=261.
On a local machine:
- Few hours (varies by dataset).
On High-Performance Cluster:
- Working directory creation: >1 hour (varies by dataset).
- Full pipeline run: Approximately 2–3 hours.
2. Licensing
Preprocessing requires a FreeSurfer license file which you can get for free when you submit the FreeSurfer Registration form. You will receive the license in the following minutes via email.
3. Downloads
Please ensure these downloaded items are accessible in your environment before proceeding. This means either placed inside your base directory or another directory available to your environment (for example, if using a High-Performing cluster, you need to put the atlas folder on your cluster).
We recommend that you write down the path where these files are located, you will need them later.
4. Data
- Raw (non-skull-stripped) 3D T1-weighted (anatomical) image with .nii or .nii.gz extension. De-faced images will work out of the box.
- Raw 4D functional (task) image with .nii or .nii.gz extension.
- Field map images (if available). Three types are supported if the required metadata is available (e.g., echo spacing, echo time, etc.):
- Siemens field maps, as phase and magnitude image pairs.
- Philips field maps, as one field map image and one or two magnitude images.
- Blip-up/blip-down field maps, as a pair of EPI images with opposite phase encoding directions (mostly AP and PA).
Recommended: Processing using multiple cores or on a high-performance compute cluster (HPC) will be faster and more resource efficient. The manual is built for these conditions although single core processing is possible.
Troubleshooting: If you encounter issues running the pipeline, please refer to the GitHub page here. For further assistance, submit a GitHub issue using the form here (recommended) or contact the support email at [email protected]. You can also join the HALFpipe Mattermost (similar to Slack) using this link.
Installing container platform
Installation of a container platform is only required once.
Select and install an option based on operating system:
- Use Docker from the install link below.
- Install Docker Desktop
| Platform | Installation |
|---|---|
| Docker Desktop | Follow install instructions here: Docker Desktop |
Check to see if the container platform is installed:
- You should now have an application named Docker Desktop on your computer. Look at your applications folder.
- Open it to finish the installation.
- Chose a container platform based on your system:
On a local machine: Use Apptainer on newer systems or otherwise Singularity (via Neurodebian repositories).
On a HPC: Use Singularity or Apptainer (depending on which one is available on your cluster)
- Install the platform
| Platform | Installation |
|---|---|
| Singularity (3.x) | Follow install instructions link |
| Singularity (2.x) | sudo apt install singularity-container |
| Apptainer | Follow install instructions link or sudo apt install -y apptainer |
- Check to see if the container platform is installed:
- Open a terminal session. Only if using a HPC: connect to your server.
- Type
apptainerorsingularityand press enter. - If you see instructions on using Singularity and do not get
command not found, then you can proceed to the next section.
If using Apptainer or Singularity, the command syntax is identical. Replace the tool name accordingly in the commands below.
Working Environment Setup
Here are the steps of setting up your base and working directory where HALFpipe will be run.
Open a terminal session. Only if using a HPC: connect to your server.
Type
pwd(orcdon Windows) and verify that this is the location where you want to begin creation of your environment.- If not, please move to the folder where you want to run the pipeline and save the outputs using the command
cd path/to/your_working_space/
- If not, please move to the folder where you want to run the pipeline and save the outputs using the command
To create a new base directory (output folder), type
mkdir your_enigma_directory.- Verify that the file has been created using the command
ls
- Verify that the file has been created using the command
Then do
cd your_enigma_directoryto enter the folder just created.Then type
mkdir your_working_dirto create the working directory where all the outputs will be stored.
Downloading HALFpipe
Download the container image file:
- Open the terminal in Docker desktop. Refer to this documentation: Explore Docker Desktop
- Use the following command
| Container | Instructions |
|---|---|
| Docker Desktop | docker pull --platform linux/amd64 halfpipe/halfpipe:1.2.3 |
Note: The Docker image for HALFpipe occupies about 23 GB of disk space upon installation.
- Open a terminal session. Only if using a HPC: connect to your server.
- Navigate to your base directory with
cd path/to/your_working_space/your_enigma_directory - Use one of the following commands:
| Platform | Instructions |
|---|---|
| Singularity (3.x) or Apptainer | curl -O https://download.fmri.science/singularity/halfpipe-1.2.3.sif |
Run find $(pwd) -maxdepth 1 to show all files in the current directory with their full path. You should see a file named halfpipe-1.2.3.sif, or similar, listed among the files. |
|
| This file is the container image that includes all software and code needed for processing. Please note down the path to this file, you will need this later. | |
| Singularity (2.x) | curl -O https://download.fmri.science/singularity/halfpipe-1.2.3.simg |
Note: We recommend installing version 1.2.3 of HALFpipe, which includes fMRIPrep LTS. Compatibility testing with the newer fMRIPrep release is ongoing (as of April 2025, already available in the development version).
Additional Information: You will need the paths to both your data and the atlases when running HALFpipe. You will need to specify their locations during the settings configuration. These files do not need to be in the same location as the pipeline image file—just be sure you know where they are stored. To do this, please use the command cd to navigate to your atlas or data folder, then run the command pwd (or cd on Windows).
Working Environment Check
Here we ensure that the working environment is correctly set up before beginning to run HALFpipe.
- Open a terminal session.
Open the terminal in Docker desktop. Refer to this documentation: Explore Docker Desktop
Note that you need to launch HALFpipe via Docker Desktop.
Open a terminal session.
Only if using a HPC: connect to your server.
Navigate to your working directory using this command:
cd path/to/your_working_space/your_enigma_directory/your_working_dirThen use the command
lsEnsure that these items are directly inside or moved into your working directory before proceeding:
- Freesurfer license file (license.txt).
- You can move the license.txt file using the command
mv path/to/license.txt path/to/your_working_space/your_enigma_directory/your_working_dir(on Windows, usemove)
Navigate back to your base directory (i.e.
your_enigma_directory) using this command:cd ..Use the command
ls. Ensure that these items are directly inside your base directory before proceeding:
- Your working directory (i.e.
your_working_dir) - If Singularity or Apptainer: HALFpipe container file (.sif or .simg)
- Ensure that these items are accessible in your environment before proceeding:
- Atlas and Seed files (downloaded in section Before Starting)
- Your unprocessed, resting-state fMRI dataset.