Dose2Risk (v2.2): A Computational Pipeline for Cancer Risk Estimation from Ionizing Radiation

Read this document in other languages: Português (BR)

---

Overview

Dose2Risk is a scientific software tool designed to process radiation dose data from HotSpot simulations and estimate the cancer risk associated with ionizing radiation exposure. It implements a Hybrid Model Selection strategy, dynamically switching between BEIR VII Phase 2 (for low doses) and BEIR V (for high doses) methodologies.

The system features a Data-Driven Architecture, where all biological and epidemiological parameters are externalized in JSON configuration files, ensuring scientific auditability and flexibility. It is designed for applications in radiation protection, nuclear emergency response, and risk analysis.

New in v2.2

• Hybrid Algorithm: Automatic switching between BEIR VII (< 100 mSv) and BEIR V (> 100 mSv).
• Scientific Visualization: Automated generation of log-linear risk charts (Matplotlib).
• Audit Trail: Generation of HTML validation reports and Markdown audit logs with shadow recalculations.
• Interactive Gallery: Web interface with lightbox gallery for chart navigation.

---

Features

• Automated Data Extraction: Seamlessly parses data from HotSpot .txt output files using Regex.
• Hybrid Risk Engine: Dynamically applies Linear-No-Threshold (LNT) or Linear-Quadratic models based on dose magnitude.
• 24 Supported Organs: Full parametrization for 24 organs including Thyroid, Lung, Breast, and Leukemia.
• Data-Driven Configuration: All risk coefficients are stored in config/beir_hotspot_parameters.json and validated via JSON Schema.
• Scientific Visualization: Generates high-resolution PNG charts for ERR (Excess Relative Risk) and LAR (Lifetime Attributable Risk).
• Audit & Validation:
  • HTML Reports: Execution statistics and input integrity hashes.
  • Markdown Audit Logs: Independent shadow recalculations for compliance verification.
• Web Interface: Modern Flask UI with Internationalization (i18n), Dark Mode, and drag-and-drop upload.

---

Documentation

Comprehensive technical documentation is available in the docs/technical/ directory:

1. System Flow
2. Mathematical Detail
3. Parameterization (JSON)
4. Output Files & Audit
5. Data Collection Guide
6. Installation & Environment
7. Verification & Validation

---

Installation

To run this project, you need Python 3.8+ and the required libraries.

1. Clone the repository:

   git clone https://github.com/profalvarobarros/Dose2Risk.git
   cd Dose2Risk

2. Install dependencies: It is recommended to use a virtual environment.

   # Create virtual environment
   python -m venv .venv
   
   # Activate (Windows)
   .venv\Scripts\activate
   
   # Activate (Linux/macOS)
   source .venv/bin/activate
   
   # Install packages
   pip install -r requirements.txt

---

Usage

Web Interface

1. Start the server:

   python run.py

2. Access: Open http://127.0.0.1:5000 in your browser.

3. Workflow:

   • Upload: Select HotSpot .txt files.
   • Configure: Set Age at Exposure, Attained Age, and Filters (Sex, Organ, Model).
   • Process: The system runs the ETL pipeline, Risk Calculation, and Chart Generation.
   • Visualize: Browse results in the interactive gallery.
   • Download: Get a ZIP file containing CSVs, Logs, and PNG Charts.

Docker Support

docker build -t dose2risk .
docker run -p 5000:5000 dose2risk

---

Project Structure

Programa_Python_AR/
├── dose2risk/               # Main Application Package
│   ├── api/                 # Flask Web Interface
│   │   ├── routes.py        # Routes & Controllers
│   │   ├── templates/       # HTML Templates (Jinja2)
│   │   └── static/          # CSS/JS Assets
│   ├── core/                # Scientific Core
│   │   ├── pipeline.py      # Facade Orchestrator
│   │   ├── risk_calculator.py # Hybrid Risk Engine (BEIR V/VII)
│   │   ├── extractor.py     # HotSpot Parser
│   │   ├── transposer.py    # Matrix Transposer
│   │   ├── validator.py     # JSON Schema Validator
│   │   ├── auditor.py       # Compliance Auditor
│   │   └── reporter.py      # HTML Report Generator
│   └── vis/                 # Visualization
│       └── charts.py        # Matplotlib Chart Generator
├── config/                  # Configuration
│   └── beir_hotspot_parameters.json # Biological Parameters
├── docs/                    # Documentation
│   └── technical/           # Tech Specs (Markdown)
├── tests/                   # Test Suite
├── data/                    # I/O Directory
├── run.py                   # Entry Point
└── requirements.txt         # Dependencies

---

Scientific References

• BEIR VII (2006): Health Risks from Exposure to Low Levels of Ionizing Radiation (National Academy of Sciences).
• BEIR V (1990): Health Effects of Exposure to Low Levels of Ionizing Radiation.
• HotSpot: Health Physics Codes (Lawrence Livermore National Laboratory).

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Developed for applications in Radiation Protection, Nuclear Emergencies, and Scientific Research.