histolab

Files (8)

• SKILL.md
• core_capabilities.md · references/
• filters_preprocessing.md · references/
• slide_management.md · references/
• tile_extraction.md · references/
• tissue_masks.md · references/
• typical_workflows.md · references/
• visualization.md · references/

SKILL.md (first lines)

# Histolab

## When to use

Use Histolab to inspect WSI metadata, identify tissue, extract image tiles, and
standardize H&E staining. Its masks and scores are image-processing heuristics;
they do not diagnose cancer, count individual cells, or establish image quality.

## Installation

Histolab 0.7.0 remains the latest published release as of the review date. Its
[release constraints](https://github.com/histolab/histolab/blob/v0.7.0/pyproject.toml)
require Python <3.12, NumPy <=1.24.4, scikit-image <0.19.4, SciPy <1.10.1,
Pillow <11, and openslide-python 1.3.1. Keep this stack isolated from modern
scientific environments. Windows is not supported by this Histolab release.

Install [native OpenSlide](https://openslide.org/download/) for your system,
then create a dedicated environment (Python 3.10 was tested):

```bash
uv venv --python 3.10 .venv-histolab
uv pip install --python .venv-histolab/bin/python 'histolab==0.7.0' pooch matplotlib
.venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'
```

On macOS with Homebrew, `brew install openslide` installs the native library.
If the older Python binding cannot find it, launch Python with the library path
set immediately before Python starts:

```bash
env DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix openslide)/lib" .venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'
```

`pooch` is optional for remote examples. Start with a local slide or the tiny
bundled `cmu_small_region` sample; other sample functions may download hundreds
of megabytes. Exact `mpp` extraction also needs `large-image` and a matching
source plugin; see [slide management](references/slide_management.md).

## Workflow

1. Inspect `slide.dimensions`, `slide.levels` (a list), and
   `slide.level_dimensions(level)` (a method). Check both MPP axes in metadata.
2. Select physical field of view and pixel resolution; level numbers are not
   interchangeable across scanners. Preserve level-0 coordinate bounds.
3. Choose `TissueMask` for all tissue sections or `BiggestTissueBoxMask` for the
   largest section's bounding box. Inspect the mask at its actual resolution.
4. Configure a tiler and preview with the **same mask** passed to extraction.
   Preview methods return a Pillow image; save or display that return value.
5. Extract into a distinct per-slide/per-strategy directory. Count saved files,
   inspect representative tiles, and retain parameters, source IDs and QC flags.
6. Split datasets by patient before training/validation/test tile assignment.
   Fit stain normalization targets on training data only and validate on held-out
   scanners. A seed reproduces sampling; it does not prevent patient leakage.

## Quick start

Illustrative for a user-provided slide; the same API path is tested with small
local fixtures. `n_tiles` is an upper bound, not a promise of 100 valid tiles.

```python
from pathlib import Path
from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler

output = Path("output/random_tiles")
output.mkdir(parents=True, exist_ok=True)
slide = Slide("slide.svs", processed_path=output)
mask = TissueMask()
slide.locate_mask(mask).save(output / "mask_preview.png")

tiler = RandomTiler(
    tile_size=(512, 512), n_tiles=100, level=0, seed=42,
    check_tissue=True, tissue_percent=80.0, prefix="random_",
)
tiler.locate_tiles(slide, extraction_mask=mask).save(output / "tile_preview.png")
tiler.extract(slide, extraction_mask=mask)
print("[OK] Saved tiles:", len(list(output.glob("random_tile_*.png"))))
```

`extraction_mask` belongs to `extract()` and `locate_tiles()`, not to the tiler
constructor. `locate_tiles()` has no `n_tiles` argument. Previewing runs tile
selection again, so it may be expensive; use a separate small tiler for initial
exploration, then preview the final configuration before committing a large run.

## Choose a strategy

| Tiler | Selection | Important limitation |
| --- | --- | --- |
| `RandomTiler` | Seeded sampling, at most `n_tiles`, up to `max_iter` attempts | May overlap, repeat, or miss rare structures |
| `GridTiler` | Grid within the extraction mask | Boundary tiles and tissue checks can leave gaps |
| `ScoreTiler` | Scores all eligible grid candidates; saves top `n_tiles` | Lower output count does not avoid scoring all candidates |

For grids, stride in each axis is tile size minus `pixel_overlap`; positive
values must be smaller than both tile dimensions. Negative overlap leaves gaps.
`ScoreTiler(n_tiles=0)` saves all eligible ranked tiles.

Nuclei and cellularity scores estimate stain-derived area fractions. They are
not calibrated tumor probabilities or blur/focus scores. Score reports contain
exactly `filename,score,scaled_score`; record coordinate bounds and physical
resolution separately. Equal raw scores can make `scaled_score` undefined in
0.7.0, so inspect raw scores and finiteness before plotting or comparing them.

## Troubleshooting and scientific checks

- **No/few tiles:** inspect mask and output counts, dimensions, level, and
  `max_iter`. Lowering `tissue_percent` relaxes QC; validate the added tiles.
- **Missing sections:** the default biggest-region box excludes other sections.
  Pass `TissueMask()` explicitly to both preview and extraction.
- **Slow extraction:** benchmark valid coarser levels (larger level numbers).
  Higher tissue thresholds can increase random rejections; ScoreTiler still
  examines the full candidate grid. Avoid assuming lower output count is faster.
- **Mask/thumbnail mismatch:** 0.7.0 selects the larger of the thumbnail and
  1/32-scale image for slide masks. Resize categorical masks with nearest-neighbor
  interpolation when overlaying them; never reinterpret mask pixels as level 0.
- **Normalization artifacts:** inspect target/source tissue coverage and finite
  output. Near-constant or blank tiles can make stain estimates degenerate.
  HED channel scaling alone is not a validated RGB stain normalization method.
- **Across-scale alignment:** the same random seed at different levels does

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills