histolab

Histolab

Overview

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

Installation

最初に OpenSlide のシステムライブラリをインストールし（OpenSlide のダウンロード）、次に histolab をインストールします。

uv pip install histolab

histolab.data を使って組み込みの TCGA サンプルスライドを利用する場合は、pooch もインストールします。

uv pip install pooch

Histolab 0.7.0（最新の安定版）は、Linux と macOS で Python 3.8～3.11 をサポートしています。0.7.0 時点では Windows はサポートされていません。

Quick Start

全スライド画像からタイルを抽出する基本的なワークフローです。

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

# Load slide
slide = Slide("slide.svs", processed_path="output/")

# Configure tiler
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42
)

# Preview tile locations
tiler.locate_tiles(slide, n_tiles=20)

# Extract tiles
tiler.extract(slide)

Core Capabilities

6 つの機能分野について、実行可能なコード例を含む詳細を references/core_capabilities.md に記載しています。

1. スライド管理 — スライドの読み込み、プロパティ、レベル、サムネイル、縮小画像。
2. 組織の検出とマスク — TissueMask、BiggestTissueBoxMask、およびカスタムマスク。
3. タイル抽出 — サイズ、レベル、組織の割合を制御できる、ランダム、グリッド、スコアベースのタイル抽出器。
4. フィルターと前処理 — 画像フィルターや形態学的フィルター、およびそれらの組み合わせ。
5. 染色の正規化 — ターゲット画像を基準とする Reinhard および Macenko の正規化。
6. 可視化 — スライド上のタイルの位置特定、マスクと抽出結果の確認。

エンドツーエンドのワークフローを 5 つ、 references/typical_workflows.md に記載しています。トピックごとの詳細は、 references/slide_management.md、 references/tissue_masks.md、 references/tile_extraction.md、 references/filters_preprocessing.md、 references/visualization.md にあります。

Best Practices

Slide Loading and Inspection

1. 処理を始める前に、必ずスライドのプロパティを確認します。
2. 素早く目視確認できるように、slide.thumbnail.save() でサムネイルを保存します。
3. ピラミッドのレベルと寸法を確認します。
4. サムネイルを使って、組織が含まれていることを確認します。

Tissue Detection

1. 抽出前に locate_mask() でマスクをプレビューします。
2. 複数の組織領域には TissueMask、単一の組織領域には BiggestTissueBoxMask を使います。
3. 特定の染色（H&E と IHC など）に合わせてフィルターをカスタマイズします。
4. カスタムマスクを使って、ペンによる注釈に対処します。
5. 多様なスライドを使ってマスクをテストします。

Tile Extraction

1. 抽出前に必ず locate_tiles() でプレビューします。
2. 適切なタイル抽出器を選択します。
   • RandomTiler：サンプリングと探索
   • GridTiler：全領域の網羅
   • ScoreTiler：品質に基づく選択
3. 適切な tissue_percent のしきい値を設定します（通常は 70～90%）。
4. RandomTiler では、再現性を確保するためにシードを使用します。
5. 分析に必要な解像度に応じて、適切なピラミッドレベルで抽出します。
6. 大規模なデータセットではログ記録を有効にします。

Performance

1. より高速に処理するには、低いレベル（1、2）で抽出します。
2. 適切な場合は、TissueMask より BiggestTissueBoxMask を使用します。
3. tissue_percent を調整して、無効なタイルの試行を減らします。
4. 初期の探索では n_tiles を制限します。
5. 重複しないグリッドには pixel_overlap=0 を使用します。

Quality Control

1. タイルの品質を検証します（ぼやけ、アーティファクト、焦点を確認）。
2. ScoreTiler のスコア分布を確認します。
3. スコアが最も高いタイルと最も低いタイルを確認します。
4. 組織のカバレッジ統計を監視します。
5. 必要に応じて、追加の品質指標を使って抽出済みタイルをフィルタリングします。

Common Use Cases

Training Deep Learning Models

• 複数のスライドで RandomTiler を使い、バランスの取れたデータセットを抽出します。
• NucleiScorer と ScoreTiler を使い、細胞の多い領域に重点を置きます。
• 一貫した解像度（レベル 0 またはレベル 1）で抽出します。
• タイルのメタデータを追跡するために CSV レポートを生成します。

全スライド解析

• GridTilerを使用して組織全体を網羅します
• 階層的な解析のために、複数のピラミッドレベルで抽出します
• グリッド位置を使って空間的な関係を維持します
• スライディングウィンドウ方式では pixel_overlap を使用します

組織の特性評価

• RandomTilerで多様な領域をサンプリングします
• マスクで組織の被覆率を定量化します
• HED分解で染色に固有の情報を抽出します
• スライド間で組織パターンを比較します

品質評価

• ScoreTilerで最適な焦点領域を特定します
• カスタムマスクとフィルターを使ってアーティファクトを検出します
• スライドコレクション全体の染色品質を評価します
• 問題のあるスライドにフラグを付け、手動レビューの対象にします

データセットのキュレーション

• ScoreTilerで情報量の多いタイルを優先します
• 組織の割合でタイルをフィルタリングします
• タイルスコアとメタデータを含むレポートを生成します
• スライドと組織タイプにわたる層化データセットを作成します

トラブルシューティング

タイルが抽出されない

• tissue_percent のしきい値を下げます
• スライドに組織が含まれていることを確認します（サムネイルを確認してください）
• extraction_maskが組織領域を捉えていることを確認します
• tile_sizeがスライドの解像度に適していることを確認します

背景タイルが多い

• check_tissue=True を有効にします
• tissue_percent のしきい値を上げます
• 適切なマスク（TissueMaskとBiggestTissueBoxMask）を使用します
• 組織をより適切に検出できるよう、マスクフィルターをカスタマイズします

抽出が非常に遅い

• より低いピラミッドレベル（level=1または2）で抽出します
• RandomTiler/ScoreTilerの n_tiles を減らします
• サンプリングにはGridTilerではなくRandomTilerを使用します
• TissueMaskではなくBiggestTissueBoxMaskを使用します

タイルにアーティファクトがある

• アノテーション除外用のカスタムマスクを実装します
• アーティファクト除去用にフィルターパラメーターを調整します
• 小さなオブジェクトを除去するしきい値を上げます
• 抽出後に品質フィルタリングを適用します

スライド間で結果に一貫性がない

• RandomTilerに同じシードを使用します
• MacenkoStainNormalizer または ReinhardStainNormalizer で染色を正規化します
• 染色品質に応じて tissue_percent を調整します
• スライドごとにマスクをカスタマイズします

リソース

このスキルには、references/ ディレクトリに詳細なリファレンスドキュメントが含まれています。

references/slide_management.md

全スライド画像の読み込み、確認、操作に関する包括的なガイド：

• スライドの初期化と設定
• 組み込みのサンプルデータセット
• スライドのプロパティとメタデータ
• サムネイルの生成と可視化
• ピラミッドレベルの操作
• 複数スライドの処理ワークフロー
• ベストプラクティスと一般的なパターン

references/tissue_masks.md

組織の検出とマスキングに関する完全なドキュメント：

• TissueMask、BiggestTissueBoxMask、BinaryMaskの各クラス
• 組織検出フィルターの仕組み
• フィルターチェーンを使ったマスクのカスタマイズ
• マスクの可視化
• カスタムの矩形マスクとアノテーション除外マスクの作成
• タイル抽出との統合
• ベストプラクティスとトラブルシューティング

references/tile_extraction.md

タイル抽出戦略の詳細な解説：

• RandomTiler、GridTiler、ScoreTilerの比較
• 利用可能なスコアラー（NucleiScorer、CellularityScorer、カスタムスコアラー）
• 共通パラメーターと戦略固有のパラメーター
• locate_tiles()を使ったタイルのプレビュー
• 抽出ワークフローとCSVレポート
• 高度なパターン（マルチレベル、階層型）
• パフォーマンスの最適化
• よくある問題のトラブルシューティング

references/filters_preprocessing.md

フィルターの完全なリファレンスと前処理ガイド：

• 画像フィルター（色変換、しきい値処理、コントラスト）
• 形態学的フィルター（膨張、収縮、オープニング、クロージング）
• フィルターの合成と連結
• 組み込みの染色正規化（Macenko、Reinhard）とフィルターを使った代替手法
• 一般的な前処理パイプライン
• タイルへのフィルターの適用
• カスタムマスクフィルター
• 品質管理フィルター
• ベストプラクティスとトラブルシューティング

references/visualization.md

包括的な可視化ガイド：

• スライドのサムネイル表示と保存
• マスクの可視化手法
• タイル位置のプレビュー
• 抽出したタイルの表示とモザイクの作成
• 品質評価の可視化
• 複数スライドの比較
• フィルター効果の可視化
• 高解像度の図と PDF のエクスポート
• Jupyter ノートブックでのインタラクティブな可視化

使用パターン： 参照ファイルには、このメインスキル文書で説明されているワークフローを支援する詳細情報が含まれています。実装の詳細、トラブルシューティング、高度な機能について詳しく知る必要がある場合は、該当する参照ファイルを読み込んでください。

エージェントの作業手順

1. 環境を確認します。 データへのアクセス権限、匿名化の状況、適用される規制やプロトコルを確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、ユーザーに尋ねてください。
3. まず小規模に実行します。 匿名化されたサンプルデータまたは合成データを使って作業します。
4. 上記の指示と参照資料を使って、タスク全体を実行します。
5. 結果を検証します。 出力を臨床ガイドラインと報告基準に照らして確認し、臨床内容を有資格者にレビューしてもらいます。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

こうした場合	次のように対応します
データに患者を特定できる情報が含まれているように見える	処理を中断し、続行する前にユーザーに確認します。
これらの指示にある関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに尋ねるか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計情報を決して捏造しないでください。実行または検証できない場合は、率直に伝えてください。
• 出力は有資格者の意思決定を支援するものであり、医療上の助言ではありません。診断や指示として提示しないでください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭が発生する操作、共有 GPU やクラウドの割り当てを消費する操作、個人情報や患者データに触れる操作、元に戻せない操作を行う前に、ユーザーに確認してください。

関連スキル

• pathml：PathML 3.0.5 を使ったローカル限定の研究用計算病理学。全スライド画像の読み込みとタイル分割（OpenSlide、Bio-Formats）、前処理…
• scientific-slides：研究発表用のスライドデッキとプレゼンテーションを作成します。
• segment-anything-model：ゼロショット転移に対応する画像セグメンテーションの基盤モデル。