Installation (Quickstart)

Requirements & data

Inputs should be BIDS with T1w or T2w images. Higher‑res (≤ 0.8 mm) preferred; 1.0 mm works.
Other 3D modalities (e.g., ex‑vivo MRI, histology) may require manual tissue segmentation (UNet models are trained on common MRI only).

Pick one way to run it:

Conda (Linux/macOS) — more flexible, good for HPC environments, developers.
Containers (Docker or Apptainer/Singularity) — easiest, best for Windows, or when you want fully pinned dependencies.

Note: Containers must be given access to input/output directories by mounting them.

Method	OS	Edit code?	Cluster profiles	Notes
Conda	Linux, macOS	✅	✅	Simple, container‑free. Not on Windows.
Docker	Windows, Linux, macOS (Intel)	❌	❌	Mount paths required; portable.
Apptainer (Singularity)	Linux	❌	❌	Common on HPC; portable single `.sif`.

Quickstart (choose one)

Option A — Conda (Linux/macOS)

# create env & install (channels templated)
conda create --name hippunfold-env -c khanlab -c conda-forge -c bioconda hippunfold
conda activate hippunfold-env

# check it works
hippunfold -h

Run a one‑subject example:

curl -L https://www.dropbox.com/s/mdbmpmmq6fi8sk0/hippunfold_test_data.tar -o hippunfold_test_data.tar
tar -xvf hippunfold_test_data.tar
hippunfold ds002168 ds002168_hippunfold participant --modality T1w --cores all

Option B — Containers (Docker or Apptainer)

Containers share nearly identical commands. Replace docker run with apptainer run depending on your environment. Both need directory mounts to access your data.

1. Pull the container

Docker:

docker pull khanlab/hippunfold:dev-v2.0.0

Apptainer:

apptainer pull hippunfold_dev-v2.0.0.sif docker://khanlab/hippunfold:dev-v2.0.0

2. Dry‑run

# Docker
docker run -it --rm \
  -v /directory/to/mount:/data \
  khanlab/hippunfold:dev-v2.0.0 \
  /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -n

# Apptainer
apptainer run -e \
  --bind /directory/to/mount:/data \
  hippunfold_dev-v2.0.0.sif \
  /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -n

3. Run with all cores

# Docker
docker run -it --rm \
  -v /directory/to/mount:/data \
  khanlab/hippunfold:dev-v2.0.0 \
  /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -p --cores all

# Apptainer
apptainer run -e \
  --bind /directory/to/mount:/data \
  hippunfold_dev-v2.0.0.sif \
  /data/ds002168 /data/ds002168_hippunfold participant --modality T1w -p --cores all

Note on mounting

Docker uses -v host_path:container_path
Apptainer uses --bind host_path:container_path

To avoid repeating mounts on every command, you can set:

# Apptainer
env APPTAINER_BINDPATH=/project:/project,/data:/data

# Docker (in docker-compose or wrapper scripts)
# e.g., export DOCKER_OPTS="-v /project:/project -v /data:/data"

This way, input/output paths are automatically accessible.

Models & cache (Note)

As of v1.3.0+, containers no longer ship all models; they’re downloaded on demand.

Default cache:

~/.cache/hippunfold

Override with:

export HIPPUNFOLD_CACHE_DIR=/path/to/cache