andreasneil13/Transparent-Deauville-score

# Automated Deauville Scoring Pipeline (FDG PET/CT) An automated pipeline for **Deauville treatment-response scoring** of lymphoma from paired longitudinal FDG PET/CT studies. Given a baseline and one or more follow-up PET/CT exams within a treatment line, the pipeline produces a **Deauville score (1–5)** for each consecutive exam pair, with a per-lesion breakdown, SUV reference values, and review flags. ## Deauville 5-point scale | Score | Interpretation | |-------|----------------| | 1 | No residual uptake | | 2 | Uptake ≤ mediastinal blood pool | | 3 | Uptake > mediastinum but ≤ 1.4× liver SUVpeak | | 4 | Uptake > 1.4× and ≤ 2× liver SUVpeak | | 5 | Uptake > 2× liver SUVpeak, or a new lesion | ## Pipeline overview The pipeline runs nine stages on the critical path. Segmentation/alignment and lesion detection run as two independent branches that merge before matching and scoring. Inputs (DICOM PET/CT) | BRANCH A (segmentation -> alignment) BRANCH B (lesion detection) ----------------------------------- -------------------------- [1] CT segmentation (TotalSegmentator) [5] lesion detection [2] derived masks (deep learning, nnU-Net) |- [3] liver VOI |- [4] mediastinal (blood-pool) VOI |- [6] alignment stage 1 (organ-wise ICP) | [7] alignment stage 2 (dense displacement field) | +---------------- MERGE -----------------+ | [8] lesion matching (follow-up -> baseline) | [9] Deauville scoring (per-lesion + pair aggregation) | Deauville result (JSON + CSV) | Stage | Description | |-------|-------------| | 1. Segmentation | Multi-organ CT masks via TotalSegmentator | | 2. Derived masks | Region partitions and union masks | | 3. Liver VOI | Liver SUVpeak reference (1 mL sphere) | | 4. Mediastinal VOI | Thoracic-aorta blood-pool reference | | 5. Lesion detection | Whole-body PET/CT lesion segmentation | | 6. Alignment stage 1 | Organ-wise ICP (rigid/affine) | | 7. Alignment stage 2 | Dense Laplace/Jacobi displacement field | | 8. Lesion matching | Follow-up to baseline lesion correspondence | | 9. Deauville scoring | Per-lesion score + pair aggregation | ## Installation Requires Python 3.10+. git clone cd deauville-pipeline-public python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ### External dependencies (not bundled) | Dependency | Purpose | Notes | |------------|---------|-------| | [TotalSegmentator](https://github.com/wasserth/TotalSegmentator) ≥ 2.4 | CT multi-organ segmentation | installed via `requirements.txt` | | Deep-learning lesion model (nnU-Net, autoPET-3) | Stage 5 lesion detection | **external** — clone the model repo and download weights separately | | PyTorch + CUDA | GPU acceleration | optional; CPU fallback available | The lesion-detection model and its weights are **not** distributed here. Obtain them from their original source and place the weights where the configuration expects them (a local `models/` directory, which is git-ignored). ## Usage / └── / └── / ├── Baseline/ │ ├── CT/ # DICOM series │ └── PET/ ├── FU1/ │ ├── CT/ │ └── PET/ └── FU2/ ... Run the full pipeline: python -m src.cli.run_pipeline -i -o Common options: # GPU acceleration for the dense-field alignment stage python -m src.cli.run_pipeline -i -o --device cuda # Preview the plan without running python -m src.cli.run_pipeline -i -o --dry-run # Restrict to specific patients python -m src.cli.run_pipeline -i -o --patients ### Output For each exam pair, the pipeline writes: - `/deauville//deauville_result.json` — full pair result (both scores, references, flags, warnings) - `/deauville//lesion_deauville.csv` — per-lesion table - `/deauville_summary.{json,csv}` — one row per pair The result reports two scores: `final_deauville_score` (primary, includes the new-lesion rule) and `uptake_based_deauville_score` (uptake only, for audit). ## Repository layout src/ ├── cli/ # command-line entry points (run_pipeline.py) ├── data/ # dataset discovery, manifests, reports ├── io/ # DICOM / image loading ├── qc/ # input quality control ├── segmentation/ # TotalSegmentator integration, derived masks ├── voi/ # liver and mediastinal reference VOIs ├── quantification/ # SUV / SUVpeak computation ├── lesion_detection/ # deep-learning lesion segmentation ├── alignment/ # two-stage registration (ICP + dense field) ├── alignment_qa/ # alignment quality metrics ├── matching/ # follow-up to baseline lesion matching ├── scoring/ # Deauville decision logic and pair aggregation ├── interpretation/ # optional pair-level response interpretation ├── exclusion/ # physiological-uptake exclusion rules ├── hotspots/ # uptake hotspot extraction ├── diagnostics/ # visualisation and audit helpers └── models/ # dataclasses / domain models ## License Released under the [MIT License](LICENSE). ## Disclaimer This software is provided for research and educational purposes only. It has not been clinically validated and is not approved for any diagnostic or treatment decision. Use at your own risk.