Feat/examples

[kisside]

Summary by CodeRabbit

• Documentation
  • Added a suite of new examples and guides: slide inspection, deterministic tile-grid generation, local tile extraction, stain augmentation, tissue-mask generation, TIFF export from tiles, tensor aggregations, group-aware splitting, and multiple end-to-end pipelines (distributed tiling, annotation-aware datasets, mask-first filtering, leakage-safe splits), plus annotation/overlay-based tile metadata enrichment.
  • Added reference pages for tissue mask generation and model selection splitting.
  • Enhanced GeoJSON parser documentation.
• Chores
  • Updated documentation navigation and landing pages to better surface Examples and Reference content.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6df9834c-4b50-4829-83c4-0168a95e9886

📥 Commits

Reviewing files that changed from the base of the PR and between 3bf00f4 and c928960.

📒 Files selected for processing (2)

• docs/examples/basic-functionalities/tissue-mask-generation.md
• docs/examples/pipelines/mask-first-tile-filtering-pipeline.md

✅ Files skipped from review due to trivial changes (1)

• docs/examples/pipelines/mask-first-tile-filtering-pipeline.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/examples/basic-functionalities/tissue-mask-generation.md

---

📝 Walkthrough

Walkthrough

Adds a comprehensive docs/examples/ section to the ratiopath documentation, including an index page, ten basic-functionality example pages, and four end-to-end pipeline pages. Registers all new pages in mkdocs.yml navigation, adds two API reference stubs (tissue_mask, model_selection/split), updates the docs home page, and expands the GeoJSONParser docstring.

Changes

ratiopath Documentation Examples and Navigation

Layer / File(s)	Summary
Site navigation wiring and home page mkdocs.yml, docs/index.md, docs/examples/index.md	mkdocs.yml adds an Examples submenu under Learn/GET STARTED with all new page links plus tissue_mask and Model Selection reference entries. docs/index.md adds an Examples CTA button and a "How To Use These Docs" section. docs/examples/index.md introduces the examples landing page organizing Basic Functionalities and Pipelines sections.
Basic: slide inspection, metadata, and tile grid docs/examples/basic-functionalities/inspect-slides-and-preview-tiles.md, docs/examples/basic-functionalities/slide-metadata-and-resolution.md, docs/examples/basic-functionalities/tile-grid-generation.md	Example pages covering pyramid level selection with closest_level, reading slide metadata via read_slides, and generating deterministic tile grids with grid_tiles including last-mode boundary strategies.
Basic: local tile extraction and TIFF export docs/examples/basic-functionalities/extract-tiles-locally-without-ray.md, docs/examples/basic-functionalities/write-tiff-outputs-from-ray.md	Example for extracting and saving tiles locally via OpenSlide + grid_tiles (no Ray), and an example for writing per-row TIFFs from a Ray dataset using VipsTiffDatasink.
Basic: tissue mask generation with reference docs/examples/basic-functionalities/tissue-mask-generation.md, docs/reference/masks/tissue_mask.md	Example page for tissue_mask generation with default and custom pyvips filter chains, saving as pyramid TIFF, and reusing the mask as an aligned overlay to compute tissue overlap per tile. Includes API reference stub.
Basic: stain augmentation docs/examples/basic-functionalities/stain-augmentation.md	Example page for H&E-style stain augmentation using StainAugmentor with adaptive and fixed matrix modes.
Basic: tensor aggregations docs/examples/basic-functionalities/tensor-aggregations.md	Example page for computing dataset-wide mean/std over Ray tensor columns using TensorMean and TensorStd with guidance on axis parameter selection and distributed variance combination.
Basic: annotation and overlay enrichment docs/examples/basic-functionalities/annotation-and-overlay-enrichment.md	Example page for enriching tile metadata via tile_annotations (geometry-based coverage), tile_overlay_overlap (raster overlap fractions), and tile_overlay (aligned patch with ROI mask).
Basic: group-aware splitting with reference docs/examples/basic-functionalities/group-aware-splitting.md, docs/reference/model_selection/split.md	Example page for leakage-safe train/test splitting using train_test_split with stratify and groups parameters and StratifiedGroupShuffleSplit. Includes API reference stub.
Pipeline: distributed tiling docs/examples/pipelines/distributed-tiling-pipeline.md	Complete pipeline page describing staged Ray-based tiling workflow: metadata reading → tile grid expansion → repartitioning → lazy pixel reading → filtering → Parquet output.
Pipeline: mask-first tile filtering docs/examples/pipelines/mask-first-tile-filtering-pipeline.md	Complete pipeline page for mask-first filtering workflow: generate tissue-mask overlays, compute per-tile mask overlap, filter by tissue fraction, decode pixels for retained tiles.
Pipeline: annotation-aware dataset docs/examples/pipelines/annotation-aware-dataset-pipeline.md	Complete pipeline page for building annotation-aware tile datasets with per-tile coverage via tile_annotations, including helper functions, coordinate space alignment explanation, and pipeline adaptation guidance.
Pipeline: leakage-safe splits docs/examples/pipelines/prepare-a-training-dataset-with-leakage-safe-splits.md	Complete pipeline page for preparing train/test tile datasets using grouped stratified splits with explanation of why split occurs at slide-table level and useful variants.
GeoJSONParser docstring ratiopath/parsers/geojson_parser.py	Module and constructor docstrings rewritten to document solve_relations join-key–based mapping schema, definition vs annotation feature distinction, and join_key=None behavior. No logic changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• vejtek
• matejpekar
• Adames4
• JakubPekar

Poem

🐇 Hop, hop! The docs have grown so bright,
With tiles and masks and stains just right.
Pipelines flow from slide to split,
Each example page a perfect fit.
No pixel left behind today —
The rabbit tidied all the way! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Feat/examples' is vague and uses a generic naming pattern that doesn't convey meaningful information about the changeset; while it suggests feature additions related to examples, it lacks specificity about the scope or nature of these examples.	Use a more descriptive title that specifies what examples are being added, such as 'Add documentation examples for basic functionalities and pipelines' or similar to clarify the scope and purpose.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/examples

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive set of usage examples and end-to-end pipeline guides to the documentation, covering topics such as slide resolution selection, coordinate generation, tissue masking, stain augmentation, and leakage-safe dataset splitting. It also adds reference stubs for the tissue mask and split APIs and updates the MkDocs navigation. The review feedback highlights two issues in mkdocs.yml: a duplicate entry for Darwin7JSONParser in the Parsers section, and missing navigation entries for the newly added reference files tissue_mask.md and split.md.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[github-actions]

Documentation Preview

Preview URL: https://RationAI.github.io/ratiopath/feat-examples/

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

docs/index.md (1)

9-13: ⚡ Quick win

Rephrase the "How To Use These Docs" bullets to reduce repetition.

All three bullets in lines 11–13 start with "Use [...]", which linters flag as repetitive sentence structure. Consider varying the phrasing or restructuring to improve readability.

Suggested revision:

• Line 11: "Use Examples when you want to solve a concrete problem."
• Line 12: "Visit Installation for environment setup."
• Line 13: "Check the API Reference when you already know which function or class you need."

🤖 Prompt for 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.

In `@docs/index.md` around lines 9 - 13, The "How To Use These Docs" section has
repetitive sentence structure with all three bullets starting with "Use [...]".
Vary the phrasing across the three bullets to improve readability: keep the
first bullet starting with "Use [Examples]", change the second bullet to start
with "Visit" for the Installation link, and change the third bullet to start
with "Check the" for the API Reference link while maintaining the same
informative content for each entry.

ratiopath/parsers/geojson_parser.py (2)

23-46: 💤 Low value

Consider using Markdown tables for better portability.

HTML tables work with mkdocstrings but Markdown tables are more conventional in Python docstrings and render correctly across more tools.

♻️ Example Markdown table format

| Feature    | Geometry                     | Join key                              | Metadata                                          |
|------------|------------------------------|---------------------------------------|---------------------------------------------------|
| Definition | `null`                       | `properties[join_key]` (e.g., `presetID`) | All properties merged into matching annotations |
| Annotation | Spatial geometry (e.g., `Polygon`) | `properties[join_key]` (e.g., `presetID`) | Receives all properties from matching definition |

🤖 Prompt for 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.

In `@ratiopath/parsers/geojson_parser.py` around lines 23 - 46, Replace the HTML
table in the docstring of geojson_parser.py with a Markdown table format for
better portability and consistency with Python documentation conventions. The
table documents Feature types (Definition and Annotation) with their
corresponding Geometry, Join key, and Metadata properties. Convert the HTML
table structure to use Markdown pipe syntax with appropriate column alignment
and formatting, ensuring the content matches the structure and meaning of the
original HTML table while making it more portable across different documentation
tools.

---

52-59: 🏗️ Heavy lift

Add an Examples section to illustrate solve_relations usage.

The solve_relations feature is complex and would benefit from a usage example showing how definition features (null geometry) are merged into annotation features via join_key.

As per coding guidelines: "Use Google-style docstrings with clear Args:, Returns:, Yields:, Raises:, and Examples: sections when relevant."

💡 Example section template

"""Read GeoJSON annotations from a file path or text stream.

Args:
    file_path: GeoJSON file path or readable text stream.
    join_key: Shared property key used to merge geometry-less definition
        features into spatial annotation features. Set to `None` to skip
        relational metadata merging.

Examples:
    Basic usage with relational metadata merging:

    >>> parser = GeoJSONParser("annotations.geojson", join_key="presetID")
    >>> parser.gdf.columns
    Index(['geometry', 'presetID', 'shared_attr', 'shared_attr_def', 'meta'], dtype='object')

    Skip relational merging:

    >>> parser = GeoJSONParser("annotations.geojson", join_key=None)
"""

🤖 Prompt for 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.

In `@ratiopath/parsers/geojson_parser.py` around lines 52 - 59, Add an Examples
section to the docstring of the GeoJSONParser read method (or constructor) in
ratiopath/parsers/geojson_parser.py to illustrate the complex solve_relations
functionality. The Examples section should come after the Args section and
include at least two concrete examples: one demonstrating how to use the
join_key parameter to merge geometry-less definition features into annotation
features by matching on a shared property key, and another showing how to skip
relational metadata merging by setting join_key to None. Each example should
show the instantiation of GeoJSONParser with the relevant parameters and the
resulting behavior or output structure.

Source: Coding guidelines

🤖 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 `@docs/examples/pipelines/mask-first-tile-filtering-pipeline.md`:
- Around line 45-56: The tissue_mask function returns a single pyvips.Image
object, not a tuple, so the unpacking syntax in the generate_mask function is
incorrect. Change the line that calls tissue_mask from unpacking it as `mask, _
= tissue_mask(slide=slide, mpp=(8.0, 8.0))` to assigning it directly as `mask =
tissue_mask(slide=slide, mpp=(8.0, 8.0))` to match the actual return type and
prevent a runtime TypeError.

In `@ratiopath/parsers/geojson_parser.py`:
- Line 37: The documentation at line 37 inaccurately describes the merging
behavior by stating only properties.meta values are merged, when in fact the
implementation merges all properties from definition features into annotations.
Update the description to clarify that all properties from definitions are
merged, with columns unique to definitions added as-is and columns present in
both annotations and definitions receiving a _def suffix on the definition side,
per the _solve_relations logic referenced in the implementation.

---

Nitpick comments:
In `@docs/index.md`:
- Around line 9-13: The "How To Use These Docs" section has repetitive sentence
structure with all three bullets starting with "Use [...]". Vary the phrasing
across the three bullets to improve readability: keep the first bullet starting
with "Use [Examples]", change the second bullet to start with "Visit" for the
Installation link, and change the third bullet to start with "Check the" for the
API Reference link while maintaining the same informative content for each
entry.

In `@ratiopath/parsers/geojson_parser.py`:
- Around line 23-46: Replace the HTML table in the docstring of
geojson_parser.py with a Markdown table format for better portability and
consistency with Python documentation conventions. The table documents Feature
types (Definition and Annotation) with their corresponding Geometry, Join key,
and Metadata properties. Convert the HTML table structure to use Markdown pipe
syntax with appropriate column alignment and formatting, ensuring the content
matches the structure and meaning of the original HTML table while making it
more portable across different documentation tools.
- Around line 52-59: Add an Examples section to the docstring of the
GeoJSONParser read method (or constructor) in
ratiopath/parsers/geojson_parser.py to illustrate the complex solve_relations
functionality. The Examples section should come after the Args section and
include at least two concrete examples: one demonstrating how to use the
join_key parameter to merge geometry-less definition features into annotation
features by matching on a shared property key, and another showing how to skip
relational metadata merging by setting join_key to None. Each example should
show the instantiation of GeoJSONParser with the relevant parameters and the
resulting behavior or output structure.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: a9dcdeae-99ae-4a3e-be88-540c8b2c7d9e

📥 Commits

Reviewing files that changed from the base of the PR and between 49892ab and 3bf00f4.

⛔ Files ignored due to path filters (9)

• docs/assets/examples/distributed-tiling-pipeline.png is excluded by !**/*.png
• docs/assets/examples/ecdp-exported-tiles.png is excluded by !**/*.png
• docs/assets/examples/ecdp-inspect-preview.png is excluded by !**/*.png
• docs/assets/examples/ecdp-stain-augmentation-triptych.png is excluded by !**/*.png
• docs/assets/examples/ecdp-tissue-mask-triptych.png is excluded by !**/*.png
• docs/assets/examples/leakage-safe-splits.png is excluded by !**/*.png
• docs/assets/examples/pyramid-level-selection.png is excluded by !**/*.png
• docs/assets/examples/slide-row-to-tile-rows.png is excluded by !**/*.png
• docs/assets/examples/tile-grid-boundary-strategies.png is excluded by !**/*.png

📒 Files selected for processing (20)

• docs/examples/basic-functionalities/annotation-and-overlay-enrichment.md
• docs/examples/basic-functionalities/extract-tiles-locally-without-ray.md
• docs/examples/basic-functionalities/group-aware-splitting.md
• docs/examples/basic-functionalities/inspect-slides-and-preview-tiles.md
• docs/examples/basic-functionalities/slide-metadata-and-resolution.md
• docs/examples/basic-functionalities/stain-augmentation.md
• docs/examples/basic-functionalities/tensor-aggregations.md
• docs/examples/basic-functionalities/tile-grid-generation.md
• docs/examples/basic-functionalities/tissue-mask-generation.md
• docs/examples/basic-functionalities/write-tiff-outputs-from-ray.md
• docs/examples/index.md
• docs/examples/pipelines/annotation-aware-dataset-pipeline.md
• docs/examples/pipelines/distributed-tiling-pipeline.md
• docs/examples/pipelines/mask-first-tile-filtering-pipeline.md
• docs/examples/pipelines/prepare-a-training-dataset-with-leakage-safe-splits.md
• docs/index.md
• docs/reference/masks/tissue_mask.md
• docs/reference/model_selection/split.md
• mkdocs.yml
• ratiopath/parsers/geojson_parser.py