Metadata-Version: 2.4
Name: histox
Version: 0.1.8
Summary: Deep learning tools for digital histology
Home-page: https://github.com/leicaohmu/histox
Author: Lei Cao
Author-email: caolei@hrbmu.edu.cn
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gast>=0.3.3
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib>=3.2
Requires-Dist: imageio
Requires-Dist: opencv-python-headless
Requires-Dist: shapely
Requires-Dist: umap-learn
Requires-Dist: seaborn<0.14
Requires-Dist: pandas
Requires-Dist: pyvips
Requires-Dist: fpdf2
Requires-Dist: scikit-image
Requires-Dist: tqdm
Requires-Dist: click
Requires-Dist: protobuf<3.21
Requires-Dist: tensorboard
Requires-Dist: crc32c
Requires-Dist: numpy
Requires-Dist: tabulate
Requires-Dist: rasterio
Requires-Dist: smac==1.4.0
Requires-Dist: ConfigSpace
Requires-Dist: rich
Requires-Dist: pillow>=6.0.0
Requires-Dist: imgui>=2.0.0
Requires-Dist: pyopengl
Requires-Dist: glfw
Requires-Dist: saliency
Requires-Dist: pyperclip
Requires-Dist: requests
Requires-Dist: parameterized
Requires-Dist: zarr
Requires-Dist: gdown
Requires-Dist: triangle
Requires-Dist: pyarrow
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Requires-Dist: torchvision; extra == "torch"
Requires-Dist: pretrainedmodels; extra == "torch"
Requires-Dist: cellpose<2.2; extra == "torch"
Requires-Dist: spacy<3.8; extra == "torch"
Requires-Dist: fastai; extra == "torch"
Requires-Dist: pytorch-lightning; extra == "torch"
Requires-Dist: timm; extra == "torch"
Requires-Dist: segmentation-models-pytorch; extra == "torch"
Provides-Extra: tf
Requires-Dist: tensorflow<2.12,>=2.7; extra == "tf"
Requires-Dist: tensorflow_probability<0.20; extra == "tf"
Requires-Dist: tensorflow_datasets<4.9.0; extra == "tf"
Provides-Extra: cucim
Requires-Dist: cucim; extra == "cucim"
Provides-Extra: cucim-cuda12
Requires-Dist: cucim; extra == "cucim-cuda12"
Requires-Dist: cupy-cuda12x; extra == "cucim-cuda12"
Provides-Extra: cucim-cuda11
Requires-Dist: cucim; extra == "cucim-cuda11"
Requires-Dist: cupy-cuda11x; extra == "cucim-cuda11"
Provides-Extra: noncommercial
Requires-Dist: slideflow-noncommercial; extra == "noncommercial"
Provides-Extra: gpl
Requires-Dist: slideflow-gpl; extra == "gpl"
Provides-Extra: all
Requires-Dist: slideflow-noncommercial; extra == "all"
Requires-Dist: slideflow-gpl; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# histox

![Python Version](https://img.shields.io/badge/python->=3.7-blue)
![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen)
![Language](https://img.shields.io/badge/language-Python-blue)
[![Docs](https://readthedocs.org/projects/histox/badge/?version=latest)](https://histox.readthedocs.io/en/latest/)

**histox** is a powerful, open-source deep learning library for digital pathology. Built on top of [Slideflow](https://github.com/slideflow/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](https://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)

```bash
pip install histox
```

### From Source

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

### With PyTorch Backend

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

### With TensorFlow Backend

```bash
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:

```bash
nvidia-smi
```

Then install the matching extra:

```bash
# 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:
> ```bash
> 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:

```csv
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

```python
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

```python
# 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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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](https://histox.readthedocs.io)
- 🐛 [GitHub Issues](https://github.com/leicaohmu/histox/issues)
- 📦 [PyPI Package](https://pypi.org/project/histox/)

## 🤝 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](https://github.com/slideflow/slideflow). Please refer to the original project's license for additional terms.

## 🙏 Acknowledgments

- **[Slideflow](https://github.com/slideflow/slideflow)** - The powerful foundation this project is built upon
- **[TCGA](https://portal.gdc.cancer.gov/)** - The Cancer Genome Atlas for dataset resources
- **PyTorch & TensorFlow** - Deep learning frameworks

## 📞 Support & Contact

- **Email**: caolei@hrbmu.edu.cn
- **Documentation**: [histox.readthedocs.io](https://histox.readthedocs.io)
- **Repository**: [github.com/leicaohmu/histox](https://github.com/leicaohmu/histox)

## 🔗 Related Resources

- [histox Documentation](https://histox.readthedocs.io)
- [Slideflow Documentation](https://slideflow.dev)
- [TCGA Data Portal](https://portal.gdc.cancer.gov/)
- [Digital Pathology Resources](https://www.digipathonet.org/)

---

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