megatile_extraction

WSI Mega-Tile Extraction Module. This module provides the MegaTileExtractor class, which groups individual tile positions from a Whole Slide Image into mega tiles — fixed- size grids of rows × cols tiles. It builds on the tile-level tissue filtering from TileExtractor and adds a second filtering stage: only mega tiles where the fraction of tissue-positive tiles falls within a configurable [min_valid_tiles_ratio, max_valid_tiles_ratio] band are kept. The class follows the same scikit-learn–style lifecycle as TileExtractor:

Configure — instantiate with a MegaTileSpec, optional tissue mask, and threshold.
Fit — call fit with an open WSIReader.
Extract — call extract (or the shortcut fit_extract). Results are stored in megatile_regions_ and also returned.
Export — call to_csv or to_json to persist the results.

Usage:

>>> from bioptimus.extraction.wsi.megatile_extraction import MegaTileExtractor
>>> from bioptimus.extraction.wsi.types import MegaTileSpec, TileSpec, GridLayout
>>> from bioptimus.io.wsi.types import Level, MeasurementUnit
>>> tile = TileSpec(
...     size=(256, 256), stride=(256, 256),
...     resolution=Level(0), unit=MeasurementUnit.PIXELS,
... )
>>> mega = MegaTileSpec(
...     megatile_shape=(5, 5), tile_spec=tile,
...     grid_layout=GridLayout.RECTANGULAR,
...     min_valid_tiles_ratio=0.5,
... )
>>> extractor = MegaTileExtractor(
...     megatile_spec=mega,
...     mask=tissue_mask, mask_threshold=0.5,
... )
>>> with SomeWSIReader("path/to/slide.svs") as reader:
...     megatiles = extractor.fit_extract(reader)
...     extractor.to_csv("output/")
...     extractor.to_json("output/")

MegaTileExtractor

class MegaTileExtractor(WSIExtractor)

Extracts mega tiles (grids of tiles) from a WSI, filtered by tissue. A mega tile is a rectangular or hexagonal grid of individual tiles. Extraction proceeds in two stages:

Tile-level filtering — a binary tissue mask and mask_threshold determine which individual tile positions contain sufficient tissue.
Mega-tile-level filtering — only mega tiles where the fraction of valid (tissue-positive) tiles falls within [min_valid_tiles_ratio, max_valid_tiles_ratio] are retained.

The extractor follows the same lifecycle as TileExtractor:

extractor = MegaTileExtractor(megatile_spec=spec, mask=mask)
extractor.fit(reader)
megatiles = extractor.extract()
extractor.to_csv("output/")

Or via method chaining:

megatiles = MegaTileExtractor(megatile_spec=spec).fit_extract(reader)

Configuration attributes (set at init):

MegaTileSpec

Mega-tile grid shape, per-tile spec, layout, stride, and valid-ratio bounds.

np.ndarray | None

Binary tissue mask.

TissueMaskProvider | None

Per-slide mask generator.

float | None

Per-tile tissue fraction threshold.

bool

Whether to store per-tile masks.

int | None

Optional cap on returned mega tiles. Fitted attributes (populated by fit / extract):

WSIReader

Bound WSI reader.

str

Stem of the slide filename.

List[MegaTileRegion]

Extracted mega tiles.

fit

def fit(source: WSIReader) -> "MegaTileExtractor"

Binds the extractor to an open WSI reader. Stores the reader and slide name. If a mask_provider is set, its generate method is called to create a per-slide tissue mask.

WSIReader

required

An open WSI reader.

MegaTileExtractor

self for method chaining.

Example:

>>> extractor.fit(reader)
>>> extractor.slide_name_
'slide_001'

extract

def extract(source: Optional[WSIReader] = None) -> List[MegaTileRegion]

Extracts mega-tile regions from a WSI. The method operates in five stages:

Reference-level setup — as in TileExtractor.
Mask scaling — resize tissue mask to the reference level.
Tile-spec scaling — convert tile dimensions to reference-level pixels.
Per-tile tissue evaluation — build an integral image and compute the tissue fraction for every candidate tile position.
Mega-tile grouping — slide a rows × cols window (in tile units) across the tile grid, collect per-tile validity, and filter by [min_valid_tiles_ratio, max_valid_tiles_ratio].

Results are stored in megatile_regions_ and returned.

WSIReader | None

An open WSI reader. When given, the extractor is fitted automatically. Otherwise fit must have been called.

List[MegaTileRegion]

Mega-tile regions that pass filtering.

Raises:

RuntimeError — If no source is provided and fit has not been called.

Example:

>>> megatiles = extractor.fit(reader).extract()
>>> len(megatiles)
12

fit_extract

def fit_extract(source: WSIReader) -> List[MegaTileRegion]

Convenience method: fit + extract in one call.

WSIReader

required

An open WSI reader.

List[MegaTileRegion]

Extracted mega-tile regions.

Example:

>>> megatiles = extractor.fit_extract(reader)
>>> len(megatiles)
12

to_csv

def to_csv(output_dir: Union[str, Path],
           regions: Optional[List[MegaTileRegion]] = None) -> Path

Saves mega-tile metadata to a CSV file named after the slide. Each row represents one tile within a mega tile. Mega-tile–level columns (megatile_index, megatile_top, etc.) allow grouping.

str | Path

required

Destination directory (created if needed).

List[MegaTileRegion] | None

Override the stored regions. Defaults to megatile_regions_.

Path

Path of the written CSV file.

Raises:

RuntimeError — If no regions are available.

Example:

>>> extractor.fit_extract(reader)
>>> extractor.to_csv("output/")
PosixPath('output/slide_001.csv')

to_json

def to_json(output_dir: Union[str, Path],
            regions: Optional[List[MegaTileRegion]] = None,
            indent: int = 2) -> Path

Saves mega-tile metadata to a JSON file named after the slide. The output is a JSON array of mega-tile objects, each containing the mega-tile location, grid info, valid ratio, and a nested tiles array with per-tile metadata.

str | Path

required

Destination directory (created if needed).

List[MegaTileRegion] | None

Override the stored regions.

int

JSON pretty-printing indent.

Path

Path of the written JSON file.

Raises:

RuntimeError — If no regions are available.

Example:

>>> extractor.fit_extract(reader)
>>> extractor.to_json("output/")
PosixPath('output/slide_001_megatiles.json')

Overview

Get Started

Preprocessing

Workflows

Reference

MegaTileExtractor

fit

extract

fit_extract

to_csv

to_json

​MegaTileExtractor

​fit

​extract

​fit_extract

​to_csv

​to_json

MegaTileExtractor

fit

extract

fit_extract

to_csv

to_json