pumaz 1.8.14

PUMA (PET Universal Multi-tracer Aligner) aligns multi-tracer PET/CT studies using advanced diffeomorphic imaging.

PUMA 1.0 — Multiplexed PET, Ready for Practice

---

PUMA turns serial PET/CT acquisitions into a single, context-rich view. The pipeline multiplexes tracer studies, aligns anatomy, and produces consistent reporting assets so clinicians and researchers can read more in less time.

Why teams choose PUMA 🧠

• Multiplexed insight – Fuse several tracer volumes into colour-encoded composites without sacrificing quantitative context.
• Trusted accuracy – nnU-Net driven segmentations and diffeomorphic registration keep tumour boundaries and uptake values reliable.
• Workflow friendly – One CLI coordinates preprocessing, registration, blending, and export, keeping radiologists and physicists in sync.
• Platform agnostic – Linux, Windows, and macOS (including Apple Silicon) run the same wheel; PyTorch’s upstream MPS backend covers 3D convolutions with no custom build.

Quick start 🚀

1. Install the package: pip install pumaz
2. Arrange tracer folders as described in 🔗 Workflow essentials.
3. Launch a run:

pumaz -d /path/to/patient -m -ir arms,legs,head

PUMA aligns each tracer, multiplexes RGB composites when requested, and writes results to a timestamped PUMAZ-v<version>-YYYY-MM-DD-HH-MM-SS folder beside your subject data. A run log (pumaz-v.<clock>.log) is saved in the working directory.

Installation 🛠️

• Using uv (recommended)

  curl -Ls https://astral.sh/uv/install.sh | sh  # install uv if needed
  uv venv .venv
  source .venv/bin/activate
  uv pip install pumaz
  

  To add PUMA to an existing uv project, run uv add pumaz.
• Using pip

  pip install pumaz
  

• From source (development work)

  git clone https://github.com/ENHANCE-PET/PUMA.git
  cd PUMA
  uv pip install -e .
  

  Use Python 3.10+ and create a virtual environment when possible.

Usage essentials 🧾

Retrieve the full command reference with:

pumaz --help
pumaz-display --help

Common flags:

• -d /path/to/patient – Root directory that contains one subfolder per tracer.
• -ir arms,legs – Skip specified body regions during registration (none by default).
• -m – Produce multiplexed RGB composites alongside individual tracer outputs.
• -cm Tracer1:R,... – Assign explicit colour channels to each tracer (mutually exclusive with -cs).
• -cs – Interactively choose channel assignments when -m is enabled.
• --display-preset legacy|balanced|green-suppressed|red-focus – Choose the RGB display transfer function for multiplexed PET. legacy keeps the original min-max behavior; adaptive presets write a reproducible window report.
• --display-gallery – Generate balanced, green-suppressed, and red-focus MIP PNGs plus a comparison sheet.
• --review-display-presets – Batch-safe review mode: generate preset galleries and stop before final RGB/DICOM export.
• --export-rotating-mip – Export a spacing-aware upright rotating MIP MP4 for the selected display preset.
• -c2d – Convert aligned NIfTI volumes back to DICOM.

Recommended display workflow:

# Single subject: run registration once and generate a display review gallery.
pumaz -d /path/to/patient -ir none -m --review-display-presets

# Batch: run registration once per subject and generate review galleries.
pumaz --subjects-root /path/to/subjects -ir none -m --review-display-presets

# Review each PUMA-display-gallery.png, then apply the chosen preset
#    to already aligned PET volumes without rerunning registration.
pumaz-display /path/to/PUMAZ-run/aligned_PT --display-preset red-focus --export-rotating-mip

For batch finalization, pass multiple aligned_PT folders to pumaz-display:

pumaz-display /case1/PUMAZ-run/aligned_PT /case2/PUMAZ-run/aligned_PT --display-preset red-focus --export-rotating-mip

Workflow essentials 🧬

Organise every patient or study with one directory per tracer; each tracer must contain PET and CT data as DICOM folders or NIfTI files prefixed by modality:

Parent_Directory/
├── Tracer1/
│   ├── PT_series.nii.gz    # or PET DICOM directory
│   └── CT_series.nii.gz    # or CT DICOM directory
├── Tracer2/
│   ├── PT_series.nii.gz
│   └── CT_series.nii.gz
└── Tracer3/
    ├── PT_series.nii.gz
    └── CT_series.nii.gz

Ensure PET/CT pairs are spatially corresponding within each tracer directory for best results.

Output artefacts 📁

Each run emits a timestamped workspace (PUMAZ-v<version>-<timestamp>) alongside your tracer folders:

Path	Contents
CT/	Resliced CT volumes staged for registration
PT/	Resliced PET volumes indexed by tracer order
aligned_CT/	Final aligned CT volumes
aligned_MASK/	Aligned segmentation masks
aligned_PT/	Aligned PET volumes; includes RGB-composite.nii.gz, grayscale-composite.nii.gz, display-window reports, MIP PNGs, gallery PNGs, and optional rotating MIP MP4 when requested
body_masks/	Body-region masks with ignored labels removed
puma_masks/	24-label PUMA segmentations
transforms/	Affine and warp fields for every tracer

• Logs live alongside the run (pumaz-v.<clock>.log); batch failures append to pumaz-failures-YYYYMMDD-HHMMSS.log.
• Passing --convert-to-dicom creates _dicom folders inside aligned_PT/ with Processed-by-PUMA metadata.

Platform support 💻

PUMA runs on CPU or GPU across major operating systems. PyTorch ≥2.1 ships native Metal (MPS) support, so Apple Silicon users can install the standard wheel—no custom forks or 3D-convolution patches required.

Benchmarks 📊

Performance benchmarks and reference datasets are in preparation. If you want early numbers or to contribute your own results, open an issue.

Support and roadmap 🤝

• File bugs or feature requests on the 🔗 issue tracker.
• Commercial support and integration services are available via 🔗 Zenta Solutions.
• The near-term roadmap includes automated QA scoring, longitudinal dashboards, and cloud-friendly batching.

Citation 📚

If you use PUMA in your research, please cite:

L.K. Shiyam Sundar, S. Gutschmayer, M. Pires, et al.
“Fully Automated Image-Based Multiplexing of Serial PET/CT Imaging for Facilitating Comprehensive Disease Phenotyping.”
Journal of Nuclear Medicine, September 2025. doi:10.2967/jnumed.125.269688

The QIMP “Z” signature ✨

Every QIMP library carries a trailing “z” to signal curiosity for what comes next. It nods to the unknown variable in science and to our commitment to keep stretching medical imaging beyond the expected. When you install pumaz, you join that exploration.

License ⚖️

The open-source edition ships under GPLv3. For commercial licensing or OEM partnerships, contact [e-mail].

Contributors 🙌

Thanks to every contributor—large and small—for shaping PUMA.

W7ebere 📖

Manuel Pires 💻 📖

Sebastian Gutschmayer 💻 📖

This project follows the all-contributors specification. Contributions of any kind are welcome.