OmniPrep is under active development — early documentation and usage preview.
OmniPrep logo OmniPrep
Home/Getting Started

Getting Started

Install OmniPrep, obtain a FreeSurfer license, and preprocess your first BIDS dataset in minutes.

Requirements

OmniPrep ships as a self-contained container image, so most dependencies are bundled. You will need:

RequirementPurpose
Docker (or Singularity / Apptainer)Container runtime to execute the workflow.
FreeSurfer license fileRequired for anatomical reconstruction. Free — register at surfer.nmr.mgh.harvard.edu.
BIDS-formatted datasetInput data organized according to the BIDS standard.
GPU (optional)Accelerates eligible steps. CPU fallback is supported via --device cpu.

Storage note: multimodal preprocessing generates large intermediate files. Use --remove_temp_files when disk space is limited.

Installation

Pull the latest OmniPrep image. No compilation is required.

Docker

bash
docker pull uxhao/omniprep:latest

Verify the image and print the built-in help:

bash
docker run --rm uxhao/omniprep:latest --help

Singularity / Apptainer

Build a Singularity image from the Docker image, or use a pre-built .simg:

bash
singularity pull omniprep.simg docker://uxhao/omniprep:latest

FreeSurfer license

OmniPrep requires a valid FreeSurfer license file (license.txt) for anatomical reconstruction. It is free to obtain:

  1. Register for a license

    Fill in the registration form at surfer.nmr.mgh.harvard.edu/registration.html.

  2. Download license.txt

    You will receive the license by email. Save it to a known path on your host.

  3. Mount it into the container

    Pass the license path with --fs_license_file (see the quick start below).

Do not redistribute the license. Each user must obtain their own. OmniPrep never bundles a license.

Quick start

The minimal run needs three mounts: the BIDS data, the output directory, and your FreeSurfer license.

Docker

bash — Docker
docker run -it --rm [--gpus all] \
  -v /path/to/bids:/data \
  -v /path/to/output:/out \
  -v /path/to/fs_license.txt:/license.txt \
  uxhao/omniprep:latest /data /out participant \
  --fs_license_file /license.txt \
  --tasks "anat bold dwi"

Singularity / Apptainer

bash — Singularity
singularity run [-nv] \
  --bind /path/to/bids:/data \
  --bind /path/to/output:/out \
  --bind /path/to/fs_license.txt:/license.txt \
  omniprep.simg \
  --fs_license_file /license.txt \
  --tasks "anat bold dwi"

Tip: running with no arguments launches the interactive Streamlit web UI. Running with one argument (--help) prints the full parameter reference.

Run examples

Preprocess all modalities for every subject

bash
omniprep-docker /data /out participant \
  --fs_license_file /opt/freesurfer/license.txt \
  --tasks "anat bold dwi" \
  [options]

BOLD only, reusing existing structural derivatives

bash
omniprep-docker /data /out participant \
  --fs_license_file /opt/freesurfer/license.txt \
  --tasks "bold" \
  --subjects_dir /out/Recon \
  --participant_label "sub-001 sub-002" \
  [options]

When anat is omitted from --tasks, BOLD and DWI workflows still need structural derivatives (T1w, masks, surfaces, segmentations, parcellations). Provide them via --subjects_dir; if unspecified, the default is output_dir/derivatives/omniprep/Recon.

Output structure

All derivatives are written under output_dir/derivatives/omniprep:

text
output_dir/
└── derivatives/
    └── omniprep/
        ├── Recon/        # FreeSurfer structural derivatives
        ├── BOLD/         # denoised BOLD + voxel/ROI metrics
        ├── DWI/          # DTI/CSD metrics, tractography, connectomes
        ├── QC/           # run report, trace, timeline
        └── WorkDir/      # Nextflow work & runtime state

See the Documentation page for the complete parameter reference and more examples.