HCCExplorer: Transforming Histology into Virtual Multiplex Immunofluorescence to Decode Tumor Immune Microenvironment in Hepatocellular Carcinoma

This repository contains the official implementation of HCCExplorer, a deep learning framework that transforms standard H&E slides into virtual multiplex immunofluorescence (mIF) images and performs spatially resolved survival analysis for hepatocellular carcinoma (HCC). Specific tutorials are in directories.

🔬 Overview

Figure 1: HCCExplorer framework overview. [View Full PNG]

🌟 Key Features

🔬 Overview

HCCExplorer addresses critical limitations in routine hepatopathology by:

1. Virtual Immunophenotyping: Generates high-fidelity virtual mIF images (CD3, CD4, CD8, CD19, CD68, Foxp3, DAPI) from standard H&E slides without physical staining
2. Spatial Prognostic Modeling: Captures tumor-immune microenvironment (TIME) interactions through hierarchical graph learning
3. Biomarker Discovery: Identifies macrophage-mediated "Containment Niche" as a protective spatial signature at the invasion frontier

Performance Highlights

• C-index: 0.71 (95% CI: 0.67–0.76) for overall survival prediction
• Data Efficiency: Trained on only 30 paired slides, generalized to 1,813 patients across 4 centers
• Superior Generalization: Outperforms pathology foundation models (UNI-h2, CHIEF, Prov-GigaPath, TITAN) and proteomics foundation model (KRONOS)

📁 Repository Structure

HCCExplorer/
├── C3UT/                    # Virtual mIF translation (Cell-Consistent Cross-modal Unpaired Translation)
    └── Tutorial             # Step-by-step guide for H&E-to-mIF generation
├── CellFilter               # Cell segmentation and quality control
    └── Tutorial             # Data preprocessing and cell filtering protocols
├── CoOptimization/          # H&E-virtual mIF feature co-optimization
    └── Tutorial             # Multi-modal contrastive learning pipeline
├── GraphLearning/           # Graph-based survival analysis
    └── Tutorial             # Graph construction and survival prediction
├── ImmuneAnalysis/          # Spatial immune feature extraction
    └── Tutorial             # Immune profiling and biomarker validation
└── Registration/            # WSI registration and spatial alignment
    └── Tutorial             # Image registration workflows

Note: Each module contains a dedicated Tutorial notebook with detailed documentation, usage examples, and step-by-step instructions.

🚀 Quick Start

Prerequisites

# Python 3.8+
pip install torch>=1.12.0 torchvision>=0.13.0
pip install openslide-python numpy pandas scikit-learn
pip install torch-geometric torch-scatter torch-sparse  # For GraphLearning

1. Virtual mIF Generation (C3UT)

📖 Detailed tutorial: See C3UT/Tutorial

2. Feature Co-Optimization

📖 Detailed tutorial: See CoOptimization/Tutorial

3. Survival Prediction (GraphLearning)

📖 Detailed tutorial: See GraphLearning/Tutorial

4. Immune Feature Analysis

📖 Detailed tutorial: See ImmuneAnalysis/Tutorial

📊 Datasets

The framework was validated on four independent cohorts:

🔍 Key Biological Findings

HCCExplorer enabled discovery of:

1. Macrophage Infiltration: Most significant protective factor (HR=0.51, P<0.001)
2. M1 Polarization: Pro-inflammatory macrophages drive survival benefit (HR=0.40, P<0.05)
3. Containment Niche: Macrophage-orchestrated immune barrier at invasion frontier (P<0.01)
4. Spatial Co-localization: Foxp3+ Tregs and CD4+ T cells cooperate with macrophages at tumor boundary

🛠️ Installation

# Clone repository
git clone https://github.com/MedCAI/HCCExplorer.git
cd HCCExplorer

# Install dependencies in each directory
pip install -r requirements.txt

# Download pretrained weights (available upon request for academic use)

📚 Citation

If you use HCCExplorer in your research, please cite:

@article{cai2026hccexplorer,
  title={Transforming Histology into Virtual Multiplex Immunofluorescence to Decode Prognostic Spatial Immunity in Hepatocellular Carcinoma},
  author={Cai, Linghan and Jiang, Songhan and Liang, Junhao and Liu, Fengchun and Zhang, Buyi and Reitsam, Nic Gabriel and Zeng, Qinghe and Hu, Zheqi and Ma, Yanqing and Li, Ziqian and Shi, Feng and Hu, Maotong and Zhang, Xiuming and Zhang, Jing and Kather, Jakob Nikolas and Zhang, Yongbing and Liang, Wenjie},
  journal={BioRxiv},
  year={2026}
}

📧 Contact

For questions about the code or model access:

• Issues: Please use GitHub Issues
• Email: Linghan Cai; Songhan Jiang; Fengchun Liu

🤝 Contributing

Thanks to the following work for improving our project：

• MADELEINE (contrastive learning): https://github.com/mahmoodlab/MADELEINE
• Trident (data pre-processing): https://github.com/mahmoodlab/TRIDENT
• HoverNet (H&E cell segmentation): https://github.com/vqdang/hover_net
• StarDist (mIF cell segmentation): https://github.com/stardist/stardist
• VALIS (WSI registration): https://github.com/MathOnco/valis
• TEA-Graph (graph learning): https://github.com/taliq/TEA-graph
• CUT (H&E-to-mIF translation): https://github.com/taesungp/contrastive-unpaired-translation/
• TissueLab (code style): https://github.com/zhihuanglab/Tissuelab-Model-Zoo/tree/main

📜 License

This code is made available for academic research purposes only. Commercial use requires explicit permission from the authors.