Address review feedback for RankSEG tutorial

Signed-off-by: statmlben <bdai.hk@protonmail.com>

Author: statmlben

modules/rankseg_integration.ipynb

@@ -24,6 +24,35 @@
     "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Project-MONAI/tutorials/blob/main/modules/rankseg_integration.ipynb)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## What is RankSEG?\n",
+    "\n",
+    "A segmentation network usually produces a score or probability for every class at every voxel. A conventional multiclass pipeline converts these values to a mask with `argmax`, independently assigning each voxel to the class with the largest score. This is a natural rule for voxel-wise classification, but it does not directly target region-level metrics such as Dice or IoU, whose values depend on the predicted region as a whole.\n",
+    "\n",
+    "RankSEG is an inference-time, metric-aware alternative to argmax or fixed thresholding. It leaves the trained model and its probability maps unchanged, and only replaces the final probability-to-mask decision. Unlike connected-component filtering or morphological post-processing, RankSEG does not impose connectivity, shape, or anatomical constraints.\n",
+    "\n",
+    "| Property | Argmax / fixed threshold | RankSEG |\n",
+    "| --- | --- | --- |\n",
+    "| Decision | Independent at each voxel | Based on each class probability map as a whole |\n",
+    "| Target | Voxel-wise class decision | A selected region metric, such as Dice or IoU |\n",
+    "| Region size | Implicit or controlled by a fixed threshold | Adaptively selected for each image and class |\n",
+    "| Model training | Unchanged | Unchanged |\n",
+    "| Additional inference cost | Minimal | Probability ranking and metric-aware optimization |\n",
+    "\n",
+    "### How the algorithm works\n",
+    "\n",
+    "For each class, RankSEG ranks voxels from highest to lowest predicted probability. The `RMA` solver used in this tutorial then estimates how many of the highest-ranked voxels should be included to target the selected metric. In multiclass mode, the class masks are finally combined into one non-overlapping label map. No model retraining or threshold tuning is required.\n",
+    "\n",
+    "### When should RankSEG be considered?\n",
+    "\n",
+    "RankSEG can be useful when Dice or IoU is the evaluation target and the model produces meaningful probability maps, particularly for uncertain predictions or small-to-medium foreground regions. When predictions are already confident, RankSEG and argmax may produce nearly identical masks.\n",
+    "\n",
+    "RankSEG does not correct errors in the underlying probability maps, and its output depends on their quality and calibration. It also adds computation and memory use during inference because the probabilities must be ranked. Improvement is not guaranteed for every case or deployment distribution, so the metric, output mode, and solver should be selected deliberately and validated on representative data. The case below illustrates the integration rather than serving as a standalone performance benchmark."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -44,10 +73,7 @@
    },
    "outputs": [],
    "source": [
-    "!python -c \"import monai\" || pip install -q \"monai-weekly[nibabel, tqdm]\"\n",
-    "!python -c \"import rankseg\" || pip install -q \"rankseg\"\n",
-    "!python -c \"import huggingface_hub\" || pip install -q huggingface_hub\n",
-    "!python -c \"import matplotlib\" || pip install -q matplotlib\n",
+    "%pip install -q --upgrade-strategy only-if-needed \"monai-weekly[nibabel, tqdm,matplotlib,huggingface_hub]\" rankseg\n",
     "%matplotlib inline"
    ]
   },
@@ -260,12 +286,11 @@
     "import matplotlib.pyplot as plt\n",
     "import torch\n",
     "from huggingface_hub import hf_hub_download\n",
-    "from monai.bundle import download\n",
+    "from monai.bundle import ConfigParser, download\n",
     "from monai.config import print_config\n",
     "from monai.data import decollate_batch\n",
     "from monai.inferers import SlidingWindowInferer\n",
     "from monai.metrics import DiceMetric\n",
-    "from monai.networks.nets import DiNTS, TopologyInstance\n",
     "from monai.transforms import (\n",
     "    Activations,\n",
     "    Activationsd,\n",
@@ -632,21 +657,11 @@
     "    map_location=device,\n",
     "    weights_only=False,\n",
     ")\n",
-    "topology = TopologyInstance(\n",
-    "    channel_mul=1,\n",
-    "    num_blocks=12,\n",
-    "    num_depths=4,\n",
-    "    use_downsample=True,\n",
-    "    arch_code=[architecture[\"arch_code_a\"], architecture[\"arch_code_c\"]],\n",
-    "    device=str(device),\n",
-    ")\n",
-    "model = DiNTS(\n",
-    "    dints_space=topology,\n",
-    "    in_channels=1,\n",
-    "    num_classes=3,\n",
-    "    use_downsample=True,\n",
-    "    node_a=torch.as_tensor(architecture[\"node_a\"], device=device),\n",
-    ").to(device)\n",
+    "parser = ConfigParser()\n",
+    "parser.read_config(os.path.join(bundle_dir, \"configs\", \"inference.yaml\"))\n",
+    "parser[\"arch_ckpt\"] = architecture\n",
+    "parser[\"dints_space#device\"] = str(device)\n",
+    "model = parser.get_parsed_content(\"network_def\").to(device)\n",
     "checkpoint = torch.load(\n",
     "    os.path.join(bundle_dir, \"models\", \"model.pt\"),\n",
     "    map_location=device,\n",
@@ -960,6 +975,8 @@
     "Further reading:\n",
     "\n",
     "- [RankSEG repository and documentation](https://github.com/rankseg/rankseg)\n",
+    "- [RankSEG: A Consistent Ranking-based Framework for Segmentation](https://www.jmlr.org/papers/v24/22-0712.html)\n",
+    "- [RankSEG-RMA: An Efficient Segmentation Algorithm via Reciprocal Moment Approximation](https://openreview.net/forum?id=4tRMm1JJhw)\n",
     "- [Reproducible MONAI Pancreas comparison](https://github.com/rankseg/rankseg/tree/main/experiments/monai-pr-8908-reproducibility)\n",
     "- [MONAI Pancreas CT DiNTS Segmentation Bundle](https://github.com/Project-MONAI/model-zoo/tree/dev/models/pancreas_ct_dints_segmentation)\n",
     "- [Discussion of Option B in MONAI PR #8908](https://github.com/Project-MONAI/MONAI/pull/8908#issuecomment-5077397523)"