Data & I/O API¶

This module provides data structures and I/O functions for reading and writing dose distributions, structure masks, and other radiotherapy data.

I/O Functions¶

data_io ¶

Unified I/O module for radiotherapy data.

This module provides high-level functions for loading radiotherapy data from various sources (DICOM, NIfTI) with automatic format detection and intelligent structure organization.

The API is organized in layers: 1. Low-level: Format-specific readers (dicom_io, nifti_io) 2. Mid-level: Type-specific loaders (load_volume, load_structure, etc.) 3. High-level: Auto-detecting folder loaders (load_from_folder, load_structure_set)

Usage Examples¶

Loading Data from NIfTI Files¶

from dosemetrics import read_dose_and_mask_files, StructureSet

# Load dose and structures from a folder
dose, structures = read_dose_and_mask_files("path/to/patient_data")

# Access individual structures
ptv_mask = structures.get_structure_mask("PTV")
print(f"Loaded {len(structures)} structures")

Creating a StructureSet¶

from dosemetrics import StructureSet, Structure

# Create from folder
structures = StructureSet.from_folder("path/to/structures/")

# Access structure names
for name in structures.get_structure_names():
    print(f"Structure: {name}")
    mask = structures.get_structure_mask(name)
    print(f"  Volume: {mask.sum()} voxels")

Reading Dose Distribution¶

from dosemetrics.io import read_from_nifti

# Read NIfTI file
dose = read_from_nifti("path/to/dose.nii.gz")
print(f"Dose shape: {dose.shape}")
print(f"Dose range: {dose.min():.2f} - {dose.max():.2f} Gy")

Working with Multiple Files¶

from dosemetrics.io import find_all_files
from pathlib import Path

# Find all NIfTI files in directory
data_dir = Path("path/to/data")
dose_files = find_all_files(data_dir, pattern="*.nii.gz")

for dose_file in dose_files:
    print(f"Found: {dose_file}")

Batch Processing¶

from dosemetrics import read_dose_and_mask_files, compute_dvh
from pathlib import Path

# Process multiple patients
results = []
for patient_dir in Path("data").glob("patient_*"):
    # Load data
    dose, structures = read_dose_and_mask_files(patient_dir)

    # Compute metrics
    for structure_name in structures.get_structure_names():
        mask = structures.get_structure_mask(structure_name)
        dvh = compute_dvh(dose, mask, organ_name=structure_name)
        results.append({
            "patient": patient_dir.name,
            "structure": structure_name,
            "dvh": dvh
        })

Supported Formats¶

Dose Distributions¶

Format	Extension	Read	Notes
NIfTI	`.nii`, `.nii.gz`	✓	Recommended
DICOM	`.dcm`	✓	RT Dose
NRRD	`.nrrd`	✓	Research format

Structure Masks¶

Format	Extension	Read	Notes
NIfTI	`.nii`, `.nii.gz`	✓	Binary or labeled
DICOM	`.dcm`	✓	RT Structure Set
NRRD	`.seg.nrrd`	✓	Segmentation

Data Requirements¶

Spatial Alignment¶

Critical: Dose and structure masks must be spatially aligned:

Same image spacing (voxel size)
Same image dimensions
Same coordinate system origin
Same orientation

File Organization¶

Recommended structure:

patient_data/
├── dose.nii.gz
└── structures/
    ├── PTV.nii.gz
    ├── Brain.nii.gz
    └── Brainstem.nii.gz