README.md

metadata

license: gpl-3.0
tags:
  - histopathology
  - tissue-detection
  - whole-slide-imaging
  - pathology
  - medical-imaging
  - densenet
  - image-classification
  - computational-pathology
  - cancer-research
library_name: pytorch
pipeline_tag: image-classification

Deep Tissue Detector - DenseNet121

A deep learning model for detecting tissue regions in Whole Slide Images (WSI) of histopathology slides.

Model Description

This is a DenseNet121-based tissue detector trained to classify image patches into three categories for histopathology analysis. The model is specifically designed to identify tissue-containing regions in H&E (Hematoxylin and Eosin) stained whole slide images, enabling efficient processing of large pathology datasets.

Model Details

• Architecture: DenseNet121
• Input Size: 224x224 RGB images
• Number of Classes: 3
  • Class 0: Background/Non-tissue
  • Class 1: Artifact/Low-quality
  • Class 2: Tissue (high quality)
• Parameters: ~7M
• Model Size: 28MB
• Framework: PyTorch
• License: GPL-3.0

Intended Use

This model is designed for:

• Filtering tissue-containing patches from whole slide images
• Quality control in computational pathology pipelines
• Preprocessing for downstream cancer analysis tasks
• Reducing computational burden by identifying regions of interest

Recommended Usage: Accept patches where class 2 (tissue) probability ≥ 0.8

Usage

Installation

pip install torch torchvision huggingface_hub pillow

Basic Usage

from tissue_detector import TissueDetector
from PIL import Image

# Initialize detector (automatically downloads weights from HuggingFace)
detector = TissueDetector(device='cuda')

# Load and process an image
image = Image.open('patch.png')
patch_transformed = detector.transforms(image)
patch_batch = patch_transformed.unsqueeze(0).to(detector.device)

# Get predictions
import torch
with torch.no_grad():
    prediction = detector.model(patch_batch)
    probabilities = torch.nn.functional.softmax(prediction, dim=1).cpu().numpy()[0]
    tissue_class = probabilities.argmax()

# Check if patch contains tissue (class 2 with threshold 0.8)
is_tissue = tissue_class == 2 and probabilities[2] >= 0.8
print(f"Tissue detected: {is_tissue} (confidence: {probabilities[2]:.3f})")

Integration with HoneyBee Framework

from honeybee.models import TissueDetector
from honeybee.processors.wsi import SimpleSlide

# Initialize tissue detector
detector = TissueDetector(device='cuda')

# Load whole slide image
slide = SimpleSlide(
    slide_path='path/to/slide.svs',
    tile_size=512,
    max_patches=100,
    tissue_detector=detector
)

# Extract tissue patches (automatically filtered)
patches = slide.load_patches_concurrently(target_patch_size=224)

Manual Download

from huggingface_hub import hf_hub_download

# Download PyTorch weights
model_path = hf_hub_download(
    repo_id="Lab-Rasool/tissue-detector",
    filename="deep-tissue-detector_densenet_state-dict.pt"
)

# Or download SafeTensors format (recommended)
model_path = hf_hub_download(
    repo_id="Lab-Rasool/tissue-detector",
    filename="model.safetensors"
)

Model Performance

The model has been extensively used in cancer classification, survival analysis, and multimodal integration tasks within the HoneyBee framework. It effectively filters:

• Background regions: Glass slide backgrounds, whitespace
• Artifacts: Pen marks, dust, blur, fold artifacts
• Tissue regions: High-quality H&E stained tissue for analysis

Recommended threshold: 0.8 probability for class 2 provides a good balance between recall and precision for tissue detection.

Training Data

The model was originally trained as part of the SliDL project for tissue detection in histopathology whole slide images. Training details include H&E stained tissue sections with annotations for tissue/non-tissue regions.

Preprocessing

The model expects images preprocessed with standard ImageNet normalization:

from torchvision import transforms

preprocessing = transforms.Compose([
    transforms.Resize(224),
    transforms.ToTensor(),
    transforms.Normalize(
        mean=[0.485, 0.456, 0.406],
        std=[0.229, 0.224, 0.225]
    )
])

Limitations and Biases

• Stain Variation: Performance may vary with different staining protocols or scanners
• Tissue Types: Primarily validated on H&E stained tissue; may not generalize to other stains
• Resolution: Designed for patches at standard WSI resolution (~0.5 µm/pixel)
• Artifacts: May misclassify unusual artifacts not seen during training
• Medical Use: This model is for research purposes only and not intended for clinical diagnosis

Applications in Research

This tissue detector has been used in:

• Cancer Classification: TCGA multi-cancer type classification (BRCA, BLCA, KIRC, LIHC, etc.)
• Survival Analysis: Cox proportional hazards and deep survival models
• Stain Normalization Studies: Evaluating impact of Macenko/Reinhard normalization
• Multimodal Integration: Combining pathology with clinical, radiology, and molecular data
• Foundation Model Evaluation: Preprocessing for UNI, UNI2, Virchow2 embeddings

Citation

If you use this model, please cite the HoneyBee framework and the original SliDL project:

@software{honeybee2024,
  title={HoneyBee: A Scalable Modular Framework for Multimodal AI in Oncology},
  author={Lab-Rasool},
  year={2024},
  url={https://github.com/lab-rasool/HoneyBee}
}

@software{slidl,
  title={SliDL: A Python library for deep learning on whole-slide images},
  author={Markowetz Lab},
  url={https://github.com/markowetzlab/slidl}
}

Model Card Authors

Lab-Rasool

Model Card Contact

For questions or issues, please open an issue on the HoneyBee GitHub repository.

Additional Resources

• HoneyBee Framework: https://github.com/lab-rasool/HoneyBee
• Documentation: https://lab-rasool.github.io/HoneyBee
• Original Model Source: SliDL GitHub

Version History

• v1.0 (2024): Initial release with DenseNet121 architecture
  • PyTorch state dict format
  • SafeTensors format for improved loading
  • Integration with HuggingFace Hub