Patch-based training
normalize_patch_transforms
def normalize_patch_transforms(
tfms:list
)->list:Extract raw TorchIO transforms from a list of fastMONAI wrappers (raw TorchIO transforms pass through).
Lets the same transform syntax work in both standard and patch-based workflows.
Args: tfms: List of fastMONAI wrappers or raw TorchIO transforms.
Returns: List of raw TorchIO transforms suitable for tio.Compose().
Example: >>> patch_tfms = normalize_patch_transforms([RandomAffine(degrees=10), RandomGamma(p=0.5)])
Configuration
PatchConfig
def PatchConfig(
patch_size:list=<factory>, patch_overlap:int | float | list=0, samples_per_volume:int=8,
sampler_type:str='uniform', label_probabilities:dict=None, queue_length:int=300, queue_num_workers:int=4,
aggregation_mode:str='hann', apply_reorder:bool=True, target_spacing:list=None, preprocessed:bool=False,
padding_mode:int | float | str=0, keep_largest_component:bool=False, binary_threshold:float=0.5,
normalization:list=None
)->None:Configuration for patch-based training and inference.
Args: patch_size: Size of patches [x, y, z]. patch_overlap: Overlap for inference GridSampler (int, float 0-1, or list). - Float 0-1: fraction of patch_size (e.g., 0.5 = 50% overlap) - Int >= 1: pixel overlap (e.g., 48 = 48 pixel overlap) - List: per-dimension overlap in pixels samples_per_volume: Number of patches to extract per volume during training. sampler_type: Type of sampler (‘uniform’ or ‘label’). label_probabilities: For LabelSampler, dict mapping label values to probabilities. queue_length: Maximum number of patches to store in queue. queue_num_workers: Number of workers for parallel patch extraction. aggregation_mode: For inference, how to combine overlapping patches (‘crop’, ‘average’, ‘hann’). apply_reorder: Whether to reorder to RAS+ canonical orientation. Must match between training and inference. Defaults to True (the common case). target_spacing: Target voxel spacing [x, y, z] for resampling. Must match between training and inference. preprocessed: If True, data has been preprocessed externally (e.g., via preprocess_dataset()). Training will skip reorder, resample, AND pre_patch_tfms (e.g., normalization) since they were already applied. Inference is unaffected and always applies pre_inference_tfms to raw images. Defaults to False. padding_mode: Padding mode for intensity images on axes smaller than patch_size, during both training and inference. Masks are always padded with background 0. Padding is removed from inference outputs before native-space restoration. Can be int, float, or string (e.g., ‘minimum’, ‘mean’). Defaults to 0. keep_largest_component: If True, keep only the largest connected component in binary segmentation predictions. Only applies during inference when return_probabilities=False. Defaults to False. Binary-only: for multi-class output (more than 2 classes) it is skipped with a warning, since it would otherwise merge all classes into one blob and collapse the labels. binary_threshold: Decision boundary for single-channel (sigmoid) masks; a voxel is foreground when probability >= binary_threshold (matches MONAI AsDiscrete). Only applies when return_probabilities=False and n_classes == 1. Defaults to 0.5. normalization: Single source of truth for pre-patch / pre-inference intensity normalization. A list of fastMONAI transforms (e.g. [ZNormalization(masking_method=‘foreground’)]) or JSON spec dicts; coerced to specs and persisted with the config. Read by both MedPatchDataLoaders.from_df (training) and PatchInferenceEngine (inference). The manual pre_patch_tfms / pre_inference_tfms args override this when provided.
Example: >>> config = PatchConfig( … patch_size=[96, 96, 96], … samples_per_volume=16, … sampler_type=‘label’, … label_probabilities={0: 0.1, 1: 0.9}, … target_spacing=[0.5, 0.5, 0.5] … )
Subject conversion
med_to_subject
def med_to_subject(
img:pathlib.Path | str, mask:pathlib.Path | str=None
)->Subject:Create a TorchIO Subject with LAZY loading (stores paths only, no tensors).
Storing only paths lets TorchIO’s Queue workers load volumes on-demand during training, keeping RAM usage low.
Args: img: Path to image file. mask: Path to mask file (optional).
Returns: TorchIO Subject with ‘image’ and optionally ‘mask’ keys (lazy loaded).
Example: >>> subject = med_to_subject(‘image.nii.gz’, ‘mask.nii.gz’) >>> data = subject[‘image’].data # volume loaded only now
create_subjects_dataset
def create_subjects_dataset(
df:DataFrame, img_col:str, mask_col:str=None, pre_tfms:list=None, ensure_affine_consistency:bool=True
)->SubjectsDataset:Build a TorchIO SubjectsDataset with LAZY loading from a DataFrame.
Stores only file paths (not tensors); volumes are loaded on-demand by Queue workers, keeping memory usage constant regardless of dataset size.
Args: df: DataFrame with image (and optionally mask) paths. img_col: Column name containing image paths. mask_col: Column name containing mask paths (optional). pre_tfms: List of TorchIO transforms to apply before patch extraction. Use tio.ToCanonical() for reordering and tio.Resample() for resampling. ensure_affine_consistency: If True and mask_col is provided, automatically prepends tio.CopyAffine(target=‘image’) to ensure spatial metadata consistency between image and mask. This prevents “More than one value for direction found” errors. Defaults to True.
Returns: TorchIO SubjectsDataset with lazy-loaded subjects.
Example: >>> pre_tfms = [tio.ToCanonical(), tio.Resample([0.5, 0.5, 0.5]), tio.ZNormalization()] >>> dataset = create_subjects_dataset(df, img_col=‘image’, mask_col=‘label’, pre_tfms=pre_tfms)
Sampler creation
create_patch_sampler
def create_patch_sampler(
config:PatchConfig
)->PatchSampler:Create appropriate TorchIO sampler based on config.
Args: config: PatchConfig with sampler settings.
Returns: TorchIO PatchSampler instance.
Example: >>> config = PatchConfig(patch_size=[96, 96, 96], sampler_type=‘label’) >>> sampler = create_patch_sampler(config)
Patch DataLoaders
MedPatchDataLoader
def MedPatchDataLoader(
subjects_dataset:SubjectsDataset, config:PatchConfig, batch_size:int=4, patch_tfms:list=None,
gpu_augmentation:NoneType=None, shuffle:bool=True, drop_last:bool=False
):DataLoader wrapper for patch-based training with TorchIO Queue.
This class wraps a TorchIO Queue to provide a fastai-compatible DataLoader interface for patch-based training.
Args: subjects_dataset: TorchIO SubjectsDataset. config: PatchConfig with queue and sampler settings. batch_size: Number of patches per batch. Must be positive. patch_tfms: Transforms to apply to extracted patches (training only). Accepts both fastMONAI wrappers (e.g., RandomAffine, RandomGamma) and raw TorchIO transforms. fastMONAI wrappers are automatically normalized to raw TorchIO for internal use. Mutually exclusive with gpu_augmentation. gpu_augmentation: GpuPatchAugmentation instance for GPU-batched augmentation. Operates on [B, C, X, Y, Z] tensors already on GPU, avoiding per-sample CPU overhead. Mutually exclusive with patch_tfms. Training only. shuffle: Whether to shuffle subjects and patches. drop_last: Whether to drop last incomplete batch.
MedPatchDataLoaders
def MedPatchDataLoaders(
train_dl:MedPatchDataLoader, valid_dl:MedPatchDataLoader, device:device=None
):fastai-compatible DataLoaders for patch-based training with LAZY loading.
This class provides train and validation DataLoaders that work with fastai’s Learner for patch-based training on 3D medical images.
Memory-efficient: Volumes are loaded on-demand by Queue workers, keeping memory usage constant (~150 MB) regardless of dataset size.
Note: Validation uses the same sampling as training (pseudo Dice). For true validation metrics, use PatchInferenceEngine with GridSampler for full-volume sliding window inference.
Example: >>> config = PatchConfig(patch_size=[96, 96, 96], apply_reorder=True, target_spacing=[0.5, 0.5, 0.5], … normalization=[ZNormalization(masking_method=‘foreground’)]) >>> dls = MedPatchDataLoaders.from_df( … df, img_col=‘image’, mask_col=‘label’, valid_pct=0.2, patch_config=config, bs=4 … ) >>> learn = Learner(dls, model, loss_func=DiceLoss())
Patch-based Inference
PatchInferenceEngine
def PatchInferenceEngine(
learner, config:PatchConfig, apply_reorder:bool=None, target_spacing:list=None,
sw_batch_size:int=1, # Memory-safe for large 3D patches; tune upward after benchmarking.
pre_inference_tfms:list=None, amp:bool=False, label_interpolation:str='shape'
):Patch-based inference with automatic volume reconstruction.
Uses TorchIO’s GridSampler to extract overlapping patches and GridAggregator to reconstruct the full volume from predictions.
Args: learner: fastai Learner or PyTorch model (nn.Module), or a list of them for soft-vote ensembling (per-patch probabilities are averaged before argmax/ threshold). When passing a raw PyTorch model, load weights first with model.load_state_dict(). A torch.compile’d model is unwrapped for inference; the caller’s wrapper object is left in place. config: PatchConfig with inference settings. Preprocessing params (apply_reorder, target_spacing, padding_mode) can be set here for DRY usage. apply_reorder: Whether to reorder to RAS+ orientation. If None, uses config value. target_spacing: Target voxel spacing. If None, uses config value. sw_batch_size: Number of patches to predict at once. Defaults to 1 as the memory-safe choice for large 3D patches; benchmark higher values for the target accelerator. Must be positive. pre_inference_tfms: Optional override for config.normalization. If None, normalization is read from config.normalization (the default source of truth, set at training time). Provide this only to override the config (e.g. for non-serializable transforms). Accepts both fastMONAI wrappers and raw TorchIO transforms. amp: If True, use automatic mixed precision (bfloat16) for the forward pass. Only supported on CUDA devices; ignored with a warning on CPU/MPS. Defaults to False. label_interpolation: How decoded masks are restored to the original grid. ‘shape’ (default) uses shape-based interpolation, so a slice between two model slices gets an outline between theirs. ‘nearest’ copies the nearest voxel, which repeats slices when the original slices are thinner.
Example: >>> # normalization is read from config.normalization; amp=True for faster GPU >>> config = PatchConfig(patch_size=[96, 96, 96], normalization=[ZNormalization(masking_method=‘foreground’)]) >>> engine = PatchInferenceEngine(learn, config) >>> pred = engine.predict(‘image.nii.gz’)
patch_inference
def patch_inference(
learner, config:PatchConfig, file_paths:list, apply_reorder:bool=None, target_spacing:list=None,
sw_batch_size:int=1, # Memory-safe for large 3D patches; tune upward after benchmarking.
return_probabilities:bool=False, progress:bool=True, save_dir:str=None, pre_inference_tfms:list=None,
tta:bool | tuple | list=False, prefetch:bool=True, amp:bool=False, label_interpolation:str='shape'
)->list:Batch patch-based inference on multiple volumes.
When prefetch=True (default), overlaps I/O with compute: while the current image is being inferred, the next image is loaded and preprocessed in a background thread, and the previous result is saved in the background. This eliminates most I/O idle time, especially on GPU where CPU prep and GPU compute use different hardware.
Args: learner: PyTorch model or fastai Learner, or a list of them to soft-vote ensemble (per-patch probabilities are averaged before argmax/threshold). config: PatchConfig with inference settings. Preprocessing params (apply_reorder, target_spacing) can be set here for DRY usage. file_paths: List of image paths. apply_reorder: Whether to reorder to RAS+ orientation. If None, uses config value. target_spacing: Target voxel spacing. If None, uses config value. sw_batch_size: Patches per batch. Defaults to 1 as the memory-safe choice for large 3D patches; benchmark higher values for the target accelerator. return_probabilities: Return probability maps. progress: Show progress bar. save_dir: Directory to save predictions as NIfTI files. If None, predictions are not saved. pre_inference_tfms: Optional override for config.normalization. If None, normalization is read from config.normalization (the source of truth set at training time). Provide this only to override the config (e.g. for non-serializable transforms). tta: If True, mirror TTA (8 flip combinations); a sequence of flip-axis tuples uses only those flips, e.g. [(), (4,)]. prefetch: If True (default), overlap I/O with compute using a background thread for preparation and saving. Holds two subjects in memory simultaneously (current + next). Set to False for memory-constrained environments processing very large volumes. amp: If True, use automatic mixed precision (bfloat16) for the forward pass. Only supported on CUDA devices; ignored with a warning on CPU/MPS. label_interpolation: How decoded masks are restored to the original grid: ‘shape’ (default) or ‘nearest’. See PatchInferenceEngine.
Returns: List of predicted tensors.
Example: >>> config = PatchConfig(patch_size=[96, 96, 96], apply_reorder=True, target_spacing=[0.4102, 0.4102, 1.5], … normalization=[ZNormalization(masking_method=‘foreground’)]) >>> predictions = patch_inference( # normalization auto-applied from config … learner=learn, config=config, file_paths=val_paths, … save_dir=‘predictions/patch_based’, amp=True … )
prediction_filename
def prediction_filename(
input_path:str | pathlib.Path
)->str:Return the filename used by patch inference for a saved prediction.