autods_pet.deauville#

Deauville Score assignment from ROI statistics.

Implements the standard threshold ladder comparing a target ROI uptake value against the mediastinal blood pool (MBP) and liver references.

autods_pet.deauville.assign_ds(target_value, mbp_value, liver_value, allow_ds1=False, liver_multiplier=2.0)[source]#

Assign a Deauville Score (1-5) from PET uptake values.

Clinical note on DS 1: Per the Deauville criteria, DS 1 represents absent residual uptake (no visible lesion). It is only assigned when target_value is None (or NaN) and allow_ds1 is True. A target with any measurable uptake (even very low, e.g. SUV = 0.001) receives DS 2 or higher, not DS 1. Callers should pass None to indicate the absence of a target lesion.

The DS 4/5 boundary is set at liver_multiplier × liver_value (default 2.0, per the Lugano 2014 consensus - Barrington et al., J Clin Oncol, 2014). Some protocols use 3× liver; pass liver_multiplier=3.0 for those.

Parameters:

  • target_value (float | None) – Uptake statistic for the target ROI (e.g. p95, max). If None/NaN, interpreted as “no uptake” (DS 1 when allow_ds1 is True).

  • mbp_value (float) – Mediastinal blood pool reference (e.g. voxelwise median of aorta).

  • liver_value (float) – Liver reference (e.g. voxelwise median of liver).

  • allow_ds1 (bool (default: False)) – If True, a missing/NaN target_value yields DS 1 (used for focal lesion scoring where absence of a lesion = DS 1). If False, a missing target yields 0 (unassignable).

  • liver_multiplier (float (default: 2.0)) – Multiplier applied to liver_value for the DS 4/5 threshold (default 2.0 per Lugano 2014).

Returns:

Deauville Score: 1-5, or 0 if the score cannot be assigned.

Return type:

int

Raises:

ValueError – If mbp_value or liver_value is <= 0.

Examples

>>> from autods_pet.deauville import assign_ds
>>> assign_ds(target_value=1.5, mbp_value=2.0, liver_value=3.0)
2
>>> assign_ds(target_value=2.5, mbp_value=2.0, liver_value=3.0)
3
>>> assign_ds(target_value=5.0, mbp_value=2.0, liver_value=3.0)
4
>>> assign_ds(target_value=7.0, mbp_value=2.0, liver_value=3.0)
5
>>> assign_ds(target_value=None, mbp_value=2.0, liver_value=3.0, allow_ds1=True)
1