alterlab-histolab

Histolab

概要

Histolabは、デジタル病理学における全スライド画像（WSI）を処理するためのPythonライブラリです。組織の検出、ギガピクセル画像からの有用なタイルの抽出、ディープラーニングのパイプライン用データセットの準備を自動化します。複数のWSI形式に対応し、高度な組織セグメンテーションを実装するとともに、柔軟なタイル抽出方法を提供します。

このスキルを使用する場合

組織検出、MLトレーニング用のタイルデータセットの構築、H&E染色の処理、病理組織スライドのタイルベースの簡易分析など、軽量なWSIタイルパイプラインにはhistolabを使用してください。高度な空間プロテオミクス、多重イメージング、またはディープラーニングを用いた病理学の包括的なパイプラインには、代わりにalterlab-pathmlを使用してください。

対象外

シナリオ	代わりに使用
エンドツーエンドの計算病理学、核のセグメンテーション、多重イメージング（CODEX/Vectra）	alterlab-pathml
抽出したタイルを使った下流分類器のトレーニング	alterlab-pytorch-lightning
SVS/NDPIではなく、DICOM全スライド画像または放射線画像を扱う場合	alterlab-pydicom、alterlab-imaging-data-commons
組織切片の空間トランスクリプトミクス	alterlab-squidpy-spatial
スライドコレクション自体の管理／バージョン管理	alterlab-omero、alterlab-lamindb

インストール

# histolab 0.7.0 needs Python >= 3.8, < 3.12 and numpy 1.x — give it its own env
uv venv --python 3.11 .venv-histolab
uv pip install --python .venv-histolab "histolab==0.7.0" openslide-bin

2026年のツールチェーンでは、次の2つの制約に注意してください。

1. 科学技術スタックのバージョン固定。 0.7.0（2024年2月公開で、現在も最新リリース）では、numpy <= 1.24.4、scipy < 1.10.1、scikit-image < 0.19.4、openslide-python 1.3.1が必要です。numpy 2.xやPython 3.12以降を使うプロジェクトと同じ環境にはできません。バージョン固定を緩めるのではなく、別のvenvを使用してください。
2. OpenSlideはCライブラリであり、wheelには同梱されていません。最も簡単な解決方法はopenslide-bin wheel（ビルド済みバイナリ）を使うことです。それ以外の場合、macOSではbrew install openslide、Debian/Ubuntuではapt install libopenslide0を実行します。これがないと、import histolab.slideがCouldn't locate OpenSlide dylibで失敗します。

以下の例はhistolab 0.7.0を対象としています。古いリリースではAPIが異なります。

コアワークフロー

1. Slide(path, processed_path=...)でスライドを読み込み、寸法とレベルを確認します。
2. マスク（TissueMaskまたはBiggestTissueBoxMask）を使って組織を検出します。
3. 実行前にtiler.locate_tiles(slide)でタイルの位置をプレビューします。
4. 3種類のタイラー（Random/Grid/Score）のいずれかを使ってタイルを抽出します。

最小限の例：

from histolab.slide import Slide
from histolab.tiler import RandomTiler

slide = Slide("slide.svs", processed_path="output/")
# n_tiles, level, seed are CONSTRUCTOR args — not args to locate_tiles/extract.
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100, level=0, seed=42)
tiler.locate_tiles(slide)   # preview locations on the thumbnail first
tiler.extract(slide)        # writes PNGs into processed_path

APIに関する注意点（histolab 0.7.0）： locate_tiles()とextract()が受け取るのはslide、省略可能なextraction_mask、およびログ／スタイル関連のキーワード引数のみで、n_tilesは受け取りません。n_tiles（およびseed、level、tile_size、check_tissue、tissue_percent）はタイラーのコンストラクターに設定してください。extraction_maskはコンストラクターではなく、extract()／locate_tiles()に渡します。

すぐに実行できるパイプライン（クイックスタート、エンドツーエンドのワークフロー5種類、機能別の例）はreferences/workflows.mdにあります。

主な機能

1. スライド管理

WSIファイル（SVS、TIFF、NDPIなど）を読み込み、確認、操作できます。メタデータ（寸法、倍率、プロパティ）へのアクセス、サムネイルの生成、ピラミッド／マルチレベル構造の操作が可能です。主なクラス：Slide。

スライドの初期化、組み込みのサンプルデータセット（prostate_tissue、ovarian_tissue、breast_tissue、heart_tissue、aorta_tissueに加え、ペンで印を付けたサンプルやIHCサンプル）、ピラミッドレベル、複数スライドの処理については、references/slide_management.mdを参照してください。

2. 組織の検出とマスク

組織領域を自動的に特定し、背景やアーティファクトを除外します。主な クラスは、TissueMask（すべての組織領域）、BiggestTissueBoxMask（最大領域の バウンディングボックス。デフォルト）、BinaryMask（カスタムマスクの基底クラス）です。

マスクの選び方：

• TissueMask：複数の組織切片、包括的な解析
• BiggestTissueBoxMask：単一の主要な切片、アーティファクトを除外（デフォルト）
• カスタム BinaryMask：特定の ROI、注釈の除外、カスタムセグメンテーション

検出フィルターの仕組み、locate_mask() を使ったマスクの可視化、 カスタムの矩形マスク／注釈除外マスクについては、references/tissue_masks.md を 参照してください。

3. タイルの抽出

次の 3 つの方法のいずれかを使って、大きな WSI から小さな領域を抽出します。

• RandomTiler — ランダムな位置に配置した固定数のタイルです。多様な領域のサンプリング、 探索、学習データに適しています。主なパラメーター：n_tiles、seed。
• GridTiler — 組織全体にわたる規則的なグリッドです。完全なカバレッジ、 空間解析、再構成に適しています。主なパラメーター：pixel_overlap。
• ScoreTiler — スコアリング関数で順位付けされた上位タイルです。有用な 領域の選択や、品質を重視した選択に適しています。主なパラメーター：scorer（NucleiScorer、 CellularityScorer、カスタム）。

共通パラメーター：tile_size、level（0 = 最高解像度）、check_tissue、 tissue_percent（デフォルト 80%）、extraction_mask。抽出前に必ず locate_tiles() でプレビューしてください。

スコアラー、レポート、応用的な抽出パターン（マルチレベル、階層型）については、 references/tile_extraction.md を参照してください。

4. フィルターと前処理

組織検出、QC、前処理に画像処理フィルターを適用します。

• 画像フィルター — RgbToGrayscale、RgbToHsv、RgbToHed、OtsuThreshold、 Invert、StretchContrast、HistogramEqualization、Lambda。
• 形態学的フィルター — BinaryDilation、BinaryErosion、BinaryOpening、 BinaryClosing、RemoveSmallObjects、RemoveSmallHoles。
• 合成 — Compose（histolab.filters.image_filters 内）でフィルターを パイプラインに連結します。カスタムフィルターを位置引数の可変長引数としてマスクに渡します： TissueMask(RgbToGrayscale(), OtsuThreshold(), ...)。

フィルターの連結、一般的なパイプライン（組織検出、ペンの除去、核の強調）、QC フィルターについては、 references/filters_preprocessing.md を参照してください。

5. 可視化

スライド、マスク、タイルの位置、抽出品質を表示します。サムネイル、locate_mask() による マスクのオーバーレイ、locate_tiles() によるタイル位置のプレビュー、タイルの モザイク、スコア分布などがあります。

モザイク、品質評価プロット、複数スライドの比較、高解像度図／PDF レポートの エクスポートについては、references/visualization.md を参照してください。

リファレンス一覧

• references/workflows.md — クイックスタート、機能ごとの例、エンドツーエンドで実行する 5 つのワークフロー（探索、グリッド、スコア駆動、複数スライド、カスタム組織検出）。
• references/slide_management.md — スライドの読み込み／検査、サンプルデータセット、 ピラミッドレベル、複数スライドの処理。
• references/tissue_masks.md — TissueMask／BiggestTissueBoxMask／BinaryMask、 カスタムマスク、マスクの可視化と統合。
• references/tile_extraction.md — Random／Grid／Score の各タイル抽出器の比較、スコアラー、 CSV レポート、応用的な抽出パターン。
• references/filters_preprocessing.md — 画像フィルターと形態学的フィルター、フィルターの 合成、前処理パイプライン、QC フィルター。
• references/visualization.md — サムネイル、マスク／タイルのプレビュー、モザイク、 品質プロット、図のエクスポート。
• references/best_practices.md — ベストプラクティス、一般的なユースケース、トラブルシューティング （タイルが見つからない、背景のタイル、抽出が遅い、アーティファクト）。

実装の詳しい手順、トラブルシューティング、応用機能については、必要なリファレンスファイルを読み込んでください。

AlterLab Academic Skills スイートの一部です。