DoseMetrics

[](https://python.org) [](https://badge.fury.io/py/dosemetrics) [](https://github.com/contouraid/dosemetrics/actions/workflows/tests.yml) [](license.md) **A Python library for measuring radiotherapy doses and creating interactive visualizations for radiation therapy treatment planning and analysis.** [Get Started](getting-started/installation.md){ .md-button .md-button--primary } [Try Live Demo](https://huggingface.co/spaces/contouraid/dosemetrics){ .md-button .md-button--secondary } [View on GitHub](https://github.com/contouraid/dosemetrics){ .md-button .md-button--secondary }

---

Overview

DoseMetrics provides comprehensive tools for analyzing radiation dose distributions, calculating dose-volume histograms (DVH), evaluating treatment plan quality, and creating publication-ready visualizations. This library is designed for medical physicists, radiation oncologists, and researchers working with radiotherapy treatment planning data.

Key Features

Dose Analysis : Calculate and analyze 3D dose distributions with support for multiple file formats

DVH Generation : Create dose-volume histograms for organs at risk (OARs) and target volumes

Quality Metrics : Compute conformity indices, homogeneity indices, and other plan quality metrics

Compliance Checking : Evaluate dose constraints and treatment plan compliance against clinical protocols

Interactive Visualizations : Generate interactive plots using Plotly and Streamlit for exploratory analysis

Comparative Analysis : Compare predicted vs. actual dose distributions and analyze plan variations

Geometric Analysis : Compute spatial differences and overlaps between structure sets

Export Capabilities : Save results in various formats (CSV, PDF, PNG) for reporting and publication

Quick Example

from dosemetrics.io import load_dose, load_mask
from dosemetrics.metrics.dvh import compute_dvh
from dosemetrics.utils.plotting import plot_dvh

# Load dose and structure data
dose = load_dose("path/to/dose.nii.gz")
mask = load_mask("path/to/structure.nii.gz")

# Compute DVH
dvh_data = compute_dvh(dose, mask, organ_name="PTV")

# Create interactive visualization
plot_dvh(dvh_data, title="Target Coverage Analysis")

Try It Out

Live Demo Available

Want to try DoseMetrics without installing anything? Check out our interactive demo on Hugging Face Spaces where you can upload your own data and explore the features through a web interface.

Available Features in the Live Demo:

• Instructions: Get started with comprehensive usage guidelines
• Dosimetric Analysis: DVH calculations, dose statistics, and interactive visualizations
• Geometric Comparison: Dice coefficient, Hausdorff distance, and volume overlaps
• Gamma Analysis: Compare dose distributions with configurable criteria
• Compliance Checking: Evaluate plans against clinical constraints

Launch Live Demo

Package Structure

The library is organized into focused modules:

• dosemetrics.metrics: Core dose calculation functions (DVH, scores, comparison metrics)
• dosemetrics.io: File I/O utilities and data structures for dose and structure management
• dosemetrics.utils: Utility functions for compliance checking, plotting, and data processing

Installation

Install via pip:

pip install dosemetrics

For development with documentation tools:

pip install dosemetrics[docs]

See the Installation Guide for more options.

Getting Started

New to DoseMetrics? Start here:

1. Installation - Set up DoseMetrics in your environment
2. Quick Start - Run your first analysis in minutes
3. Using Your Own Data - Learn how to prepare and analyze your data
4. File Formats - Understand supported input formats

Use Cases

DoseMetrics is used for:

• Treatment Plan Evaluation: Assess the quality of radiotherapy treatment plans
• Research Studies: Analyze large cohorts of treatment plans for clinical research
• Quality Assurance: Verify dose calculations and constraint compliance
• Algorithm Development: Develop and test dose prediction and optimization algorithms
• Educational Purposes: Teach radiotherapy physics and treatment planning concepts

Citation

If you use DoseMetrics in your research, please cite:

@software{dosemetrics2024,
  author = {Kamath, Amith},
  title = {DoseMetrics: Tools for Radiotherapy Dose Analysis},
  year = {2024},
  url = {https://github.com/contouraid/dosemetrics}
}

Support

• Documentation
• Issue Tracker
• Source Code
• Live Demo

License

DoseMetrics is licensed under the Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License. See LICENSE for details.