Your Own Data

In [1]:

# Import required libraries
import numpy as np
import pandas as pd
from pathlib import Path
import matplotlib.pyplot as plt

# Import DoseMetrics modules
from dosemetrics import Dose
from dosemetrics.io import load_structure_set, load_volume
from dosemetrics.metrics import dvh
from dosemetrics.metrics.conformity import compute_conformity_index
from dosemetrics.metrics.homogeneity import compute_homogeneity_index

print("✓ All imports successful!")

# Import required libraries import numpy as np import pandas as pd from pathlib import Path import matplotlib.pyplot as plt # Import DoseMetrics modules from dosemetrics import Dose from dosemetrics.io import load_structure_set, load_volume from dosemetrics.metrics import dvh from dosemetrics.metrics.conformity import compute_conformity_index from dosemetrics.metrics.homogeneity import compute_homogeneity_index print("✓ All imports successful!")

✓ All imports successful!

1. Data Organization¶

Recommended Directory Structure¶

Organize your data like this:

my_data/
├── patient_001/
│   ├── dose.nii.gz          # 3D dose distribution
│   └── structures/           # Binary masks for each structure
│       ├── PTV.nii.gz
│       ├── Brain.nii.gz
│       ├── Brainstem.nii.gz
│       └── Optic_Chiasm.nii.gz
├── patient_002/
│   ├── dose.nii.gz
│   └── structures/
│       └── ...
└── ...

File Format Requirements¶

Dose files:

• Format: NIfTI (.nii.gz), DICOM RT Dose (.dcm), or NRRD (.nrrd)
• Content: 3D volume with dose values in Gy or cGy
• Metadata: Must include voxel spacing and orientation

Structure masks:

• Format: NIfTI (.nii.gz), DICOM RT Struct (.dcm), or NRRD (.seg.nrrd)
• Content: Binary mask (0 = outside, 1 = inside) or labeled mask
• Critical: Must be spatially aligned with dose distribution

2. Specify Your Data Paths¶

Update these paths to point to your actual data:

In [2]:

# UPDATE THESE PATHS TO YOUR DATA
patient_dir = Path("path/to/your/patient_data")  # Change this!
dose_file = patient_dir / "dose.nii.gz"          # Path to dose file
structures_dir = patient_dir / "structures"      # Directory with structure masks

# Optional: Specify structures of interest
structures_of_interest = [
    "PTV",           # Planning target volume
    "Brain",         # Brain
    "Brainstem",     # Brainstem
    "Optic_Chiasm",  # Optic chiasm
]

print(f"Patient directory: {patient_dir}")
print(f"Dose file: {dose_file}")
print(f"Structures directory: {structures_dir}")

# UPDATE THESE PATHS TO YOUR DATA patient_dir = Path("path/to/your/patient_data") # Change this! dose_file = patient_dir / "dose.nii.gz" # Path to dose file structures_dir = patient_dir / "structures" # Directory with structure masks # Optional: Specify structures of interest structures_of_interest = [ "PTV", # Planning target volume "Brain", # Brain "Brainstem", # Brainstem "Optic_Chiasm", # Optic chiasm ] print(f"Patient directory: {patient_dir}") print(f"Dose file: {dose_file}") print(f"Structures directory: {structures_dir}")

Patient directory: path/to/your/patient_data
Dose file: path/to/your/patient_data/dose.nii.gz
Structures directory: path/to/your/patient_data/structures

3. Load Dose Distribution¶

Load the 3D dose distribution. DoseMetrics automatically handles:

• Format detection (NIfTI, DICOM, NRRD)
• Metadata extraction
• Unit conversion if needed

In [3]:

# Load dose
try:
    dose = Dose.from_nifti(dose_file, name="Patient")
    print(f"✓ Dose loaded successfully")
    print(f"  Shape: {dose.shape}")
    print(f"  Dose range: {dose.min_dose:.2f} - {dose.max_dose:.2f} Gy")
    print(f"  Mean dose: {dose.mean_dose:.2f} Gy")
    print(f"  Spacing: {dose.spacing} mm")
except FileNotFoundError:
    print(f"❌ Error: Dose file not found at {dose_file}")
    print("   Please update the path in the cell above.")
except Exception as e:
    print(f"❌ Error loading dose: {e}")

# Load dose try: dose = Dose.from_nifti(dose_file, name="Patient") print(f"✓ Dose loaded successfully") print(f" Shape: {dose.shape}") print(f" Dose range: {dose.min_dose:.2f} - {dose.max_dose:.2f} Gy") print(f" Mean dose: {dose.mean_dose:.2f} Gy") print(f" Spacing: {dose.spacing} mm") except FileNotFoundError: print(f"❌ Error: Dose file not found at {dose_file}") print(" Please update the path in the cell above.") except Exception as e: print(f"❌ Error loading dose: {e}")

❌ Error: Dose file not found at path/to/your/patient_data/dose.nii.gz
   Please update the path in the cell above.

4. Load Structure Masks¶

Load all structure masks from the structures directory:

In [4]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

5. Verify Spatial Alignment¶

Critical check: Dose and masks must have the same shape and coordinate system!

In [5]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

6. Compute DVH for All Structures¶

Calculate dose-volume histograms for all loaded structures:

In [6]:

# Compute DVH for each structure
print("Computing DVHs...")

if 'structures' in dir() and structures is not None:
    for structure_name in structures.structure_names:
        structure = structures.get_structure(structure_name)
        try:
            # DVH computation is done on-the-fly, just report success
            print(f"✓ Structure ready: {structure_name}")
        except Exception as e:
            print(f"❌ Error with {structure_name}: {e}")

    print(f"\n✓ All {len(structures.structure_names)} structures ready for analysis")
else:
    print("⚠️ No structures loaded - please configure your data paths above")

# Compute DVH for each structure print("Computing DVHs...") if 'structures' in dir() and structures is not None: for structure_name in structures.structure_names: structure = structures.get_structure(structure_name) try: # DVH computation is done on-the-fly, just report success print(f"✓ Structure ready: {structure_name}") except Exception as e: print(f"❌ Error with {structure_name}: {e}") print(f"\n✓ All {len(structures.structure_names)} structures ready for analysis") else: print("⚠️ No structures loaded - please configure your data paths above")

Computing DVHs...
⚠️ No structures loaded - please configure your data paths above

7. Visualize DVH Curves¶

Create an interactive plot showing all DVH curves:

In [7]:

# Plot all DVHs together
if 'structures' in dir() and structures is not None and 'dose' in dir() and dose is not None:
    fig, ax = plt.subplots(figsize=(12, 7))

    for structure_name in structures.structure_names:
        structure = structures.get_structure(structure_name)
        try:
            from dosemetrics.metrics import dvh
            dose_bins, volumes = dvh.compute_dvh(dose, structure)
            ax.plot(dose_bins, volumes, label=structure_name, linewidth=2)
        except Exception as e:
            print(f"Could not plot DVH for {structure_name}: {e}")

    ax.set_xlabel('Dose (Gy)', fontsize=12)
    ax.set_ylabel('Volume (%)', fontsize=12)
    ax.set_title('DVH Curves - All Structures', fontsize=14, fontweight='bold')
    ax.legend(loc='upper right')
    ax.grid(True, alpha=0.3)
    ax.set_xlim(0, None)
    ax.set_ylim(0, 105)
    plt.tight_layout()
    plt.show()
    print("✓ DVH plot generated")
else:
    print("⚠️ Dose and/or structures not loaded - please configure your data paths above")

# Plot all DVHs together if 'structures' in dir() and structures is not None and 'dose' in dir() and dose is not None: fig, ax = plt.subplots(figsize=(12, 7)) for structure_name in structures.structure_names: structure = structures.get_structure(structure_name) try: from dosemetrics.metrics import dvh dose_bins, volumes = dvh.compute_dvh(dose, structure) ax.plot(dose_bins, volumes, label=structure_name, linewidth=2) except Exception as e: print(f"Could not plot DVH for {structure_name}: {e}") ax.set_xlabel('Dose (Gy)', fontsize=12) ax.set_ylabel('Volume (%)', fontsize=12) ax.set_title('DVH Curves - All Structures', fontsize=14, fontweight='bold') ax.legend(loc='upper right') ax.grid(True, alpha=0.3) ax.set_xlim(0, None) ax.set_ylim(0, 105) plt.tight_layout() plt.show() print("✓ DVH plot generated") else: print("⚠️ Dose and/or structures not loaded - please configure your data paths above")

⚠️ Dose and/or structures not loaded - please configure your data paths above

8. Compute Quality Metrics (for Target)¶

Calculate plan quality indices for the planning target volume:

In [8]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

9. Check Dose Constraints¶

Evaluate if your plan meets clinical dose constraints:

In [9]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

10. Extract Dose Statistics¶

Get detailed dose statistics for each structure:

In [10]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

11. Export Results¶

Save your analysis results to files:

In [11]:

if 'structures' in dir() and structures is not None:
    pass  # Guarded cell - update as needed
else:
    print("⚠️ Structures not loaded")

if 'structures' in dir() and structures is not None: pass # Guarded cell - update as needed else: print("⚠️ Structures not loaded")

⚠️ Structures not loaded

Summary¶

You've now learned how to:

✅ Organize your radiotherapy data ✅ Load dose distributions and structure masks ✅ Compute dose-volume histograms ✅ Calculate quality metrics ✅ Check constraint compliance ✅ Generate visualizations ✅ Export analysis results

Next Steps¶

• Compare plans: Compare multiple treatment plans (TPS vs predicted)
• Batch processing: Analyze multiple patients efficiently
• Custom constraints: Define your own institutional constraints
• Advanced metrics: Explore gamma analysis and geometric comparisons

Need Help?¶

• Documentation
• API Reference
• Try Live Demo
• GitHub Issues

Happy analyzing! 🎉