histox

histox is a powerful, open-source deep learning library for digital pathology. Built on top of Slideflow, it provides researchers and AI practitioners with a comprehensive toolkit for analyzing whole slide images (WSI) and building state-of-the-art computational pathology models.

🌐 Documentation: histox.readthedocs.io

✨ Key Features

• End-to-end WSI analysis pipeline - From raw slides to trained models
• Robust slide processing - Automatic tile extraction with stain normalization
• Flexible learning paradigms
  • Strongly-supervised and weakly-supervised learning
  • Multiple Instance Learning (MIL) for slide-level labels
  • Self-Supervised Learning (SSL) for representation learning
  • Generative Adversarial Networks (GANs) for data augmentation
• Pre-trained foundation models - Integrated support for modern architectures
• Interpretability tools - Generate heatmaps, saliency maps, and mosaic visualizations
• Layer activation analysis - Understand model decision-making
• Uncertainty quantification - Measure model confidence

📋 Requirements

• Python: >= 3.7
• Deep Learning Framework (at least one):
  • PyTorch >= 1.9
  • TensorFlow >= 2.5, < 2.12

📦 Installation

From PyPI (Recommended)

pip install histox

From Source

git clone https://github.com/leicaohmu/histox
cd histox
pip install -e .

With PyTorch Backend

pip install histox[torch]
# or from source
pip install -e ".[torch]"

With TensorFlow Backend

pip install histox[tf]
# or from source
pip install -e ".[tf]"

With cuCIM GPU Acceleration (WSI Reading)

cuCIM provides GPU-accelerated whole slide image reading. First check your CUDA version:

nvidia-smi

Then install the matching extra:

# CUDA 12.x
pip install histox[torch,cucim-cuda12]

# CUDA 11.x
pip install histox[torch,cucim-cuda11]

# cuCIM only (manage cupy manually)
pip install histox[torch,cucim]

⚠️ Important: cupy is tightly coupled to your CUDA version. Do not install multiple cupy-* packages simultaneously, as this will cause conflicts. If you encounter a conflict, clean up first:

pip uninstall cupy cupy-cuda12x cupy-cuda11x -y

Then reinstall the correct version.

Installation Summary

Command	Includes
pip install histox	Core only
pip install histox[torch]	Core + PyTorch
pip install histox[tf]	Core + TensorFlow
pip install histox[torch,cucim]	Core + PyTorch + cuCIM
pip install histox[torch,cucim-cuda12]	Core + PyTorch + cuCIM + CuPy (CUDA 12)
pip install histox[torch,cucim-cuda11]	Core + PyTorch + cuCIM + CuPy (CUDA 11)

🚀 Quick Start Example

This example demonstrates how to train a lung cancer adenocarcinoma classifier using the included TCGA dataset.

1. Prepare Your Data Structure

project_root/
├── slides/                    # WSI files (.svs, .ndpi, etc.)
│   ├── TCGA-83-5908-01Z-00-DX1.svs
│   ├── TCGA-62-A46V-01Z-00-DX1.svs
│   └── ...
├── annotations.csv            # Slide labels
└── tfrecords/                # Output directory for processed data (auto-created)

2. Create Annotation File

Create annotations.csv with slide-level labels:

patient,subtype,site,slide
TCGA-83-5908,adenocarcinoma,Site-28,TCGA-83-5908-01Z-00-DX1
TCGA-62-A46V,adenocarcinoma,Site-124,TCGA-62-A46V-01Z-00-DX1
TCGA-44-2655,squamous,Site-29,TCGA-44-2655-01Z-00-DX1

(A complete dataset example is available in lung_labels.csv in this repository)

3. Initialize and Train

import histox as hx
import os

# Define paths
project_root = '/path/to/project'
annotations_file = '/path/to/annotations.csv'
slides_directory = '/path/to/slides'
tfrecords_directory = os.path.join(project_root, 'tfrecords')

# Create project
print("[1/5] Creating project...")
project = hx.create_project(
    root=project_root,
    annotations=annotations_file,
    slides=slides_directory,
    tfrecords=tfrecords_directory
)

# Extract tiles from slides
print("[2/5] Extracting tiles...")
project.extract_tiles(
    tile_px=299,        # Tile size in pixels
    tile_um=302,        # Tile size in micrometers
    workers=8           # Number of parallel workers
)

# Define model parameters
print("[3/5] Configuring model...")
params = hx.ModelParams(
    tile_px=299,
    tile_um=302,
    batch_size=32,
    model='xception',            # Base architecture
    learning_rate=0.0001,
    epochs=50,
    validation_fraction=0.2
)

# Train the model
print("[4/5] Training model...")
project.train(
    'subtype',                   # Column name for classification target
    params=params,
    save_predictions=True,
    multi_gpu=True               # Enable multi-GPU training if available
)

# Generate explanations
print("[5/5] Generating interpretations...")
project.generate_heatmaps()      # Attention/saliency visualizations
project.generate_mosaic_maps()   # Tile-level predictions

print("✓ Training complete!")

4. Evaluate and Interpret Results

# Access trained models and predictions
results = project.get_results('subtype')

# Generate patient-level predictions
slide_predictions = project.predict_slides('subtype')

# Create visualizations
heatmap = hx.Heatmap.from_project(
    project=project,
    outcome_name='subtype',
    model_idx=0
)
heatmap.save('/path/to/output/heatmap.png')

# Access detailed metrics
print(f"Validation Accuracy: {results['val_accuracy']:.4f}")
print(f"Validation AUC: {results['val_auc']:.4f}")

📊 Complete Workflow Example (Lung Cancer Dataset)

Here's a ready-to-run example using the included TCGA lung cancer data:

import histox as hx
import pandas as pd
import os

# Configuration
data_root = './datasets/lung_adeno_squam'
project_dir = './lung_project'

annotations_file = os.path.join(data_root, 'lung_labels.csv')
slides_dir = os.path.join(data_root, 'slides')
tfrecords_dir = os.path.join(project_dir, 'tfrecords')

# Check available data
labels_df = pd.read_csv(annotations_file)
print(f"Total slides: {len(labels_df)}")
print(f"Subtypes: {labels_df['subtype'].unique()}")
print(labels_df.head())

# Step 1: Create project
try:
    project = hx.create_project(
        root=project_dir,
        annotations=annotations_file,
        slides=slides_dir,
        tfrecords=tfrecords_dir
    )
    print("✓ Project created successfully")
except Exception as e:
    print(f"Project already exists or error: {e}")

# Step 2: Extract tiles (if slides are available)
try:
    project.extract_tiles(
        tile_px=299,
        tile_um=302,
        workers=4,
        verbose=True
    )
    print("✓ Tiles extracted")
except Exception as e:
    print(f"Could not extract tiles: {e}")

# Step 3: Configure and train
params = hx.ModelParams(
    tile_px=299,
    tile_um=302,
    batch_size=32,
    model='xception',
    learning_rate=0.0001,
    epochs=30,
    validation_fraction=0.2
)

project.train(
    'subtype',
    params=params,
    save_predictions=True,
    multi_gpu=False
)

print("✓ Model training complete!")

🔧 Advanced Features

Multiple Instance Learning (MIL)

Use when you only have slide-level labels, not individual tile annotations:

params = hx.ModelParams(
    tile_px=299,
    model='xception',
    mil=True,
    mil_method='attention',   # 'attention' or 'max-pooling'
    learning_rate=0.0001
)

project.train('diagnosis', params=params)

Self-Supervised Pre-training

Pre-train feature extractors without labeled data:

project.train_ssl(
    method='simclr',
    epochs=100,
    batch_size=64,
    model='xception'
)

# Fine-tune on labeled data
project.train('diagnosis', params=params)

Stain Normalization

Automatic handling of staining variations across labs:

project.extract_tiles(
    tile_px=299,
    tile_um=302,
    stain_norm=True,
    norm_method='macenko'     # 'macenko' or 'reinhard'
)

Generate Heatmaps

Visualize model predictions across slides:

heatmap = hx.Heatmap.from_project(
    project=project,
    outcome_name='diagnosis',
    model_idx=0,
    cmap='RdYlBu_r'
)

heatmap.save(
    '/output/heatmap.png',
    high_res=True,
    stride=32
)

📚 Key Modules

Module	Purpose
histox.project	Main Project class for pipeline management
histox.dataset	Dataset handling and tile management
histox.model	Model architecture and training
histox.slide	WSI (Whole Slide Image) handling
histox.norm	Stain normalization algorithms
histox.heatmap	Heatmap generation and visualization
histox.stats	Statistical analysis and reporting

🎯 Supported Models

• CNN Architectures: Xception, ResNet-50, EfficientNet, InceptionV3, DenseNet
• Vision Transformers: ViT, DeiT
• Specialized Architectures: Cellpose (instance segmentation)

📖 Documentation

For detailed documentation and API reference:

• 📘 histox Documentation
• 🐛 GitHub Issues
• 📦 PyPI Package

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0. See LICENSE file for details.

Note: This project is built on Slideflow. Please refer to the original project's license for additional terms.

🙏 Acknowledgments

• Slideflow - The powerful foundation this project is built upon
• TCGA - The Cancer Genome Atlas for dataset resources
• PyTorch & TensorFlow - Deep learning frameworks

📞 Support & Contact

• Email: caolei@hrbmu.edu.cn
• Documentation: histox.readthedocs.io
• Repository: github.com/leicaohmu/histox

🔗 Related Resources

• histox Documentation
• Slideflow Documentation
• TCGA Data Portal
• Digital Pathology Resources

---

Status: Active development
Last Updated: 2026-04-11