histolab

Par mkurman · zorai

Extraction et prétraitement légers de tuiles WSI. À utiliser pour le traitement de base des lames : détection du tissu, extraction de tuiles, normalisation de la coloration pour les images H&E. Idéal pour les pipelines simples, la préparation de jeux de données et l'analyse rapide par tuiles. Pour la protéomique spatiale avancée, l'imagerie multiplexée ou les pipelines de deep learning, utilisez pathml.

npx skills add https://github.com/mkurman/zorai --skill histolab

Histolab

Aperçu

Histolab est une bibliothèque Python pour traiter les images de lames entières (WSI) en pathologie numérique. Elle automatise la détection des tissus, extrait des tuiles informatives à partir d'images gigapixel et prépare les ensembles de données pour les pipelines d'apprentissage profond. La bibliothèque gère plusieurs formats WSI, implémente une segmentation tissulaire sophistiquée et fournit des stratégies d'extraction de tuiles flexibles.

Installation

uv pip install histolab

Démarrage rapide

Flux de travail de base pour extraire des tuiles à partir d'une image de lame entière :

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

# Charger la lame
slide = Slide("slide.svs", processed_path="output/")

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

# Aperçu des emplacements de tuiles
tiler.locate_tiles(slide, n_tiles=20)

# Extraire les tuiles
tiler.extract(slide)

Capacités principales

1. Gestion des lames

Charger, inspecter et travailler avec des images de lames entières dans divers formats.

Opérations courantes :

  • Chargement de fichiers WSI (SVS, TIFF, NDPI, etc.)
  • Accès aux métadonnées de la lame (dimensions, grossissement, propriétés)
  • Génération de vignettes pour la visualisation
  • Travail avec des structures d'images pyramidales
  • Extraction de régions à des coordonnées spécifiques

Classes principales : Slide

Référence : references/slide_management.md contient une documentation complète sur :

  • Initialisation et configuration des lames
  • Ensembles de données d'exemple intégrés (tissus prostatique, ovarien, mammaire, cardiaque, rénal)
  • Accès aux propriétés et métadonnées des lames
  • Génération et visualisation de vignettes
  • Travail avec les niveaux pyramidaux
  • Flux de traitement multi-lames

Flux de travail exemple :

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

# Charger les données d'exemple
prostate_svs, prostate_path = prostate_tissue()

# Initialiser la lame
slide = Slide(prostate_path, processed_path="output/")

# Inspecter les propriétés
print(f"Dimensions: {slide.dimensions}")
print(f"Niveaux: {slide.levels}")
print(f"Grossissement: {slide.properties.get('openslide.objective-power')}")

# Enregistrer la vignette
slide.save_thumbnail()

2. Détection des tissus et masques

Identifier automatiquement les régions tissulaires et filtrer le fond/les artefacts.

Opérations courantes :

  • Création de masques tissulaires binaires
  • Détection de la plus grande région tissulaire
  • Exclusion du fond et des artefacts
  • Segmentation tissulaire personnalisée
  • Suppression des annotations au stylo

Classes principales : TissueMask, BiggestTissueBoxMask, BinaryMask

Référence : references/tissue_masks.md contient une documentation complète sur :

  • TissueMask : Segmente toutes les régions tissulaires en utilisant des filtres automatisés
  • BiggestTissueBoxMask : Retourne le rectangle englobant de la plus grande région tissulaire (par défaut)
  • BinaryMask : Classe de base pour les implémentations de masque personnalisé
  • Visualisation des masques avec locate_mask()
  • Création de masques rectangulaires personnalisés et d'exclusion d'annotations
  • Intégration des masques avec l'extraction de tuiles
  • Bonnes pratiques et dépannage

Flux de travail exemple :

from histolab.masks import TissueMask, BiggestTissueBoxMask

# Créer un masque tissulaire pour toutes les régions tissulaires
tissue_mask = TissueMask()

# Visualiser le masque sur la lame
slide.locate_mask(tissue_mask)

# Obtenir le tableau de masque
mask_array = tissue_mask(slide)

# Utiliser la plus grande région tissulaire (par défaut pour la plupart des extracteurs)
biggest_mask = BiggestTissueBoxMask()

Quand utiliser chaque masque :

  • TissueMask : Sections tissulaires multiples, analyse complète
  • BiggestTissueBoxMask : Principale section tissulaire unique, exclure les artefacts (par défaut)
  • BinaryMask personnalisé : ROI spécifique, exclure les annotations, segmentation personnalisée

3. Extraction de tuiles

Extraire des régions plus petites à partir de grandes WSI en utilisant différentes stratégies.

Trois stratégies d'extraction :

RandomTiler : Extraire un nombre fixe de tuiles positionnées aléatoirement

  • Optimal pour : Échantillonnage de régions diversifiées, analyse exploratoire, données d'entraînement
  • Paramètres clés : n_tiles, seed pour la reproductibilité

GridTiler : Extraire systématiquement les tuiles à travers le tissu selon un motif en grille

  • Optimal pour : Couverture complète, analyse spatiale, reconstruction
  • Paramètres clés : pixel_overlap pour les fenêtres glissantes

ScoreTiler : Extraire les tuiles les mieux classées en fonction de fonctions de notation

  • Optimal pour : Régions les plus informatives, sélection axée sur la qualité
  • Paramètres clés : scorer (NucleiScorer, CellularityScorer, personnalisé)

Paramètres courants :

  • tile_size : Dimensions de tuile (p. ex., (512, 512))
  • level : Niveau pyramidal pour l'extraction (0 = résolution la plus élevée)
  • check_tissue : Filtrer les tuiles par contenu tissulaire
  • tissue_percent : Couverture tissulaire minimale (par défaut 80%)
  • extraction_mask : Masque définissant la région d'extraction

Référence : references/tile_extraction.md contient une documentation complète sur :

  • Explication détaillée de chaque stratégie de tiler
  • Notateurs disponibles (NucleiScorer, CellularityScorer, personnalisé)
  • Aperçu des tuiles avec locate_tiles()
  • Flux de travail d'extraction et rapports
  • Motifs avancés (extraction multi-niveaux, hiérarchique)
  • Optimisation des performances et dépannage

Flux de travail exemples :

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

# Échantillonnage aléatoire (rapide, diversifié)
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)

# Couverture en grille (complète)
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=0,
    pixel_overlap=0,
    check_tissue=True
)
grid_tiler.extract(slide)

# Sélection basée sur la notation (la plus informative)
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    scorer=NucleiScorer(),
    level=0
)
score_tiler.extract(slide, report_path="tiles_report.csv")

Toujours prévisualiser avant extraction :

# Aperçu des emplacements de tuiles sur la vignette
tiler.locate_tiles(slide, n_tiles=20)

4. Filtres et prétraitement

Appliquer des filtres de traitement d'images pour la détection tissulaire, le contrôle de qualité et le prétraitement.

Catégories de filtres :

Filtres d'image : Conversions d'espace colorimétrique, seuillage, amélioration du contraste

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

Filtres morphologiques : Opérations structurelles sur images binaires

  • BinaryDilation, BinaryErosion
  • BinaryOpening, BinaryClosing
  • RemoveSmallObjects, RemoveSmallHoles

Composition : Enchaîner plusieurs filtres

  • Compose : Créer des pipelines de filtres

Référence : references/filters_preprocessing.md contient une documentation complète sur :

  • Explication détaillée de chaque type de filtre
  • Composition et enchaînement de filtres
  • Pipelines de prétraitement courants (détection tissulaire, suppression de stylo, amélioration de noyaux)
  • Application de filtres aux tuiles
  • Filtres de masque personnalisés
  • Filtres de contrôle de qualité (détection de flou, couverture tissulaire)
  • Bonnes pratiques et dépannage

Flux de travail exemples :

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

# Pipeline standard de détection tissulaire
tissue_detection = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=5),
    RemoveSmallHoles(area_threshold=1000),
    RemoveSmallObjects(area_threshold=500)
])

# Utiliser avec un masque personnalisé
from histolab.masks import TissueMask
custom_mask = TissueMask(filters=tissue_detection)

# Appliquer les filtres à la tuile
from histolab.tile import Tile
filtered_tile = tile.apply_filters(tissue_detection)

5. Visualisation

Visualiser les lames, masques, emplacements de tuiles et qualité d'extraction.

Tâches de visualisation courantes :

  • Affichage de vignettes de lames
  • Visualisation de masques tissulaires
  • Aperçu des emplacements de tuiles
  • Évaluation de la qualité des tuiles
  • Création de rapports et figures

Référence : references/visualization.md contient une documentation complète sur :

  • Affichage et enregistrement de vignettes de lames
  • Visualisation de masques avec locate_mask()
  • Aperçu des emplacements de tuiles avec locate_tiles()
  • Affichage des tuiles extraites et mosaïques
  • Évaluation de la qualité (distributions de scores, tuiles supérieures vs inférieures)
  • Visualisation multi-lames
  • Visualisation des effets de filtre
  • Export de figures haute résolution et rapports PDF
  • Visualisation interactive dans les notebooks Jupyter

Flux de travail exemples :

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

# Afficher la vignette de la lame
plt.figure(figsize=(10, 10))
plt.imshow(slide.thumbnail)
plt.title(f"Lame: {slide.name}")
plt.axis('off')
plt.show()

# Visualiser le masque tissulaire
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Aperçu des emplacements de tuiles
tiler = RandomTiler(tile_size=(512, 512), n_tiles=50)
tiler.locate_tiles(slide, n_tiles=20)

# Afficher les tuiles extraites en grille
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()

Flux de travail typiques

Flux de travail 1 : Extraction de tuiles exploratoire

Échantillonnage rapide de régions tissulaires diversifiées pour l'analyse initiale.

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

# Activer la journalisation pour le suivi de la progression
logging.basicConfig(level=logging.INFO)

# Charger la lame
slide = Slide("slide.svs", processed_path="output/random_tiles/")

# Inspecter la lame
print(f"Dimensions: {slide.dimensions}")
print(f"Niveaux: {slide.levels}")
slide.save_thumbnail()

# Configurer le tiler aléatoire
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)

# Aperçu des emplacements
random_tiler.locate_tiles(slide, n_tiles=20)

# Extraire les tuiles
random_tiler.extract(slide)

Flux de travail 2 : Extraction complète en grille

Couverture tissulaire complète pour l'analyse de lame entière.

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

# Charger la lame
slide = Slide("slide.svs", processed_path="output/grid_tiles/")

# Utiliser TissueMask pour toutes les sections tissulaires
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Configurer le tiler en grille
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=1,  # Utiliser le niveau 1 pour une extraction plus rapide
    pixel_overlap=0,
    check_tissue=True,
    tissue_percent=70.0
)

# Aperçu de la grille
grid_tiler.locate_tiles(slide)

# Extraire toutes les tuiles
grid_tiler.extract(slide, extraction_mask=tissue_mask)

Flux de travail 3 : Sélection de tuiles axée sur la qualité

Extraire les tuiles les plus informatives en fonction de la densité de noyaux.

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

# Charger la lame
slide = Slide("slide.svs", processed_path="output/scored_tiles/")

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

# Aperçu des meilleures tuiles
score_tiler.locate_tiles(slide, n_tiles=15)

# Extraire avec rapport
score_tiler.extract(slide, report_path="tiles_report.csv")

# Analyser les scores
report_df = pd.read_csv("tiles_report.csv")
plt.hist(report_df['score'], bins=20, edgecolor='black')
plt.xlabel('Score de tuile')
plt.ylabel('Fréquence')
plt.title('Distribution des scores de tuiles')
plt.show()

Flux de travail 4 : Pipeline de traitement multi-lames

Traiter une collection entière de lames avec des paramètres cohérents.

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

logging.basicConfig(level=logging.INFO)

# Configurer le tiler une fois
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    seed=42,
    check_tissue=True
)

# Traiter toutes les lames
slide_dir = Path("slides/")
output_base = Path("output/")

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

    # Créer un répertoire de sortie spécifique à la lame
    output_dir = output_base / slide_path.stem
    output_dir.mkdir(parents=True, exist_ok=True)

    # Charger et traiter la lame
    slide = Slide(slide_path, processed_path=output_dir)

    # Enregistrer la vignette pour la révision
    slide.save_thumbnail()

    # Extraire les tuiles
    tiler.extract(slide)

    print(f"Terminé: {slide_path.name}")

Flux de travail 5 : Détection de tissus personnalisée et filtrage

Gérer les lames avec artefacts, annotations ou coloration inhabituelle.

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
)

# Définir un pipeline de filtre personnalisé pour la suppression agressive d'artefacts
aggressive_filters = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=10),
    RemoveSmallHoles(area_threshold=5000),
    RemoveSmallObjects(area_threshold=3000)  # Supprimer les artefacts plus grands
])

# Créer un masque personnalisé
custom_mask = TissueMask(filters=aggressive_filters)

# Charger la lame et visualiser le masque
slide = Slide("slide.svs", processed_path="output/")
slide.locate_mask(custom_mask)

# Extraire avec masque personnalisé
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100)
tiler.extract(slide, extraction_mask=custom_mask)

Bonnes pratiques

Chargement et inspection des lames

  1. Toujours inspecter les propriétés des lames avant le traitement
  2. Enregistrer les vignettes pour la révision visuelle rapide
  3. Vérifier les niveaux pyramidaux et les dimensions
  4. Vérifier la présence de tissu en utilisant les vignettes

Détection tissulaire

  1. Prévisualiser les masques avec locate_mask() avant l'extraction
  2. Utiliser TissueMask pour les sections multiples, BiggestTissueBoxMask pour les sections uniques
  3. Personnaliser les filtres pour des colorations spécifiques (H&E vs IHC)
  4. Gérer les annotations au stylo avec des masques personnalisés
  5. Tester les masques sur des lames diversifiées

Extraction de tuiles

  1. Toujours prévisualiser avec locate_tiles() avant extraction
  2. Choisir le tiler approprié :
    • RandomTiler : Échantillonnage et exploration
    • GridTiler : Couverture complète
    • ScoreTiler : Sélection axée sur la qualité
  3. Définir un seuil tissue_percent approprié (70-90% typique)
  4. Utiliser des graines pour la reproductibilité dans RandomTiler
  5. Extraire au niveau pyramidal approprié pour la résolution d'analyse
  6. Activer la journalisation pour les grands ensembles de données

Performance

  1. Extraire à des niveaux inférieurs (1, 2) pour un traitement plus rapide
  2. Utiliser BiggestTissueBoxMask plutôt que TissueMask quand approprié
  3. Ajuster tissue_percent pour réduire les tentatives de tuiles invalides
  4. Limiter n_tiles pour l'exploration initiale
  5. Utiliser pixel_overlap=0 pour les grilles sans chevauchement

Contrôle de qualité

  1. Valider la qualité des tuiles (vérifier le flou, les artefacts, la mise au point)
  2. Examiner les distributions de scores pour ScoreTiler
  3. Inspecter les tuiles avec les meilleurs et pires scores
  4. Surveiller les statistiques de couverture tissulaire
  5. Filtrer les tuiles extraites par des métriques de qualité supplémentaires si nécessaire

Cas d'usage courants

Entraînement de modèles d'apprentissage profond

  • Extraire des ensembles de données équilibrés à l'aide de RandomTiler sur plusieurs lames
  • Utiliser ScoreTiler avec NucleiScorer pour se concentrer sur les régions riches en cellules
  • Extraire à une résolution cohérente (niveau 0 ou niveau 1)
  • Générer des rapports CSV pour le suivi des métadonnées de tuiles

Analyse de lame entière

  • Utiliser GridTiler pour une couverture tissulaire complète
  • Extraire à plusieurs niveaux pyramidaux pour l'analyse hiérarchique
  • Maintenir les relations spatiales avec les positions de grille
  • Utiliser pixel_overlap pour les approches par fenêtres glissantes

Caractérisation tissulaire

  • Échantillonner des régions diversifiées avec RandomTiler
  • Quantifier la couverture tissulaire avec des masques
  • Extraire des informations spécifiques à la coloration avec la décomposition HED
  • Comparer les motifs tissulaires entre les lames

Évaluation de la qualité

  • Identifier les régions optimales de mise au point avec ScoreTiler
  • Détecter les artefacts en utilisant des masques et filtres personnalisés
  • Évaluer la qualité de coloration dans la collection de lames
  • Signaler les lames problématiques pour révision manuelle

Curation d'ensembles de données

  • Utiliser ScoreTiler pour prioriser les tuiles informatives
  • Filtrer les tuiles par pourcentage tissulaire
  • Générer des rapports avec scores de tuiles et métadonnées
  • Créer des ensembles de données stratifiés entre les lames et les types de tissus

Dépannage

Aucune tuile extraite

  • Abaisser le seuil tissue_percent
  • Vérifier que la lame contient du tissu (vérifier la vignette)
  • S'assurer que extraction_mask capture les régions tissulaires
  • Vérifier que tile_size est approprié pour la résolution de la lame

Beaucoup de tuiles de fond

  • Activer check_tissue=True
  • Augmenter le seuil tissue_percent
  • Utiliser le masque approprié (TissueMask vs BiggestTissueBoxMask)
  • Personnaliser les filtres de masque pour mieux détecter le tissu

Extraction très lente

  • Extraire à un niveau pyramidal inférieur (level=1 ou 2)
  • Réduire n_tiles pour RandomTiler/ScoreTiler
  • Utiliser RandomTiler à la place de GridTiler pour l'échantillonnage
  • Utiliser BiggestTissueBoxMask à la place de TissueMask

Les tuiles ont des artefacts

  • Implémenter des masques personnalisés d'exclusion d'annotations
  • Ajuster les paramètres de filtre pour la suppression d'artefacts
  • Augmenter le seuil de suppression des petits objets
  • Appliquer le filtrage de qualité post-extraction

Résultats incohérents entre les lames

  • Utiliser la même graine pour RandomTiler
  • Normaliser la coloration avec des filtres de prétraitement
  • Ajuster tissue_percent par qualité de coloration
  • Implémenter la personnalisation de masques spécifiques à la lame

Ressources

Cette compétence comprend une documentation de référence détaillée dans le répertoire references/ :

references/slide_management.md

Guide complet pour charger, inspecter et travailler avec des images de lames entières :

  • Initialisation et configuration des lames
  • Ensembles de données d'exemple intégrés
  • Propriétés et métadonnées des lames
  • Génération et visualisation de vignettes
  • Travail avec les niveaux pyramidaux
  • Flux de traitement multi-lames
  • Bonnes pratiques et motifs courants

references/tissue_masks.md

Documentation complète sur la détection tissulaire et le masquage :

  • Classes TissueMask, BiggestTissueBoxMask, BinaryMask
  • Fonctionnement des filtres de détection tissulaire
  • Personnalisation des masques avec des chaînes de filtre
  • Visualisation des masques
  • Création de masques rectangulaires personnalisés et d'exclusion d'annotations
  • Intégration avec l'extraction de tuiles
  • Bonnes pratiques et dépannage

references/tile_extraction.md

Explication détaillée des stratégies d'extraction de tuiles :

  • Comparaison RandomTiler, GridTiler, ScoreTiler
  • Notateurs disponibles (NucleiScorer, CellularityScorer, personnalisé)
  • Paramètres courants et spécifiques à la stratégie
  • Aperçu des tuiles avec locate_tiles()
  • Flux de travail d'extraction et rapports CSV
  • Motifs avancés (multi-niveaux, hiérarchique)
  • Optimisation des performances
  • Dépannage des problèmes courants

references/filters_preprocessing.md

Référence complète des filtres et guide de prétraitement :

  • Filtres d'image (conversion colorimétrique, seuillage, contraste)
  • Filtres morphologiques (dilatation, érosion, ouverture, fermeture)
  • Composition et enchaînement de filtres
  • Pipelines de prétraitement courants
  • Application de filtres aux tuiles
  • Filtres de masque personnalisés
  • Filtres de contrôle de qualité
  • Bonnes pratiques et dépannage

references/visualization.md

Guide de visualisation complet :

  • Affichage et enregistrement de vignettes de lames
  • Techniques de visualisation de masques
  • Aperçu des emplacements de tuiles
  • Affichage des tuiles extraites et création de mosaïques
  • Visualisations d'évaluation de qualité
  • Comparaison multi-lames
  • Visualisation des effets de filtre
  • Export de figures haute résolution et PDF
  • Visualisation interactive dans les notebooks Jupyter

Motif d'utilisation : Les fichiers de référence contiennent des informations détaillées pour soutenir les flux de travail décrits dans ce document de compétence principal. Charger les fichiers de référence spécifiques selon les besoins pour des conseils d'implémentation détaillés, du dépannage ou des fonctionnalités avancées.

Skills similaires

pathml
mkurman / zorai

Analyser des images histologiques entières avec ML, graphes spatiaux et multiplex.

309
imaging-data-commons
mkurman / zorai

Interroger et télécharger des données d'imagerie médicale publiques depuis NCI IDC.

309
eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

126
claude-api
anthropics / skills

Construire des applications LLM avec Claude via le SDK officiel adapté au langage.

146 952
ad-model-onboard
nvidia / skills

Automatiser l'intégration de modèles HuggingFace dans AutoDeploy avec tests et rapport.

1 033