| Name | dosemetrics JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Measuring radiotherapy doses - plotting visualizations |
| upload_time | 2025-08-08 08:25:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License
This work is licensed under the Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License.
Copyright (c) 2025 Amith Kamath
You are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material
Under the following terms:
- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
- NonCommercial — You may not use the material for commercial purposes without explicit written permission from the copyright holder.
No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Notices:
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
For commercial licensing, please contact: amithjkamath@outlook.com
Full license text available at: https://creativecommons.org/licenses/by-sa-nc/4.0/
|
| keywords |
medical image analysis
machine learning
neuro
radiotherapy
dose metrics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DoseMetrics
[](https://python.org)
[](https://github.com/amithjkamath/dosemetrics/actions/workflows/python-app.yml)
[](LICENSE)
[](https://github.com/amithjkamath/dosemetrics)
A comprehensive Python library for measuring radiotherapy doses and creating interactive visualizations for radiation therapy treatment planning and analysis.
## 🎯 Overview
DoseMetrics provides 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.
## ✨ Features
- **Dose Analysis**: Calculate and analyze 3D dose distributions
- **DVH Generation**: Create dose-volume histograms for organs at risk (OARs) and targets
- **Quality Metrics**: Compute conformity indices, homogeneity indices, and other plan quality metrics
- **Compliance Checking**: Evaluate dose constraints and treatment plan compliance
- **Interactive Visualizations**: Generate interactive plots using Plotly and Streamlit
- **Comparative Analysis**: Compare predicted vs. actual dose distributions
- **Geometric Analysis**: Compute spatial differences and overlaps between structures
- **Export Capabilities**: Save results in various formats (CSV, PDF, PNG)
## 🚀 Quick Start
### Installation
Install DoseMetrics using pip:
```bash
pip install dosemetrics
```
Or for development, install in editable mode:
```bash
git clone https://github.com/amithjkamath/dosemetrics.git
cd dosemetrics
pip install --editable .
```
### Interactive Web Application
Launch the interactive Streamlit application:
```bash
streamlit run app.py
```
This provides a user-friendly interface for uploading DICOM files, analyzing dose distributions, and generating reports.
## 📖 Usage Examples
### Basic DVH Analysis
```python
import dosemetrics as dm
# Load dose and structure data
dose_data = dm.data_utils.load_dose("path/to/dose.nii.gz")
structures = dm.data_utils.load_structures("path/to/structures/")
# Generate DVH
dvh = dm.dvh.calculate_dvh(dose_data, structures["PTV"])
# Plot DVH
dm.plot.plot_dvh(dvh, title="Target DVH")
```
### Quality Index Calculation
```python
# Calculate conformity and homogeneity indices
quality_metrics = dm.metrics.calculate_quality_indices(
dose_data,
target_structure,
prescription_dose=50
)
print(f"Conformity Index: {quality_metrics['CI']:.3f}")
print(f"Homogeneity Index: {quality_metrics['HI']:.3f}")
```
### Compliance Checking
```python
# Define dose constraints
constraints = {
"Brainstem": {"max_dose": 54, "unit": "Gy"},
"Spinal_Cord": {"max_dose": 45, "unit": "Gy"},
"Parotid_L": {"mean_dose": 26, "unit": "Gy"}
}
# Check compliance
compliance_results = dm.compliance.check_constraints(
dose_data, structures, constraints
)
```
## 📁 Project Structure
```
dosemetrics/
├── dosemetrics/ # Core library modules
│ ├── comparison.py # Plan comparison tools
│ ├── compliance.py # Constraint checking
│ ├── data_utils.py # Data loading utilities
│ ├── dvh.py # DVH calculation
│ ├── metrics.py # Quality metrics
│ ├── plot.py # Visualization tools
│ └── scores.py # Scoring algorithms
├── examples/ # Usage examples and scripts
├── test/ # Unit tests
├── data/ # Sample data for testing
└── app.py # Streamlit web application
```
## 🧪 Examples
The `examples/` directory contains comprehensive examples:
- **DVH Analysis**: Generate and compare dose-volume histograms
- **Quality Assessment**: Calculate treatment plan quality indices
- **Geometric Analysis**: Compute structure overlaps and distances
- **Interactive Plotting**: Create interactive visualizations
- **Report Generation**: Generate automated treatment plan reports
Run any example script:
```bash
python examples/plot_dvh_interactive.py
python examples/compare_quality_index.py
python examples/generate_dvh_family.py
```
## 🔬 Supported Data Formats
- **DICOM**: RT Dose, RT Structure Set
- **NIfTI**: `.nii`, `.nii.gz` files
- **NRRD**: Near Raw Raster Data format
- **Text**: Eclipse DVH export files
## 🛠️ Development
### Running Tests
Execute the test suite to ensure everything works correctly:
```bash
python -m unittest discover -s test -p "test_*.py"
```
### Contributing
We welcome contributions! Please see our contributing guidelines:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Requirements
- Python 3.9 or higher
- See `pyproject.toml` for complete dependency list
## 📚 Documentation
For detailed API documentation and tutorials, visit our [documentation site](https://github.com/amithjkamath/dosemetrics) (coming soon).
## 🤝 Citation
If you use DoseMetrics in your research, please cite:
```bibtex
@software{dosemetrics2024,
author = {Kamath, Amith},
title = {DoseMetrics: A Python Library for Radiotherapy Dose Analysis},
url = {https://github.com/amithjkamath/dosemetrics},
version = {0.2.0},
year = {2024}
}
```
## 📄 License
This project is licensed under the Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License - see the [LICENSE](LICENSE) file for details.
**Non-Commercial Use**: This software is freely available for academic, research, and personal use. Commercial use requires explicit written permission from the copyright holder.
For commercial licensing inquiries, please contact: amith.kamath@unibe.ch
## 👥 Contributors
- **Amith Kamath** - *Lead Developer* - [amithjkamath](https://github.com/amithjkamath)
## 🙏 Acknowledgments
- Medical physics community for guidance and feedback
- Open source medical imaging libraries that make this work possible
- Contributors and users who help improve the library
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/amithjkamath/dosemetrics/issues)
- **Email**: amith.kamath@unibe.ch
- **Discussions**: [GitHub Discussions](https://github.com/amithjkamath/dosemetrics/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "dosemetrics",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "medical image analysis, machine learning, neuro, radiotherapy, dose metrics",
"author": null,
"author_email": "Amith Kamath <amith.kamath@unibe.ch>",
"download_url": "https://files.pythonhosted.org/packages/ba/8d/eaf9b7c008d2ab9083560d9bf7d3d46890a7356ef4eb748894cb6a1e4d78/dosemetrics-0.2.0.tar.gz",
"platform": null,
"description": "# DoseMetrics\n\n[](https://python.org)\n[](https://github.com/amithjkamath/dosemetrics/actions/workflows/python-app.yml)\n[](LICENSE)\n[](https://github.com/amithjkamath/dosemetrics)\n\nA comprehensive Python library for measuring radiotherapy doses and creating interactive visualizations for radiation therapy treatment planning and analysis.\n\n## \ud83c\udfaf Overview\n\nDoseMetrics provides 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.\n\n## \u2728 Features\n\n- **Dose Analysis**: Calculate and analyze 3D dose distributions\n- **DVH Generation**: Create dose-volume histograms for organs at risk (OARs) and targets\n- **Quality Metrics**: Compute conformity indices, homogeneity indices, and other plan quality metrics\n- **Compliance Checking**: Evaluate dose constraints and treatment plan compliance\n- **Interactive Visualizations**: Generate interactive plots using Plotly and Streamlit\n- **Comparative Analysis**: Compare predicted vs. actual dose distributions\n- **Geometric Analysis**: Compute spatial differences and overlaps between structures\n- **Export Capabilities**: Save results in various formats (CSV, PDF, PNG)\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\nInstall DoseMetrics using pip:\n\n```bash\npip install dosemetrics\n```\n\nOr for development, install in editable mode:\n\n```bash\ngit clone https://github.com/amithjkamath/dosemetrics.git\ncd dosemetrics\npip install --editable .\n```\n\n### Interactive Web Application\n\nLaunch the interactive Streamlit application:\n\n```bash\nstreamlit run app.py\n```\n\nThis provides a user-friendly interface for uploading DICOM files, analyzing dose distributions, and generating reports.\n\n## \ud83d\udcd6 Usage Examples\n\n### Basic DVH Analysis\n\n```python\nimport dosemetrics as dm\n\n# Load dose and structure data\ndose_data = dm.data_utils.load_dose(\"path/to/dose.nii.gz\")\nstructures = dm.data_utils.load_structures(\"path/to/structures/\")\n\n# Generate DVH\ndvh = dm.dvh.calculate_dvh(dose_data, structures[\"PTV\"])\n\n# Plot DVH\ndm.plot.plot_dvh(dvh, title=\"Target DVH\")\n```\n\n### Quality Index Calculation\n\n```python\n# Calculate conformity and homogeneity indices\nquality_metrics = dm.metrics.calculate_quality_indices(\n dose_data, \n target_structure, \n prescription_dose=50\n)\n\nprint(f\"Conformity Index: {quality_metrics['CI']:.3f}\")\nprint(f\"Homogeneity Index: {quality_metrics['HI']:.3f}\")\n```\n\n### Compliance Checking\n\n```python\n# Define dose constraints\nconstraints = {\n \"Brainstem\": {\"max_dose\": 54, \"unit\": \"Gy\"},\n \"Spinal_Cord\": {\"max_dose\": 45, \"unit\": \"Gy\"},\n \"Parotid_L\": {\"mean_dose\": 26, \"unit\": \"Gy\"}\n}\n\n# Check compliance\ncompliance_results = dm.compliance.check_constraints(\n dose_data, structures, constraints\n)\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\ndosemetrics/\n\u251c\u2500\u2500 dosemetrics/ # Core library modules\n\u2502 \u251c\u2500\u2500 comparison.py # Plan comparison tools\n\u2502 \u251c\u2500\u2500 compliance.py # Constraint checking\n\u2502 \u251c\u2500\u2500 data_utils.py # Data loading utilities\n\u2502 \u251c\u2500\u2500 dvh.py # DVH calculation\n\u2502 \u251c\u2500\u2500 metrics.py # Quality metrics\n\u2502 \u251c\u2500\u2500 plot.py # Visualization tools\n\u2502 \u2514\u2500\u2500 scores.py # Scoring algorithms\n\u251c\u2500\u2500 examples/ # Usage examples and scripts\n\u251c\u2500\u2500 test/ # Unit tests\n\u251c\u2500\u2500 data/ # Sample data for testing\n\u2514\u2500\u2500 app.py # Streamlit web application\n```\n\n## \ud83e\uddea Examples\n\nThe `examples/` directory contains comprehensive examples:\n\n- **DVH Analysis**: Generate and compare dose-volume histograms\n- **Quality Assessment**: Calculate treatment plan quality indices\n- **Geometric Analysis**: Compute structure overlaps and distances\n- **Interactive Plotting**: Create interactive visualizations\n- **Report Generation**: Generate automated treatment plan reports\n\nRun any example script:\n\n```bash\npython examples/plot_dvh_interactive.py\npython examples/compare_quality_index.py\npython examples/generate_dvh_family.py\n```\n\n## \ud83d\udd2c Supported Data Formats\n\n- **DICOM**: RT Dose, RT Structure Set\n- **NIfTI**: `.nii`, `.nii.gz` files\n- **NRRD**: Near Raw Raster Data format\n- **Text**: Eclipse DVH export files\n\n## \ud83d\udee0\ufe0f Development\n\n### Running Tests\n\nExecute the test suite to ensure everything works correctly:\n\n```bash\npython -m unittest discover -s test -p \"test_*.py\"\n```\n\n### Contributing\n\nWe welcome contributions! Please see our contributing guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Requirements\n\n- Python 3.9 or higher\n- See `pyproject.toml` for complete dependency list\n\n## \ud83d\udcda Documentation\n\nFor detailed API documentation and tutorials, visit our [documentation site](https://github.com/amithjkamath/dosemetrics) (coming soon).\n\n## \ud83e\udd1d Citation\n\nIf you use DoseMetrics in your research, please cite:\n\n```bibtex\n@software{dosemetrics2024,\n author = {Kamath, Amith},\n title = {DoseMetrics: A Python Library for Radiotherapy Dose Analysis},\n url = {https://github.com/amithjkamath/dosemetrics},\n version = {0.2.0},\n year = {2024}\n}\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License - see the [LICENSE](LICENSE) file for details.\n\n**Non-Commercial Use**: This software is freely available for academic, research, and personal use. Commercial use requires explicit written permission from the copyright holder.\n\nFor commercial licensing inquiries, please contact: amith.kamath@unibe.ch\n\n## \ud83d\udc65 Contributors\n\n- **Amith Kamath** - *Lead Developer* - [amithjkamath](https://github.com/amithjkamath)\n\n## \ud83d\ude4f Acknowledgments\n\n- Medical physics community for guidance and feedback\n- Open source medical imaging libraries that make this work possible\n- Contributors and users who help improve the library\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/amithjkamath/dosemetrics/issues)\n- **Email**: amith.kamath@unibe.ch\n- **Discussions**: [GitHub Discussions](https://github.com/amithjkamath/dosemetrics/discussions)\n",
"bugtrack_url": null,
"license": "Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License\n \n This work is licensed under the Creative Commons Attribution-ShareAlike-NonCommercial 4.0 International License.\n \n Copyright (c) 2025 Amith Kamath\n \n You are free to:\n - Share \u2014 copy and redistribute the material in any medium or format\n - Adapt \u2014 remix, transform, and build upon the material\n \n Under the following terms:\n - Attribution \u2014 You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.\n - ShareAlike \u2014 If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.\n - NonCommercial \u2014 You may not use the material for commercial purposes without explicit written permission from the copyright holder.\n \n No additional restrictions \u2014 You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.\n \n Notices:\n You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.\n \n No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.\n \n For commercial licensing, please contact: amithjkamath@outlook.com\n \n Full license text available at: https://creativecommons.org/licenses/by-sa-nc/4.0/\n ",
"summary": "Measuring radiotherapy doses - plotting visualizations",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/amithjkamath/dosemetrics",
"Issues": "https://github.com/amithjkamath/dosemetrics/issues",
"Repository": "https://github.com/amithjkamath/dosemetrics"
},
"split_keywords": [
"medical image analysis",
" machine learning",
" neuro",
" radiotherapy",
" dose metrics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "466a20fb0c3b8a2a2a76dacf7c1bce972403684e09f7799d07d4b291d6746efc",
"md5": "ab3347a591ef88c8eb1c4a7038ff6634",
"sha256": "5e767483590617174dc0214715a9f071fdde948128c4d65f1f6e5ef93fea010b"
},
"downloads": -1,
"filename": "dosemetrics-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab3347a591ef88c8eb1c4a7038ff6634",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18663,
"upload_time": "2025-08-08T08:25:41",
"upload_time_iso_8601": "2025-08-08T08:25:41.538176Z",
"url": "https://files.pythonhosted.org/packages/46/6a/20fb0c3b8a2a2a76dacf7c1bce972403684e09f7799d07d4b291d6746efc/dosemetrics-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ba8deaf9b7c008d2ab9083560d9bf7d3d46890a7356ef4eb748894cb6a1e4d78",
"md5": "60bee8459ae3528df8e0e5f6957052c3",
"sha256": "4e4fca126df53e9c206a942f3f9d8648cc70ecf49521793987ef580e60eb7a34"
},
"downloads": -1,
"filename": "dosemetrics-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "60bee8459ae3528df8e0e5f6957052c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21388,
"upload_time": "2025-08-08T08:25:43",
"upload_time_iso_8601": "2025-08-08T08:25:43.200602Z",
"url": "https://files.pythonhosted.org/packages/ba/8d/eaf9b7c008d2ab9083560d9bf7d3d46890a7356ef4eb748894cb6a1e4d78/dosemetrics-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 08:25:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "amithjkamath",
"github_project": "dosemetrics",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dosemetrics"
}
