|
|
--- |
|
|
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 |
|
|
|
|
|
```bash |
|
|
pip install torch torchvision huggingface_hub pillow |
|
|
``` |
|
|
|
|
|
### Basic Usage |
|
|
|
|
|
```python |
|
|
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 |
|
|
|
|
|
```python |
|
|
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 |
|
|
|
|
|
```python |
|
|
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](https://github.com/markowetzlab/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: |
|
|
|
|
|
```python |
|
|
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: |
|
|
|
|
|
```bibtex |
|
|
@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](https://github.com/lab-rasool/HoneyBee). |
|
|
|
|
|
## Additional Resources |
|
|
|
|
|
- **HoneyBee Framework**: [https://github.com/lab-rasool/HoneyBee](https://github.com/lab-rasool/HoneyBee) |
|
|
- **Documentation**: [https://lab-rasool.github.io/HoneyBee](https://lab-rasool.github.io/HoneyBee) |
|
|
- **Original Model Source**: [SliDL GitHub](https://github.com/markowetzlab/slidl) |
|
|
|
|
|
## Version History |
|
|
|
|
|
- **v1.0** (2024): Initial release with DenseNet121 architecture |
|
|
- PyTorch state dict format |
|
|
- SafeTensors format for improved loading |
|
|
- Integration with HuggingFace Hub |
|
|
|
