autoDS-PET

Automated Deauville Score computation from PET/CT images

autoDS-PET extracts reference uptake values from anatomical ROIs (bone marrow, mediastinal blood pool, liver, long bones, brain, focal lesions) on SUV-normalized PET and assigns Deauville Scores by comparing target uptake against standard thresholds.

Pipeline

flowchart LR
    A[Raw DICOM] --> B[Convert to NIfTI]
    B --> C[SUV Normalization]
    C --> D[PET ↔ CT Registration]
    D --> E[CT Segmentation]
    E --> F1[Lumbar VB]
    E --> F2[Aorta MBP]
    E --> F3[Liver]
    E --> F4[Long Bones]
    E --> F5[Brain]
    E --> F6[Focal Lesion]
    F1 & F2 & F3 & F4 & F5 & F6 --> G[Deauville Score]

    style A fill:#e8e8e8,stroke:#999,color:#333
    style B fill:#e0f7f8,stroke:#0dafb5,color:#333
    style C fill:#e0f7f8,stroke:#0dafb5,color:#333
    style D fill:#e0f7f8,stroke:#0dafb5,color:#333
    style E fill:#e0f7f8,stroke:#0dafb5,color:#333
    style F1 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style F2 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style F3 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style F4 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style F5 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style F6 fill:#b2ebf2,stroke:#0dafb5,color:#333
    style G fill:#0dafb5,stroke:#098a8f,color:#fff

Features

• SUV normalization - Converts raw PET (Bq/mL) to SUVbw with automatic decay correction
• Rigid registration - Aligns PET onto the CT grid via SimpleElastix
• Anatomical segmentation - Whole-body CT segmentation with TotalSegmentator
• ROI extraction - Automated refinement of 6 anatomical ROIs with configurable erosion, morphology, and statistics
• Deauville scoring - Assigns DS 1-5 per target by comparing uptake against MBP and liver references
• Batch processing - Process entire patient cohorts with progress tracking and CSV/XLSX export

Installation

# Core install
pip install autods-pet

# With DICOM SEG support (adds highdicom)
pip install "autods-pet[dicom-seg]"

# With development tools (pytest, pytest-cov, hypothesis)
pip install "autods-pet[dev]"

# Everything
pip install "autods-pet[all]"

The DICOM SEG extra installs highdicom, which enables reading .dcm segmentation objects produced by tools like 3D Slicer, OHIF Viewer, dcmqi, Kaapana, and MONAILabel. Without this extra, NIfTI (.nii, .nii.gz) and NRRD (.nrrd) masks are still fully supported.

Quick Start

CLI

# Generate a config template
autods-pet create-config --output my_config.ini

# Full pipeline - single patient
autods-pet run -c my_config.ini -p PATIENT_001

# Full pipeline - batch with Excel output
autods-pet run -c my_config.ini --format xlsx

# Force re-run (ignore cached results)
autods-pet run -c my_config.ini --force

# Individual steps (each supports --force)
autods-pet convert   -c my_config.ini
autods-pet normalize -c my_config.ini
autods-pet register  -c my_config.ini
autods-pet segment   -c my_config.ini
autods-pet extract   -c my_config.ini
autods-pet score     -c my_config.ini -p PATIENT_001,PATIENT_002

Python API

from autods_pet import DeauvillePipeline, load_config

cfg = load_config("my_config.ini")
pipeline = DeauvillePipeline(cfg)

# Single patient
result = pipeline.run("PATIENT_001")
print(result.scores)  # {"BM_DS": 3, "LB_DS": 2, "FL_DS": 4, ...}

# Force re-run (ignore cached results)
pipeline = DeauvillePipeline(cfg, force=True)
result = pipeline.run("PATIENT_001")

basepath/
  PATIENT_001/
    *.dcm                           # DICOM files (flat or nested)
    lesion.nii                      # (optional) Focal lesion mask
    paramedullary.nii               # (optional) Paramedullary mask
    extramedullary.nii              # (optional) Extramedullary mask
  PATIENT_002/
    CT.nii.gz                       # Pre-converted NIfTI also supported
    PET.nii.gz

# Mixed example: NIfTI fallback + DICOM SEG label match.
[focal_lesion]
mask_filename = focal_lesion       ; matches focal_lesion.nii.gz/.nii/.nrrd
segment_label = Focal lesion, FL   ; matches segments labeled "Focal lesion" or "FL"
stats = max, p90

[paramedullary]
segment_label = PM, Paramedullary  ; DICOM SEG only
stats = max, p90

autods-pet list-segments path/to/segmentation.dcm

output_dir/
  PATIENT_001_results/
    images/
      CT.nii.gz                     # Converted CT
      PET.nii.gz                    # Converted PET
      PET_SUV.nii.gz                # SUV body-weight normalized
      PET_SUV_reg.nii.gz            # Registered to CT grid
    segmentations/
      TotSeg_multilabel.nii.gz      # TotalSegmentator multilabel
      vertebral_body.nii.gz         # Vertebral body (requires license)
      refined/                      # Post-processed ROI masks
        aorta_mbp.nii.gz
        grey_matter.nii.gz
        liver.nii.gz
        long_bones.nii.gz
        lumbar_vb.nii.gz
    metadata/
      PET_metadata.json             # DICOM tags
      elastix_transform.txt         # Registration parameters
    DeauvilleScores/
      deauville_scores.csv          # Per-patient DS
    SUV/
      SUV_values.csv                # Per-patient SUV stats
  batch_results_DS.csv              # All patients DS summary
  batch_results_SUV.csv             # All patients SUV summary
  batch_errors.csv                  # Errors (only if any)
  manifest.json                     # Run metadata

Documentation

Full documentation is available at autods-pet.readthedocs.io:

• Getting Started - Installation and first run
• CLI Reference - All commands and options
• Configuration - INI file parameters
• Methodology - Scientific methods description
• API Reference - Full Python API

Notes

Citation

Available soon.

@article{
}

Changelog

See the full history of changes in the CHANGELOG.md file.

Acknowledgments

TotalSegmentator

autoDS-PET relies on TotalSegmentator for whole-body CT segmentation. Some features (e.g., vertebral body segmentation) require a free non-commercial license obtainable from the TotalSegmentator project.

If you use autoDS-PET in your research, please also cite TotalSegmentator:

Wasserthal J, Breit HC, Meyer MT, et al. TotalSegmentator: Robust Segmentation of 104 Anatomic Structures in CT Images. Radiology: Artificial Intelligence. 2023;5(5):e230024.

TotalSegmentator is distributed under the Apache License 2.0.

License

MIT - Sara Peluso

Third-party dependencies are subject to their own licenses. In particular, TotalSegmentator is licensed under the Apache License 2.0.