histolab

Histolab

概要

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

インストール

uv pip install histolab

クイックスタート

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

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)

主な機能

1. スライド管理

さまざまな形式の全スライド画像を読み込み、確認し、操作します。

一般的な操作:

• WSI ファイル（SVS、TIFF、NDPI など）の読み込み
• スライドのメタデータ（サイズ、倍率、プロパティ）へのアクセス
• 可視化のためのサムネイルの生成
• ピラミッド型画像構造の操作
• 特定の座標における領域の抽出

主要クラス: Slide

リファレンス: references/slide_management.md には、次の内容に関する詳細なドキュメントがあります:

• スライドの初期化と設定
• 組み込みのサンプルデータセット（前立腺、卵巣、乳房、心臓、腎臓の組織）
• スライドのプロパティとメタデータへのアクセス
• サムネイルの生成と可視化
• ピラミッドレベルの操作
• 複数スライドの処理ワークフロー

ワークフローの例:

from histolab.slide import Slide
from histolab.data import prostate_tissue

# Load sample data
prostate_svs, prostate_path = prostate_tissue()

# Initialize slide
slide = Slide(prostate_path, processed_path="output/")

# Inspect properties
print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
print(f"Magnification: {slide.properties.get('openslide.objective-power')}")

# Save thumbnail
slide.save_thumbnail()

2. 組織検出とマスク

組織領域を自動的に特定し、背景やアーティファクトを除外します。

一般的な操作:

• バイナリ組織マスクの作成
• 最大の組織領域の検出
• 背景とアーティファクトの除外
• カスタム組織セグメンテーション
• ペンによる注釈の除去

主要クラス: TissueMask、BiggestTissueBoxMask、BinaryMask

リファレンス: references/tissue_masks.md には、次の内容に関する詳細なドキュメントがあります:

• TissueMask: 自動フィルターを使用してすべての組織領域をセグメント化
• BiggestTissueBoxMask: 最大の組織領域のバウンディングボックスを返す（デフォルト）
• BinaryMask: カスタムマスク実装の基底クラス
• locate_mask() によるマスクの可視化
• カスタムの矩形マスクおよび注釈除外マスクの作成
• タイル抽出とのマスクの統合
• ベストプラクティスとトラブルシューティング

ワークフローの例:

from histolab.masks import TissueMask, BiggestTissueBoxMask

# Create tissue mask for all tissue regions
tissue_mask = TissueMask()

# Visualize mask on slide
slide.locate_mask(tissue_mask)

# Get mask array
mask_array = tissue_mask(slide)

# Use largest tissue region (default for most extractors)
biggest_mask = BiggestTissueBoxMask()

各マスクの使い分け:

• TissueMask: 複数の組織切片がある場合、包括的な分析を行う場合
• BiggestTissueBoxMask: 単一の主要な組織切片があり、アーティファクトを除外したい場合（デフォルト）
• カスタム BinaryMask: 特定の関心領域（ROI）を対象とする場合、注釈を除外する場合、独自のセグメンテーションを行う場合

3. タイル抽出

さまざまな戦略を用いて、大きな WSI から小さな領域を抽出します。

3 つの抽出戦略:

RandomTiler: ランダムな位置に配置された固定数のタイルを抽出

• 適している用途: 多様な領域のサンプリング、探索的分析、学習データ
• 主要パラメーター: n_tiles、再現性のための seed

GridTiler: グリッドパターンで組織全体にわたり体系的にタイルを抽出

• 適している用途: 網羅的なカバレッジ、空間解析、再構成
• 主要パラメーター: スライディングウィンドウ用の pixel_overlap

ScoreTiler: スコアリング関数に基づいて上位のタイルを抽出

• 適している用途: 最も有益な領域の選択、品質重視の選択
• 主要パラメーター: scorer（NucleiScorer、CellularityScorer、カスタム）

共通パラメーター:

• tile_size: タイルのサイズ（例: (512, 512)）
• level: 抽出に用いるピラミッドレベル（0 = 最高解像度）
• check_tissue: 組織の含有量に基づいてタイルをフィルタリング
• tissue_percent: 最小組織被覆率（デフォルトは 80%）
• extraction_mask: 抽出領域を定義するマスク

リファレンス: references/tile_extraction.md には、次の内容に関する詳細なドキュメントがあります:

• 各タイラー戦略の詳細な説明
• 利用可能なスコアラー（NucleiScorer、CellularityScorer、カスタム）
• locate_tiles() によるタイルのプレビュー
• 抽出ワークフローとレポート作成
• 高度なパターン（マルチレベル、階層的抽出）
• パフォーマンスの最適化とトラブルシューティング

ワークフローの例:

from histolab.tiler import RandomTiler, GridTiler, ScoreTiler
from histolab.scorer import NucleiScorer

# Random sampling (fast, diverse)
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)
random_tiler.extract(slide)

# Grid coverage (comprehensive)
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=0,
    pixel_overlap=0,
    check_tissue=True
)
grid_tiler.extract(slide)

# Score-based selection (most informative)
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    scorer=NucleiScorer(),
    level=0
)
score_tiler.extract(slide, report_path="tiles_report.csv")

抽出の前に必ずプレビューしてください:

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

4. フィルターと前処理

組織検出、品質管理、前処理のために画像処理フィルターを適用します。

フィルターのカテゴリ:

画像フィルター: 色空間変換、しきい値処理、コントラスト強調

• RgbToGrayscale、RgbToHsv、RgbToHed
• OtsuThreshold、AdaptiveThreshold
• StretchContrast、HistogramEqualization

形態学フィルター: 二値画像に対する構造的操作

• BinaryDilation、BinaryErosion
• BinaryOpening、BinaryClosing
• RemoveSmallObjects、RemoveSmallHoles

合成: 複数のフィルターを連結します

• Compose: フィルターパイプラインを作成します

リファレンス: references/filters_preprocessing.md には、次の内容に関する包括的なドキュメントがあります:

• 各フィルターの種類の詳細な説明
• フィルターの合成と連結
• 一般的な前処理パイプライン（組織検出、ペン除去、核の強調）
• タイルへのフィルターの適用
• カスタムマスクフィルター
• 品質管理フィルター（ぼけ検出、組織被覆率）
• ベストプラクティスとトラブルシューティング

ワークフロー例:

from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallHoles, RemoveSmallObjects
)

# Standard tissue detection pipeline
tissue_detection = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=5),
    RemoveSmallHoles(area_threshold=1000),
    RemoveSmallObjects(area_threshold=500)
])

# Use with custom mask
from histolab.masks import TissueMask
custom_mask = TissueMask(filters=tissue_detection)

# Apply filters to tile
from histolab.tile import Tile
filtered_tile = tile.apply_filters(tissue_detection)

5. 可視化

スライド、マスク、タイルの位置、抽出品質を可視化します。

一般的な可視化タスク:

• スライドのサムネイル表示
• 組織マスクの可視化
• タイルの位置のプレビュー
• タイル品質の評価
• レポートと図の作成

リファレンス: references/visualization.md には、次の内容に関する包括的なドキュメントがあります:

• スライドのサムネイルの表示と保存
• locate_mask() によるマスクの可視化
• locate_tiles() によるタイルの位置のプレビュー
• 抽出されたタイルとモザイクの表示
• 品質評価（スコア分布、上位タイルと下位タイルの比較）
• 複数スライドの可視化
• フィルター効果の可視化
• 高解像度の図と PDF レポートの書き出し
• Jupyter ノートブックでのインタラクティブな可視化

ワークフロー例:

import matplotlib.pyplot as plt
from histolab.masks import TissueMask

# Display slide thumbnail
plt.figure(figsize=(10, 10))
plt.imshow(slide.thumbnail)
plt.title(f"Slide: {slide.name}")
plt.axis('off')
plt.show()

# Visualize tissue mask
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Preview tile locations
tiler = RandomTiler(tile_size=(512, 512), n_tiles=50)
tiler.locate_tiles(slide, n_tiles=20)

# Display extracted tiles in grid
from pathlib import Path
from PIL import Image

tile_paths = list(Path("output/tiles/").glob("*.png"))[:16]
fig, axes = plt.subplots(4, 4, figsize=(12, 12))
axes = axes.ravel()

for idx, tile_path in enumerate(tile_paths):
    tile_img = Image.open(tile_path)
    axes[idx].imshow(tile_img)
    axes[idx].set_title(tile_path.stem, fontsize=8)
    axes[idx].axis('off')

plt.tight_layout()
plt.show()

典型的なワークフロー

ワークフロー 1: 探索的タイル抽出

初期分析のために、組織のさまざまな領域を素早くサンプリングします。

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

# Enable logging for progress tracking
logging.basicConfig(level=logging.INFO)

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

# Inspect slide
print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
slide.save_thumbnail()

# Configure random tiler
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)

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

# Extract tiles
random_tiler.extract(slide)

ワークフロー 2: 包括的なグリッド抽出

スライド全体の解析のために、組織を完全にカバーします。

from histolab.slide import Slide
from histolab.tiler import GridTiler
from histolab.masks import TissueMask

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

# Use TissueMask for all tissue sections
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Configure grid tiler
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=1,  # Use level 1 for faster extraction
    pixel_overlap=0,
    check_tissue=True,
    tissue_percent=70.0
)

# Preview grid
grid_tiler.locate_tiles(slide)

# Extract all tiles
grid_tiler.extract(slide, extraction_mask=tissue_mask)

ワークフロー 3: 品質重視のタイル選択

核の密度に基づいて、最も情報量の多いタイルを抽出します。

from histolab.slide import Slide
from histolab.tiler import ScoreTiler
from histolab.scorer import NucleiScorer
import pandas as pd
import matplotlib.pyplot as plt

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

# Configure score tiler
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    scorer=NucleiScorer(),
    check_tissue=True
)

# Preview top tiles
score_tiler.locate_tiles(slide, n_tiles=15)

# Extract with report
score_tiler.extract(slide, report_path="tiles_report.csv")

# Analyze scores
report_df = pd.read_csv("tiles_report.csv")
plt.hist(report_df['score'], bins=20, edgecolor='black')
plt.xlabel('Tile Score')
plt.ylabel('Frequency')
plt.title('Distribution of Tile Scores')
plt.show()

ワークフロー 4: 複数スライドの処理パイプライン

一貫したパラメーターで、スライドのコレクション全体を処理します。

from pathlib import Path
from histolab.slide import Slide
from histolab.tiler import RandomTiler
import logging

logging.basicConfig(level=logging.INFO)

# Configure tiler once
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    seed=42,
    check_tissue=True
)

# Process all slides
slide_dir = Path("slides/")
output_base = Path("output/")

for slide_path in slide_dir.glob("*.svs"):
    print(f"\nProcessing: {slide_path.name}")

    # Create slide-specific output directory
    output_dir = output_base / slide_path.stem
    output_dir.mkdir(parents=True, exist_ok=True)

    # Load and process slide
    slide = Slide(slide_path, processed_path=output_dir)

    # Save thumbnail for review
    slide.save_thumbnail()

    # Extract tiles
    tiler.extract(slide)

    print(f"Completed: {slide_path.name}")

ワークフロー 5: カスタムの組織検出とフィルタリング

アーティファクト、注釈、または特殊な染色を含むスライドを扱います。

from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler
from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallObjects, RemoveSmallHoles
)

# Define custom filter pipeline for aggressive artifact removal
aggressive_filters = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=10),
    RemoveSmallHoles(area_threshold=5000),
    RemoveSmallObjects(area_threshold=3000)  # Remove larger artifacts
])

# Create custom mask
custom_mask = TissueMask(filters=aggressive_filters)

# Load slide and visualize mask
slide = Slide("slide.svs", processed_path="output/")
slide.locate_mask(custom_mask)

# Extract with custom mask
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100)
tiler.extract(slide, extraction_mask=custom_mask)

ベストプラクティス

スライドの読み込みと確認

1. 処理前に、必ずスライドのプロパティを確認します
2. すばやく視覚的に確認できるよう、サムネイルを保存します
3. ピラミッドのレベルと寸法を確認します
4. サムネイルを使って組織が存在することを確認します

組織検出

1. 抽出の前に locate_mask() でマスクをプレビューします
2. 複数の切片には TissueMask、単一の切片には BiggestTissueBoxMask を使用します
3. 特定の染色（H&E か IHC か）に合わせてフィルターをカスタマイズします
4. ペンによる注釈はカスタムマスクで処理します
5. さまざまなスライドでマスクをテストします

タイル抽出

1. 抽出する前に、必ず locate_tiles() でプレビューします
2. 適切なタイラーを選択します:
   • RandomTiler: サンプリングと探索
   • GridTiler: 完全なカバー
   • ScoreTiler: 品質重視の選択
3. 適切な tissue_percent のしきい値を設定します（通常 70〜90%）
4. RandomTiler では、再現性のためにシードを使用します
5. 解析に適した解像度になるよう、適切なピラミッドレベルで抽出します
6. 大規模なデータセットでは、ロギングを有効にします

パフォーマンス

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

品質管理

1. タイルの品質を検証します（ぼけ、アーティファクト、焦点を確認）
2. ScoreTiler のスコア分布を確認します
3. スコアが高いタイルと低いタイルの両方を確認します
4. 組織の被覆率の統計を監視します
5. 必要に応じて、追加の品質指標で抽出されたタイルをフィルタリングします

一般的な使用例

ディープラーニングモデルの学習

• RandomTiler を使用して、複数のスライドから均衡のとれたデータセットを抽出する
• ScoreTiler と NucleiScorer を使用して、細胞が多い領域に焦点を当てる
• 一貫した解像度（レベル 0 またはレベル 1）で抽出する
• タイルのメタデータを追跡するために CSV レポートを生成する

スライide全体の解析

• 組織全体を網羅するために 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 に同じ seed を使用する
• 前処理フィルターで染色を正規化する
• 染色の品質に応じて 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

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

• 画像フィルター（色変換、しきい値処理、コントラスト）
• 形態学的フィルター（膨張、侵食、オープニング、クロージング）
• フィルターの組み合わせとチェーン
• 一般的な前処理パイプライン
• タイルへのフィルターの適用
• カスタムマスクフィルター
• 品質管理フィルター
• ベストプラクティスとトラブルシューティング

references/visualization.md

包括的な可視化ガイドです:

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

使用パターン: リファレンスファイルには、このメインスキルドキュメントで説明されているワークフローを補足する詳細な情報が含まれています。詳細な実装ガイダンス、トラブルシューティング、または高度な機能が必要な場合は、特定のリファレンスファイルを必要に応じて読み込んでください。