Add RankSEG integration tutorial

[statmlben]

Related to MONAI-#8908

Description

This PR adds a runnable tutorial demonstrating how to use RankSEG as an optional third-party post-processing transform in a MONAI workflow.

The tutorial:

• uses the pretrained pancreas_ct_dints_segmentation MONAI Bundle and a real MSD Task07 Pancreas case;
• compares conventional argmax decoding with RankSEG using per-class Dice scores and a visualization;
• demonstrates the array-based RankSEG transform;
• demonstrates the dictionary-based RankSEGd transform in a MONAI Compose post-processing pipeline;
• documents the public dataset source, CC BY-SA 4.0 license, and research-use context.

This PR also adds the tutorial to the repository README and registers it in doesnt_contain_max_epochs because it is an inference-only notebook.

Checks

• Avoid including large-size files in the PR.
• Clean up long text outputs from code cells in the notebook.
• Check the contents and remove sensitive information such as user names and private keys.
• Verify hyperlinks, markdown content, and relative repository paths.
• Notebook runs automatically with:

./runner.sh -t modules/rankseg_integration.ipynb

Results

Argmax macro Dice: 0.7747
RankSEG macro Dice: 0.8502
Paired Dice change: +0.0755
Pancreas Dice: 0.8764 -> 0.8898
Tumor Dice: 0.6730 -> 0.8106

Summary by CodeRabbit

• New Features

  • Added a tutorial for optional RankSEG/RankSEGd post-processing in MONAI segmentation workflows.
  • Compares RankSEG results with standard argmax predictions using a pretrained pancreas segmentation model.
  • Includes Dice score evaluation, visual comparisons, and tensor- and dictionary-based workflow examples.
  • Demonstrates dataset preparation and integration validation.

• Documentation

  • Added the RankSEG integration notebook to the list of available modules and examples.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3bba29b3-1247-4481-9f8b-29482c4ed743

📥 Commits

Reviewing files that changed from the base of the PR and between e245db0 and 1efa798.

📒 Files selected for processing (1)

• modules/rankseg_integration.ipynb

---

Walkthrough

Adds a MONAI tutorial with RankSEG and RankSEGd transforms. The notebook runs pretrained pancreas inference, compares RankSEG with argmax using Dice scores, and documents the integration. README and runner support are updated.

Changes

RankSEG tutorial integration

Layer / File(s)	Summary
RankSEG transform contracts modules/rankseg_integration.ipynb	Adds RankSEG and RankSEGd wrappers for multiclass probability decoding and keyed MONAI pipelines.
Verified pancreas data and model setup modules/rankseg_integration.ipynb	Downloads and verifies MSD Pancreas data, preprocesses inputs, and loads the pretrained Pancreas DiNTS Bundle.
Inference comparison and validation modules/rankseg_integration.ipynb	Runs sliding-window inference, compares argmax and RankSEG predictions with Dice metrics, and visualizes tumor differences.
Notebook publication and execution support README.md, runner.sh, modules/rankseg_integration.ipynb	Adds the notebook to the README, exempts it from the runner’s max_epochs check, and adds cleanup and metadata.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Notebook
  participant MSD Pancreas Archive
  participant Pancreas DiNTS Bundle
  participant RankSEG
  participant Dice Evaluation
  Notebook->>MSD Pancreas Archive: download and verify case members
  Notebook->>Pancreas DiNTS Bundle: load model and run sliding-window inference
  Pancreas DiNTS Bundle-->>Notebook: return logits
  Notebook->>RankSEG: decode softmax probabilities
  RankSEG-->>Notebook: return prediction
  Notebook->>Dice Evaluation: compare argmax and RankSEG predictions
  Dice Evaluation-->>Notebook: return Dice scores

Loading

Possibly related issues

• Discussion: optional RankSEG-style decoding support in MONAI post-processing MONAI#8857: Directly covers the RankSEG and RankSEGd integration implemented by this tutorial.

Possibly related PRs

• Project-MONAI/tutorials#2065: Updates the same runner.sh notebook exemption list.

Suggested reviewers: ericspod

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a RankSEG integration tutorial.
Description check	✅ Passed	The description explains the tutorial, implementation scope, checks, execution command, results, and reproducibility details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@modules/rankseg_integration.ipynb`:
- Line 47: Update the dependency-check command in the notebook setup cell to
validate both MONAI and nibabel imports before skipping installation. Ensure any
installation runs through the active kernel interpreter, and retain the existing
MONAI extras including nibabel and tqdm so the later LoadImaged call can read
.nii.gz files.
- Around line 630-653: Update both torch.load calls for the architecture and
checkpoint artifacts in the model-loading flow to use weights_only=True instead
of explicitly enabling full pickle deserialization. Preserve the existing paths
and map_location settings, and only retain weights_only=False if the loaded
files require trusted non-tensor objects.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e68feaab-cd4b-4ade-99e2-419988bdcf7c

📥 Commits

Reviewing files that changed from the base of the PR and between 81dcf0f and 13eed5c.

📒 Files selected for processing (3)

• README.md
• modules/rankseg_integration.ipynb
• runner.sh

[ericspod]

Hi @statmlben thanks for this tutorial as we had discussed. I think it's fine overall for the existing content, but we need a discussion on what Rankseg is and how the algorithm works. At the top you should describe what it is, how it differs from other components, what it's used for, what the implications of using it are, etc. This by no means needs the same details as in your paper but should be motivating enough so readers know what the notebook is demonstrating and whether they'd want to use it themselves or not. I think the Coderabbit comments should be looked at but I had responses here as well.

[statmlben]

Thanks @ericspod for the feedback. I added an introductory section near the top of the notebook explaining what RankSEG is, how it differs from argmax, fixed thresholding, and morphology-based post-processing, and how the RMA workflow operates at a high level. The section also discusses suitable use cases, probability requirements, computational cost, and the need to validate improvements on representative data.

I also addressed your inline suggestions by consolidating the dependency installation command and using the Bundle ConfigParser to construct the model.

[garciadias]

Thanks for this tutorial — I built a GPU Docker container (monai:blackwell, RTX 5090), installed the notebook's declared dependencies exactly as specified, and ran the full ./runner.sh -t modules/rankseg_integration.ipynb end-to-end. It passed cleanly and reproduced the PR description's numbers exactly (Argmax macro Dice 0.7747, RankSEG macro Dice 0.8502, Pancreas 0.8764 -> 0.8898, Tumor 0.6730 -> 0.8106). The RankSEG/RankSEGd transform code, shape handling, and Dice evaluation are all correct.

I left three inline comments. The main one (major) is that the MSD Task07 Pancreas case is downloaded from an unofficial personal Hugging Face account (MedOtter/msd-pancreas) rather than a MONAI-controlled source, unlike every other MSD download in this repo — I've included a concrete alternative (MONAI's own S3 mirror, which supports HTTP range requests) in that comment. The other two are minor (pinning the rankseg dependency, and linking to a fixed commit rather than a moving branch for an external benchmark claim).

[statmlben]

Hi @garciadias , thank you for the detailed review. I addressed all three comments by switching to MONAI's official MSD S3 source with integrity checks, pinning rankseg==0.0.5, and linking the benchmark to a fixed commit.

Thanks again for helping improve the tutorial's provenance and reproducibility

[garciadias]

All three review findings are resolved:

• The MSD Task07 Pancreas case now downloads from MONAI's own official S3 mirror (msd-for-monai.s3-us-west-2.amazonaws.com), pinned to an immutable S3 object version, via HTTP range requests that validate the tar header (name, size, type) and verify a SHA-256 digest of the extracted bytes — a more rigorous fix than what I suggested.
• rankseg is now pinned to ==0.0.5.
• The reproducibility link now points to a fixed commit SHA instead of the main branch.

I re-verified by rebuilding a clean GPU Docker container (monai:blackwell, RTX 5090) against a fresh worktree at the latest commit, installing the notebook's declared dependencies exactly as specified, and running the full ./runner.sh -t modules/rankseg_integration.ipynb end-to-end. It passed and reproduced identical results (Argmax macro Dice 0.7747, RankSEG macro Dice 0.8502, Pancreas 0.8764 -> 0.8898, Tumor 0.6730 -> 0.8106). I also independently confirmed the downloaded image and label files' SHA-256 hashes match the values hardcoded in the notebook. LGTM.

[statmlben]

Thanks @garciadias for the thorough re-review and independent verification, much appreciated!

Hi @ericspod, I’ve addressed the requested changes, including the introductory discussion of RankSEG and the dependency/model-loading updates. @garciadias has also re-run the complete notebook in a clean GPU environment and approved the PR. The remaining Actions checks were cancelled by GitHub infrastructure errors before the repository code was executed (hosted runner not acquired and Service Unavailable while resolving action downloads). Could you please re-review the changes and, if possible, re-run the affected workflows? Thanks!

[garciadias]

Thanks @garciadias for the thorough re-review and independent verification, much appreciated!

Hi @ericspod, I’ve addressed the requested changes, including the introductory discussion of RankSEG and the dependency/model-loading updates. @garciadias has also re-run the complete notebook in a clean GPU environment and approved the PR. The remaining Actions checks were cancelled by GitHub infrastructure errors before the repository code was executed (hosted runner not acquired and Service Unavailable while resolving action downloads). Could you please re-review the changes and, if possible, re-run the affected workflows? Thanks!

Sorry @statmlben, somehow GitHub failed to run some of the CI, and this got stuck for a while. Now that everything is passing, we can just wait for @ericspod to approve and merge.