Getting Started

Prerequisites

• Python >= 3.10

• TotalSegmentator for CT segmentation (pip install TotalSegmentator)

• Elastix / SimpleElastix for PET-to-CT registration (pip install SimpleITK-SimpleElastix – replaces the plain SimpleITK package)

Installation

pip install autods-pet

Optional extras

Extra	Command	What it adds
dicom-seg	pip install "autods-pet[dicom-seg]"	highdicom – read DICOM SEG (.dcm) segmentation masks produced by 3D Slicer, OHIF, dcmqi, Kaapana, MONAILabel, etc.
dev	pip install "autods-pet[dev]"	pytest, pytest-cov, hypothesis (for running tests with coverage)
docs	pip install "autods-pet[docs]"	Sphinx, pydata-sphinx-theme (for building documentation)

Install everything at once:

pip install "autods-pet[all]"

Note

Without the dicom-seg extra, NIfTI (.nii, .nii.gz) and NRRD (.nrrd) segmentation masks are fully supported. The extra is only needed when working with DICOM SEG files.

Quick Start

1. Prepare your data following the expected layout:

   basepath/
     PATIENT_001/
       CT.nii.gz
       PET.nii.gz
     PATIENT_002/
       ...
   

2. Create a configuration file using the built-in template generator, or copy one of the example configs from the configs/ folder (standard.ini, quick.ini, full.ini, advanced.ini, brain.ini):

   # Generate a template config (defaults to "standard" profile)
   autods-pet create-config -o my_config.ini
   
   # Or choose a specific profile
   autods-pet create-config -p quick -o my_config.ini
   

   Then edit the [paths] section:

   [paths]
   basepath = /path/to/your/nifti/data
   patient_list = /path/to/patients.txt
   output_dir = /path/to/output
   

3. Run the full pipeline:

   # Single patient
   autods-pet run -c my_config.ini -p PATIENT_001
   
   # Comma-separated patients
   autods-pet run -c my_config.ini -p PATIENT_001,PATIENT_002
   
   # Patients from a text file
   autods-pet run -c my_config.ini -p patients.txt
   
   # Entire cohort (from config patient_list or auto-discover)
   autods-pet run -c my_config.ini
   
   # Re-run even if outputs already exist
   autods-pet run -c my_config.ini --force
   

   By default, completed stages are skipped. Use --force to re-run all stages regardless of existing outputs.

4. Output structure: Results are written to output_dir/{patient_id}_results/ with the following subfolders:

   output_dir/
     PATIENT_001_results/
       images/
       segmentations/
       metadata/
       DeauvilleScores/
         deauville_scores.csv
       SUV/
         SUV_values.csv
   

   Source data in basepath/{patient_id}/ is never modified.

   For batch runs, two summary CSVs are written to output_dir/:

   • batch_results_DS.csv – Deauville Score columns

   • batch_results_SUV.csv – SUV statistics

   If any patients fail, errors are collected in batch_errors.csv (only created when errors occur).

Python API Quick Start

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)

# Re-run even if outputs already exist
pipeline = DeauvillePipeline(cfg, force=True)
result = pipeline.run("PATIENT_001")

# Batch
results = pipeline.run_batch(["PATIENT_001", "PATIENT_002"])
df = DeauvillePipeline.to_dataframe(results)