Running HippUnfold with pixi

HippUnfold can be installed and run using pixi on Linux system only. Pixi will manage all Python dependencies and non-python dependencies (c3d, greedy, ANTS) through conda environments.

Note: Pixi installation is not supported on Windows at this time. If you are on Windows, please refer to the Docker instructions instead.

For Users: Installing HippUnfold via Pixi

Steps

Install pixi (if not already installed):

curl -fsSL https://pixi.sh/install.sh | bash

Clone the repository and install dependencies:

git clone https://github.com/khanlab/hippunfold.git
cd hippunfold
pixi install

Development

For development work, use the development environment which includes additional tools like formatters and linters:

pixi install --environment dev

Quality checks can be run using:

pixi run --environment dev quality_check  # Check code formatting
pixi run  --environment dev quality_fix    # Fix code formatting

Usage

Test the installation

Run the following command to verify the installation:

pixi run hippunfold -h

You should see a help message listing all available command-line options.
If this runs successfully, you’re ready to start processing data with HippUnfold!

Running an example

You can try HippUnfold on a sample dataset to make sure everything works as expected.

First, download and extract a single-subject BIDS dataset for this test:

curl -L https://www.dropbox.com/s/mdbmpmmq6fi8sk0/hippunfold_test_data.tar -o hippunfold_test_data.tar
tar -xvf hippunfold_test_data.tar

This will create a ds002168/ folder with a single subject that has both T1w and T2w images:

ds002168/
├── dataset_description.json
├── README.md
└── sub-1425
    └── anat
        ├── sub-1425_T1w.json
        ├── sub-1425_T1w.nii.gz
        ├── sub-1425_T2w.json
        └── sub-1425_T2w.nii.gz

2 directories, 6 files

Option 1: Run the full HippUnfold BIDS pipeline

Running HippUnfold using the T1w modality:

pixi run hippunfold ../ds002168 ../ds002168_hippunfold participant --modality T1w --cores all

This should run the full pipeline and place results in a new ds002168_hippunfold/ folder.

Option 2: Run HippUnfold for a single subject and modality directly

Alternatively, you can use the quick runner script to process just one image:

pixi run hippunfold-quick --input ../ds002168/sub-1425/anat/sub-1425_T1w.nii.gz --output ../ds002168_hippunfold_quick --modality T1w --subject 1425

This will run HippUnfold on the T1w image only and save outputs to the ds002168_hippunfold_quick/ directory.

Cache Directory

When running, HippUnfold automatically downloads and caches necessary resources such as atlases and templates to speed up subsequent runs.

By default, these are stored in the following directory:

~/.cache/hippunfold/

You can override this default cache location by setting the HIPPUNFOLD_CACHE_DIR environment variable:

export HIPPUNFOLD_CACHE_DIR=/path/to/custom/cache

This is useful when working on shared systems, when home directory storage is limited, or if you wish to isolate data per project or user.

Happy unfolding!