An end-to-end, lesion-centric PSMA PET/CT research system: privacy-preserving DICOM inventory, quantitative preprocessing, 3D segmentation, model uncertainty, lesion quantification, lesion graphs, longitudinal matching, grounded reporting, complete evaluation, and a polished local web application.
Research use only — not clinically validated. Outputs are not diagnoses, prognoses, treatment recommendations, or formal treatment-response classifications.
- Synthetic CT, physiologic PET, positive/negative lesions, longitudinal pairs, classic DICOM, referenced DICOM SEG, and analytically known acceptance fixtures.
- Read-only recursive PET/CT/SEG indexing with de-identified Parquet catalogs, geometry and referenced-series validation, missing-metadata handling, and HTML auditing.
- DICOM-LPS preprocessing in millimetres, SUVbw conversion with decay/midnight handling, physical PET/CT/mask alignment, body cropping, training-only normalization, and QC.
- Leakage-safe patient splits and a shared MONAI SegResNet family for PET-only, CT-only, PET/CT, and PET/CT with locally generated anatomical priors.
- Validation-only thresholding/calibration, ensemble and MC-dropout uncertainty, conservative evidence-logged physiologic suppression, and raw/filtered prediction roles.
- Stable 18-connected lesion instances with physical morphology, CT/SUV measurements, nullable missing values, representative views, and evidence-bearing coarse compartments.
- Lesion graphs, deterministic fingerprints, a 64-dimensional GraphSAGE encoder, same-patient-safe retrieval, and grounded similarity explanations.
- Rigid/affine longitudinal registration, uncertainty-aware lesion matching, split/merge hypotheses, failure handling, timelines, and lesion-track swim lanes.
- Strict versioned findings JSON, local report adapters, sentence-level support references, adversarial verification, and a deterministic fallback.
- Manifest-bound FastAPI routes, React/TypeScript, Niivue, Plotly, server-rendered slice fallback, SQLite support, Docker, and CI.
The interface is populated from generated artifacts—medical measurements are never hardcoded in React. The checked screenshots below use synthetic data only.
| Study workspace | Lesion graph |
|---|---|
 |
 |
| Longitudinal tracks | Grounded report |
|---|---|
 |
 |
Prerequisites are Git, uv, Node.js 22 with Corepack, and GNU Make. Python 3.11 is
provisioned by uv.
make bootstrap
make lint
make typecheck
make test
make smoke
make synthetic-demo
make serveOpen http://localhost:5173; the API is at http://localhost:8000. The generated workspace
is ignored under artifacts/web-demo/. Without Make:
uv sync --extra dev
corepack pnpm --dir frontend install --frozen-lockfile
uv run oncograph synthetic web-demo --output artifacts/web-demo --overwrite
uv run oncograph smokeFor containers, run make docker-build and docker compose up. Detailed native, Windows,
optional anatomy, and Docker instructions are in Installation.
uv run oncograph synthetic create --output artifacts/synthetic --seed 17 --overwrite
uv run oncograph data index
uv run oncograph data validate
uv run oncograph data audit
uv run oncograph data preprocess
uv run oncograph data split
uv run oncograph train --config configs/training/cpu_synthetic_smoke.yaml --restart
uv run oncograph infer --config configs/training/cpu_synthetic_smoke.yaml --partition validation
uv run oncograph lesions extract --config configs/training/cpu_synthetic_smoke.yaml --partition all
uv run oncograph graph build --cases cases --output artifacts/graphs --force
uv run oncograph graph retrieve --graphs artifacts/graphs --query STUDY_KEY --method fingerprint
uv run oncograph synthetic longitudinal --output artifacts/synthetic-longitudinal --overwrite
uv run oncograph longitudinal register --manifest MANIFEST --output artifacts/registration
uv run oncograph longitudinal match --manifest MANIFEST --registration REGISTRATION --output artifacts/matches
uv run oncograph findings build --case-dir CASE --patient-id DEIDENTIFIED_ID --output FINDINGS
uv run oncograph report generate --findings FINDINGS --backend deterministic --output REPORT
uv run oncograph evaluate complete --manifest MANIFEST --output reports/evaluationUse uv run oncograph --help and subgroup help for every option. make gpu-train runs the
frozen, resumable multi-model GPU matrix; read GPU execution before using it.
- Architecture
- Installation and reproducibility
- Dataset instructions and data card
- GPU execution and model card
- Evaluation, anatomy/uncertainty, and limitations
- Lesion extraction, graph retrieval, and longitudinal methods
- Grounded-report safety and web application
- Status, technical decisions, and release checklist
The source dataset is not bundled. The current local research acquisition is a representative Version 2 subset because the complete TCIA release exceeds workstation storage. Source DICOM is immutable and all derived output is written elsewhere. See Dataset instructions for acquisition scope, observed counts, configuration, privacy behavior, and limitations.
The report model receives strict findings JSON only—never pixels, DICOM, hidden measurements, or free-form medical history. Every factual sentence exposes support IDs; a deterministic verifier rejects unsupported or altered content and replaces the entire result with a verified template.
Git excludes medical images, processed volumes, patient artifacts, weights, databases, and
generated reports. make audit-repo checks both tracked and non-ignored candidate files.
Automated tests and committed screenshots use synthetic data only. Performance values are
emitted only by actual declared runs and remain separated by synthetic, development,
validation, and held-out scope.
Citation metadata is in CITATION.cff. The software is available under the MIT License; dataset and third-party model licenses remain separate. See CONTRIBUTING.md and SECURITY.md before sharing changes or reporting a vulnerability.