Skip to content

docs(tutorial 3): document ABMIL fixed-size patch sampling strategy#210

Open
sammargolis wants to merge 1 commit into
mahmoodlab:mainfrom
sammargolis:docs/abmil-training-sampling-explanation
Open

docs(tutorial 3): document ABMIL fixed-size patch sampling strategy#210
sammargolis wants to merge 1 commit into
mahmoodlab:mainfrom
sammargolis:docs/abmil-training-sampling-explanation

Conversation

@sammargolis

Copy link
Copy Markdown

Summary

Closes #115.

This PR adds documentation to Tutorial 3 explaining the intentional design choice of randomly sampling a fixed number of patches per slide during training, while using all patches at validation/test time.

Changes

tutorials/3-Training-a-WSI-Classification-Model-with-ABMIL-and-Heatmaps.ipynb

  • Markdown callout added before the training code block explaining:
    • Why fixed-size random sampling is used during training (regularization, memory efficiency, enables batch_size > 1, patch diversity across epochs)
    • That all patches are used at val/test time for deterministic, reproducible evaluation
    • Warning that this approach must not be used with position-encoding models (e.g. GigaPath)
  • Docstring added to H5Dataset.__init__ documenting the num_features parameter and the train vs. eval behavior
  • Inline comments in the __getitem__ sampling block to make the train/test asymmetry self-evident

Motivation

Issue #115 raised a good question about whether the fixed-size random sampling used during ABMIL training could cause the model to miss important patches. The answer (already explained clearly by @ajv012 in the issue thread) is well-established in the MIL literature but was not surfaced anywhere in the tutorial code. Readers following the tutorial would encounter the sampling logic with no indication that it is intentional, why it is beneficial, or what its limitations are.

Test plan

  • Verify the notebook renders correctly (markdown callout visible, docstring and comments appear in the code cell)
  • Confirm no functional code was changed (only docstring, comments, and a markdown cell were added)

Addresses issue mahmoodlab#115 by explaining why patches are randomly sampled
during training but all patches are used at val/test time. Adds a
callout block in the markdown and a docstring + inline comments to
H5Dataset clarifying the regularization rationale, memory benefits,
and the GigaPath position-encoding caveat.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Question] ABMIL training tricks

1 participant