Add 3D segmentation calibration tutorial (#2072)

## Description

Adds an introductory tutorial for the average calibration losses
proposed in Project-MONAI/MONAI#9092.

The notebook explains predictive calibration, why it matters for medical
image segmentation, and how to interpret reliability diagrams. It then
compares a segmentation-only baseline with one validation-selected Hard
L1-ACE configuration on complete 3D volumes from Medical Segmentation
Decathlon Task04 Hippocampus.

The example intentionally keeps the experiment simple: two training runs
with identical initialization, data order, augmentations, and
optimization settings. The calibrated objective uses a `1:1:0.30`
Dice:CE:Hard-L1-ACE ratio. The held-out test set is not accessed until
both validation-selected checkpoints have been fixed.

## Saved tutorial result

| Configuration | Dice | ACE | MCE |
| --- | ---: | ---: | ---: |
| Segmentation only | 0.799317 | 0.117391 | 0.295517 |
| Hard L1-ACE | 0.828645 | 0.090355 | 0.208534 |

This corresponds to a 23% reduction in held-out ACE and a 29% reduction
in MCE, while Dice increases by 0.0293 for this split and seed. The
notebook explicitly presents this as a demonstration rather than a
benchmark guarantee.

## Validation

- Executed all 36 cells end to end on an NVIDIA RTX 5090
- Passed the repository runner with a one-epoch execution
- Passed targeted notebook schema, syntax, formatting, PEP8, metadata,
and output checks
- Confirmed that saved outputs contain no execution errors or private
local paths

## Dependency

Depends on Project-MONAI/MONAI#9092 for `HardL1ACELoss` and
`SoftL1ACELoss`.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Added a Calibration tutorial using complete 3D MRI volumes from the
MSD Task04 Hippocampus dataset.
- Documented calibration metrics and losses, and the comparison of a
baseline with a validation-selected Dice:CE:Hard-L1-ACE configuration on
separate held-out test volumes.
- Added guidance for running the experiment, including a one-epoch CI
smoke test, dataset requirements, recommended GPU hardware, and required
MONAI APIs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Theo Barfoot <theo.barfoot@gmail.com>
Signed-off-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com>

Author: 3 people

README.md

@@ -101,6 +101,13 @@ Each user is responsible for checking the content of datasets and the applicable
 You can read details about adding a tutorial in our [CONTRIBUTING GUIDELINES](CONTRIBUTING.md).
 
 ### 4. List of notebooks and examples
+#### <ins>**Calibration**</ins>
+##### [Training and evaluating calibrated segmentation models](./calibration/segmentation_calibration.ipynb)
+This tutorial trains two models on complete 3D MRI volumes from the Medical Segmentation Decathlon
+`Task04_Hippocampus` dataset to demonstrate calibration metrics, reliability diagrams, the Ignite calibration
+handler, and L1-ACE auxiliary training. It compares a validation-selected hard L1-ACE configuration with a controlled
+segmentation baseline on separate held-out test volumes.
+
 #### <ins>**2D classification**</ins>
 ##### [mednist_tutorial](./2d_classification/mednist_tutorial.ipynb)
 This notebook shows how to easily integrate MONAI features into existing PyTorch programs.

calibration/README.md

@@ -0,0 +1,26 @@
+# Segmentation model calibration
+
+This folder contains a self-contained tutorial for evaluating and improving the marginal class-wise calibration of
+semantic segmentation models. It trains on complete 3D volumes from the Medical Segmentation Decathlon
+`Task04_Hippocampus` MRI dataset. The notebook downloads the approximately 28 MB archive automatically and reuses
+the directory configured by `MONAI_DATA_DIRECTORY`.
+
+The notebook demonstrates MONAI's calibration metrics, low-level bin statistics, Ignite handler, and hard- and
+soft-binned L1 Average Calibration Error losses. It uses complete-volume train/validation/test cohorts and compares
+a segmentation baseline with one hard L1-ACE configuration chosen in validation-only preliminary experiments for
+its calibration improvement with minimal Dice reduction. The focused comparison uses a validation-selected
+Dice:CE:Hard-L1-ACE objective with an approximate ratio of 1:1:0.30. It also discusses the associated publication's
+1:1:1 objective, finite-bin estimates, and the limitations of auxiliary calibration training.
+
+For a one-epoch CI smoke test, run:
+
+```bash
+export MONAI_DATA_DIRECTORY=/path/to/persistent/monai-data
+./runner.sh -t calibration/segmentation_calibration.ipynb
+```
+
+`runner.sh` rewrites `max_epochs` and `val_interval` to one. To reproduce the saved full experiment, open the notebook
+in Jupyter and run all cells without that rewrite. A CUDA GPU is strongly recommended for the two 3D training runs.
+
+The notebook requires a MONAI build containing `HardL1ACELoss` and `SoftL1ACELoss`. Until those APIs are available in
+an official MONAI package, run it in an environment with the corresponding MONAI core contribution installed editable.