Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]¶

Six new dose quality metrics drawn from the radiotherapy dose-prediction literature:

compute_dvh_score(dose_reference, dose_evaluated, structure) — Average absolute difference in D1, D95, and D99 between two dose distributions. Captures clinical discrepancies at near-maximum, coverage, and near-minimum DVH points. (metrics/dvh.py)
compute_dvh_auc(dose, structure, num_bins, normalize, dose_range) — Area under the DVH curve via trapezoidal integration. Single-distribution metric; higher value = more volume at higher dose. (metrics/dvh.py)
compute_rtog_conformity_index(dose, target, prescription_dose) — RTOG CI = V_Rx / V_target. The ICRU/RTOG 90-05 standard conformity definition, distinct from the existing ICRU CI (V_target_rx / V_rx). (metrics/conformity.py)
compute_prescription_mae(dose, target, prescription_dose) — Mean absolute error between actual dose and prescription dose within the target; directly measures under/overdosing. (metrics/conformity.py)
compute_variance_of_laplacian(dose, structure=None) — Variance of the 2D Laplacian applied to the dose volume, measuring dose-gradient sharpness. (metrics/dose_comparison.py)
compute_normalized_mae(dose_reference, dose_evaluated, structure, normalization_value, dose_threshold_gy) — MAE normalized by a reference value with optional high-dose threshold masking. (metrics/dose_comparison.py)

Two new visualization functions in utils/plot.py:

plot_dvh_score_breakdown — DVH comparison overlaid with D1/D95/D99 markers and gap annotations, with the DVH Score in the title.
plot_dvh_auc — DVH with filled area-under-curve and AUC value annotated.

Documentation:

Expanded docs/user-guide/quality-metrics.md from a placeholder into a full guide covering all conformity and homogeneity indices with formulas, named-after context (Paddick, van't Riet, RTOG, ICRU), interpretation guidance, and code examples.
Updated docs/api/metrics.md to include the dose_comparison, gamma, and advanced_dvh modules.
Updated docs/architecture/metrics-architecture.md with correct function signatures and the two new modules.

Dose Class: New Dose class for managing 3D dose distributions separately from structures
StructureSet Class: New StructureSet aggregation object for managing collections of radiotherapy structures
Structure Type Classification: Proper OAR/Target/Avoidance distinction using enums
Bulk Operations: Calculate statistics and DVH for all structures simultaneously via StructureSet
Enhanced I/O Functions: New functions for loading data directly into StructureSet objects
get_dose_and_structures_as_structure_set(): Load from folder to StructureSet
read_dose_and_mask_files_as_structure_set(): Convert file lists to StructureSet
create_structure_set_from_existing_data(): Upgrade existing data to StructureSet
Factory Functions: Convenient creation methods (create_structure_set_from_folder(), create_structure_set_from_masks())
Comprehensive Test Suite: 25+ tests for Dose class, 30+ tests for StructureSet
Documentation: New tutorials for NIfTI I/O, DICOM I/O, and StructureSet usage

BREAKING: Separated dose data from Structure class - structures no longer directly contain dose data
BREAKING: StructureSet objects now manage dose data for all structures
BREAKING: Removed set_dose_data() and related methods from Structure class
Improved multi-dose file handling - can now work with multiple RT-DOSE files per patient
Enhanced spatial compatibility checking between dose grids and structures
Updated all I/O functions to support the new architecture

BREAKING: Restructured repository to use src/ layout
BREAKING: Reorganized modules into logical packages:
dosemetrics.metrics: Core dose calculation functions (DVH, scores, etc.)
dosemetrics.io: File I/O utilities for reading dose and mask data
dosemetrics.utils: Utility functions for compliance, plotting, etc.
BREAKING: Moved Streamlit app code to separate dosemetrics_app package
BREAKING: App-specific code (variations_tab.py) moved to dosemetrics_app.tabs
Updated package configuration to exclude app code from PyPI distribution
Added CLI entry point via dosemetrics command