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 🚀
- Install the package:
pip install pumaz - Arrange tracer folders as described in 🔗 Workflow essentials.
- 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 existinguvproject, runuv 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 (noneby 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-mis enabled.--display-preset legacy|balanced|green-suppressed|red-focus– Choose the RGB display transfer function for multiplexed PET.legacykeeps 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 topumaz-failures-YYYYMMDD-HHMMSS.log. - Passing
--convert-to-dicomcreates_dicomfolders insidealigned_PT/withProcessed-by-PUMAmetadata.
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 lalith.shiyam@zenta.solutions.
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.
2 maintainers
Metadata
2 maintainers
Release files for pumaz 1.8.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| pumaz-1.8.14.tar.gz | 94.2 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pumaz-1.8.14-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 179.0 kB
Release files / pumaz-1.8.14.tar.gz
| Download URL | pumaz-1.8.14.tar.gz |
|---|---|
| Size | 94.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29f7934f312ada66bb6e25fcac570e5be36e73b287a1c38fbd7a5fa83c71c149
|
|
BLAKE2b-256 checksum How to use checksums |
27a2100907c74d02bae143d562a3cf1bcf33e16bf6714fa341a45fed6842c9fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / pumaz-1.8.14-py3-none-any.whl
| Download URL | pumaz-1.8.14-py3-none-any.whl |
|---|---|
| Size | 84.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
25e0e61b116241893c1daecbb0eac3775509cfabd3314b6c2922b82f43e28ee0
|
|
BLAKE2b-256 checksum How to use checksums |
19433ef88765362b08f3dadd43a4ef9acd02ed8518cfc7a8dc48700230f8359c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for pumaz 1.8.14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
