Skip to content

feat: add TTA, EMA checkpointing, RandomAnisotropy; bump to 0.8.0 #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
skaliy merged 1 commit into from
Feb 13, 2026
Merged

feat: add TTA, EMA checkpointing, RandomAnisotropy; bump to 0.8.0 #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 96 additions & 11 deletions .claude/skills/fastmonai-upstream-guide/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,18 @@ Use this skill proactively when:
- **Losses:** https://docs.monai.io/en/stable/losses.html
- **Transforms:** https://docs.monai.io/en/stable/transforms.html

### nnU-Net
- **Repository:** https://github.com/MIC-DKFZ/nnUNet
- **Documentation:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/
### nnU-Net v2
- **Repository:** https://github.com/MIC-DKFZ/nnUNet (complete rewrite of v1, Apache 2.0)
- **Documentation index:** https://github.com/MIC-DKFZ/nnUNet/tree/master/documentation
- **How to use:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/how_to_use_nnunet.md
- **Dataset format:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/dataset_format.md
- **Extending nnU-Net:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/extending_nnunet.md
- **Normalization explained:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/explanation_normalization.md
- **Plans files explained:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/explanation_plans_files.md
- **Pretraining/finetuning:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/pretraining_and_finetuning.md
- **Region-based training:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/region_based_training.md
- **Ignore label:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/ignore_label.md
- **ResEnc presets:** https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/resenc_presets.md

## Source Code URLs (for implementation details)

Expand All @@ -59,9 +68,21 @@ Use this skill proactively when:
- **Hausdorff:** https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/monai/metrics/hausdorff_distance.py
- **Losses:** https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/monai/losses/

### nnU-Net GitHub
- **Preprocessing:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/preprocessing
- **Training:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/training
### nnU-Net v2 GitHub (source code)
- **Package root:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2
- **Preprocessing root:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/preprocessing
- **Normalization schemes:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/preprocessing/normalization/default_normalization_schemes.py
- **Resampling:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/preprocessing/resampling
- **Training root:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/training
- **Base trainer:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/nnUNetTrainer/nnUNetTrainer.py
- **Trainer variants:** https://github.com/MIC-DKFZ/nnUNet/tree/master/nnunetv2/training/nnUNetTrainer/variants
- **Dice loss:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/dice.py
- **Compound losses (DC+CE, DC+BCE, DC+TopK):** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/compound_losses.py
- **Robust CE loss:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/robust_ce_loss.py
- **Deep supervision loss:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/deep_supervision.py
- **Evaluation metrics:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/evaluation/evaluate_predictions.py
- **Sliding window inference:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/inference/sliding_window_prediction.py
- **Predict from raw data:** https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/inference/predict_from_raw_data.py

## Workflow Steps

Expand All @@ -70,7 +91,9 @@ Use this skill proactively when:
- Metric → MONAI (compute functions) + nnU-Net (accumulated patterns)
- Loss function → MONAI
- Patch workflow → TorchIO (Queue, GridSampler)
- Preprocessing → nnU-Net conventions
- Preprocessing/normalization → nnU-Net v2 conventions
- Sliding window inference → nnU-Net v2 (Gaussian weighting, tile step size)
- Evaluation metrics → nnU-Net v2 (TP/FP/FN accumulation, Dice, IoU)

2. **Fetch relevant documentation**
Use WebFetch to retrieve the appropriate documentation page from the URLs above.
Expand Down Expand Up @@ -117,13 +140,45 @@ tio.CropOrPad(target_size) # Avoid - uses TorchIO default
- TorchIO uses: [C, D, H, W] for single images
- fastMONAI MedImage/MedMask: 4D tensors with affine tracking

### Accumulated Metrics (nnU-Net pattern)
### Accumulated Metrics (nnU-Net v2 pattern)
For patch-based training, use accumulated TP/FP/FN rather than per-batch averaging:
```python
class AccumulatedDice(Metric):
# Accumulates across batches, not averages
```

### nnU-Net v2 Quick Reference

**Architecture:** The `nnunetv2/` package is organized into: preprocessing, training, inference, evaluation, experiment_planning, postprocessing, utilities.

**Normalization schemes** (in `default_normalization_schemes.py`):
- `ZScoreNormalization` - z-score with optional foreground masking (default for MR)
- `CTNormalization` - clip to 0.5th-99.5th percentiles then z-score (for CT)
- `NoNormalization` - passthrough (dtype conversion only)
- `RescaleTo01Normalization` - min-max to [0,1]
- `RGBTo01Normalization` - divide uint8 by 255

**Loss functions** (in `training/loss/`):
- `SoftDiceLoss(apply_nonlin, batch_dice, do_bg, smooth=1.0, ddp, clip_tp)` - standard soft Dice
- `MemoryEfficientSoftDiceLoss` - same API, ~1.6GB less memory via no-grad one-hot encoding
- `DC_and_CE_loss(soft_dice_kwargs, ce_kwargs, weight_ce=1, weight_dice=1, ignore_label)` - Dice + Cross-Entropy (default nnU-Net loss)
- `DC_and_BCE_loss(bce_kwargs, soft_dice_kwargs, weight_ce=1, weight_dice=1)` - Dice + Binary CE
- `DC_and_topk_loss(soft_dice_kwargs, ce_kwargs, weight_ce=1, weight_dice=1)` - Dice + TopK

**Evaluation metrics** (in `evaluation/evaluate_predictions.py`):
- Computes per-class: Dice, IoU, TP, FP, FN, TN
- `compute_tp_fp_fn_tn(mask_ref, mask_pred, ignore_mask)` - core confusion matrix
- `compute_metrics(reference_file, prediction_file, image_reader_writer, labels_or_regions, ignore_label)` - per-file metrics
- `compute_metrics_on_folder()` / `compute_metrics_on_folder_simple()` - batch evaluation with multiprocessing

**Sliding window inference** (in `inference/sliding_window_prediction.py`):
- `compute_steps_for_sliding_window(image_size, tile_size, tile_step_size)` - tile_step_size is 0-1 (0.5 = 50% overlap)
- `compute_gaussian(tile_size)` - Gaussian importance weighting for smooth tile aggregation (center-weighted, no zeros)
- Supports test-time augmentation via mirror axes

**Trainer variants** (in `training/nnUNetTrainer/variants/`):
Subdirectories for: benchmarking, data_augmentation, loss, lr_schedule, network_architecture, optimizer, sampling, training_length

### nbdev Workflow
- All code changes in `nbs/*.ipynb`
- Run `nbdev_prepare` to regenerate .py files and run tests
Expand All @@ -140,10 +195,19 @@ When implementing, fetch relevant docs/code:
→ Fetch MONAI metrics documentation

**"How does nnU-Net handle validation metrics?"**
→ Fetch nnU-Net training code for accumulated patterns
→ Fetch nnU-Net v2 evaluation code for TP/FP/FN accumulation patterns

**"What loss does nnU-Net v2 use by default?"**
→ Fetch compound_losses.py for DC_and_CE_loss (Dice + Cross-Entropy)

**"How does nnU-Net v2 do sliding window inference?"**
→ Fetch sliding_window_prediction.py for tile stepping and Gaussian weighting

**"What normalization does nnU-Net v2 use for MR images?"**
→ Fetch default_normalization_schemes.py for ZScoreNormalization

**"I want to add a new loss function"**
→ Fetch MONAI losses documentation and source
→ Fetch MONAI losses documentation and nnU-Net v2 compound_losses.py

## Quick Reference Commands

Expand All @@ -156,6 +220,27 @@ WebFetch: https://torchio.readthedocs.io/transforms/augmentation.html
# MONAI metric implementation
WebFetch: https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/monai/metrics/meandice.py

# nnU-Net preprocessing patterns
# nnU-Net v2 usage guide
WebFetch: https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/how_to_use_nnunet.md

# nnU-Net v2 normalization schemes (ZScore, CT, RescaleTo01, etc.)
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/preprocessing/normalization/default_normalization_schemes.py

# nnU-Net v2 default loss (Dice + CE compound)
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/compound_losses.py

# nnU-Net v2 Dice loss implementation
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/loss/dice.py

# nnU-Net v2 evaluation metrics (Dice, IoU, TP/FP/FN)
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/evaluation/evaluate_predictions.py

# nnU-Net v2 sliding window inference (Gaussian weighting)
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/inference/sliding_window_prediction.py

# nnU-Net v2 base trainer (training loop, validation, scheduling)
WebFetch: https://raw.githubusercontent.com/MIC-DKFZ/nnUNet/master/nnunetv2/training/nnUNetTrainer/nnUNetTrainer.py

# nnU-Net v2 extending guide (custom trainers, architectures)
WebFetch: https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/extending_nnunet.md
```
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,7 @@ _proc/

# MLflow
mlruns/
mlruns.db

# Reports
reports/
Expand Down
2 changes: 1 addition & 1 deletion fastMONAI/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.7.0"
__version__ = "0.8.0"
22 changes: 21 additions & 1 deletion fastMONAI/_modidx.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,14 @@
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomAffine.__init__': ( 'vision_augment.html#randomaffine.__init__',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomAnisotropy': ( 'vision_augment.html#randomanisotropy',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomAnisotropy.__init__': ( 'vision_augment.html#randomanisotropy.__init__',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomAnisotropy.encodes': ( 'vision_augment.html#randomanisotropy.encodes',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomAnisotropy.tio_transform': ( 'vision_augment.html#randomanisotropy.tio_transform',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomBiasField': ( 'vision_augment.html#randombiasfield',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.RandomBiasField.__init__': ( 'vision_augment.html#randombiasfield.__init__',
Expand Down Expand Up @@ -284,7 +292,9 @@
'fastMONAI.vision_augmentation._create_ellipsoid_mask': ( 'vision_augment.html#_create_ellipsoid_mask',
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.do_pad_or_crop': ( 'vision_augment.html#do_pad_or_crop',
'fastMONAI/vision_augmentation.py')},
'fastMONAI/vision_augmentation.py'),
'fastMONAI.vision_augmentation.suggest_patch_augmentations': ( 'vision_augment.html#suggest_patch_augmentations',
'fastMONAI/vision_augmentation.py')},
'fastMONAI.vision_core': { 'fastMONAI.vision_core.MedBase': ('vision_core.html#medbase', 'fastMONAI/vision_core.py'),
'fastMONAI.vision_core.MedBase.__copy__': ( 'vision_core.html#medbase.__copy__',
'fastMONAI/vision_core.py'),
Expand Down Expand Up @@ -383,6 +393,14 @@
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.AccumulatedMultiDice.value': ( 'vision_metrics.html#accumulatedmultidice.value',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.EMACheckpoint': ( 'vision_metrics.html#emacheckpoint',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.EMACheckpoint.__init__': ( 'vision_metrics.html#emacheckpoint.__init__',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.EMACheckpoint.after_epoch': ( 'vision_metrics.html#emacheckpoint.after_epoch',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.EMACheckpoint.before_fit': ( 'vision_metrics.html#emacheckpoint.before_fit',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.binary_dice_score': ( 'vision_metrics.html#binary_dice_score',
'fastMONAI/vision_metrics.py'),
'fastMONAI.vision_metrics.binary_hausdorff_distance': ( 'vision_metrics.html#binary_hausdorff_distance',
Expand Down Expand Up @@ -513,6 +531,8 @@
'fastMONAI/vision_patch.py'),
'fastMONAI.vision_patch._normalize_patch_overlap': ( 'vision_patch.html#_normalize_patch_overlap',
'fastMONAI/vision_patch.py'),
'fastMONAI.vision_patch._predict_patch_tta': ( 'vision_patch.html#_predict_patch_tta',
'fastMONAI/vision_patch.py'),
'fastMONAI.vision_patch._warn_config_override': ( 'vision_patch.html#_warn_config_override',
'fastMONAI/vision_patch.py'),
'fastMONAI.vision_patch.create_patch_sampler': ( 'vision_patch.html#create_patch_sampler',
Expand Down
Loading