- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| figure | ||
| functions | ||
| GNN_train_and_test.py | ||
| ke_datapy | ||
| ke_embeding.py | ||
| ke_graph_s.py | ||
| README.md | ||
| requirements.txt | ||
LCG-HGNN: Logic-Constrained Gene-Pathway Heterogeneous Graph Neural Network
Inferring signaling pathway abnormalities from histopathological images via logic-constrained gene-pathway heterogeneous knowledge graph
This repository contains the official implementation of LCG-HGNN, a framework designed to infer signaling pathway alterations (e.g., PI3K-Akt) directly from Whole-Slide Images (WSIs). By integrating a Gene-Pathway Heterogeneous Graph and the KePathGraph framework, this model enables collaborative recognition of gene groups and incorporates biological priors via logical clauses to enhance clinical interpretability.

This codebase provides a complete, self-contained pipeline for data preprocessing, model training, and evaluation, facilitating the reproduction of the experimental results reported in our paper.
Table of Contents
- System Requirements
- Installation
- Dataset Preparation
- Hyperparameters & Configuration
- Usage Pipeline
- Inputs and Outputs
- Citation
System Requirements
- OS: Linux (Recommended) or Windows
- Python: 3.8+
- Hardware: NVIDIA GPU (Tested on RTX A6000) with CUDA 11.x+
- Dependencies:
torch >= 1.12torch-geometrictorchvisionscikit-learn,pandas,numpy,pillowKENN-PyTorch(See installation below)
Installation
To ensure reproducibility, please follow these steps to set up the environment and install the required Knowledge Enhanced Neural Networks (KENN) library.
-
Clone the repository:
git clone [https://github.com/xianyvxxx/LCG-HGNN.git](https://github.com/xianyvxxx/LCG-HGNN.git) cd LCG-HGNN -
Create a virtual environment:
conda create -n lcg_hgnn python=3.8 conda activate lcg_hgnn -
Install PyTorch:
pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 --extra-index-url [https://download.pytorch.org/whl/cu113](https://download.pytorch.org/whl/cu113) -
Install PyTorch Geometric:
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f [https://data.pyg.org/whl/torch-1.12.1+cu113.html](https://data.pyg.org/whl/torch-1.12.1+cu113.html) pip install pandas numpy scikit-learn pillow -
Install KENN: We utilize KENN-PyTorch for logic constraint layers. Please install it directly from the official source:
# Clone and install KENN git clone [https://github.com/HEmile/KENN-PyTorch.git](https://github.com/HEmile/KENN-PyTorch.git) cd KENN-PyTorch pip install . cd ..
Dataset Preparation
To reproduce the results, the data must be organized and pre-processed according to the methods described in our manuscript.
1. Primary Data Sources
| Dataset | Description | Access | Usage in Study |
|---|---|---|---|
| TCGA-LUAD WSIs | 1,608 whole-slide images (.svs format) from lung adenocarcinoma patients |
NCI Genomic Data Commons (GDC) | Histopathological image input; linked to genomic data via TCGA barcode |
| cBioPortal Mutation Data | Somatic mutation profiles (SNVs/indels) for TCGA-LUAD cohort (585 patients with WSI + mutation) | cBioPortal API | Gene-level labels for model supervision |
| Cancer Gene Census (CGC) | Curated list of 35 high-confidence lung cancer driver genes (e.g., EGFR, KRAS, TP53) with oncogenic/tumor-suppressor roles | COSMIC CGC v102 | Prior knowledge for edge weighting & label filtering |
| DAVID Pathway Annotations | Gene–pathway associations from 4 databases: KEGG, Reactome, WikiPathways, BioCarta | DAVID 6.8 API | Construction of gene–pathway heterogeneous graph |
| Human Protein Atlas (HPA) | Immunohistochemistry images of EGFR/KRAS*-mutant LUAD cases (clinical reference) | HPA Pathology Atlas | Validation of clinical plausibility (image similarity assessment) |
2. Directory Structure
We recommend organizing your data directory (/your/data/root/) as follows. Note: You must update the path variables in the scripts (GIN_TaT.py, etc.) to point to your specific directories.
data_root/
├── label/
│ ├── gene_list.csv # Gene labels (Target)
│ ├── pathway_new.csv # Pathway hierarchy info (DAVID/KEGG derived)
│ └── top20_LUAD.csv # Patient IDs and mutation status
├── patch/
│ ├── features/ # Pre-processed .json graph features (See Logic below)
│ └── images/ # Raw WSI patches (Required for Step 3 visualization)
├── logic_rules/
│ └── logic_rules_hsa04151.txt # DNF Logic clauses for the pathway
└── output/ # Directory for saved models and results
3. Preprocessing Logic
Before running the pipeline, raw WSIs must be processed into graph features:
- Segmentation: Segment WSIs into
512 \times 512pixel patches. - Feature Extraction: Use an ImageNet-pretrained ResNet-18 to extract features for each patch.
- Graph Construction:
- Compute Euclidean distances between patch features.
- Connect each node to its top-10 nearest neighbors.
- Establish spatial edges if physical distance is < 85 pixels.
- Format: Save the resulting adjacency matrices (
adj) and feature vectors (x) into.jsonformat compatible withgenerate_datasetinfunctions/utils.py.
Hyperparameters & Configuration
We provide configuration with default hyperparameters that reproduce the main experimental results reported in the paper. These are located at the top of GIN_TaT.py and ke_graph_s.py.
Key Default Settings:
feature_dimension: 512num_epochs: 128batch_size: 24learning_rate: 1e-3weight_decay: 1e-5lambda_reg: 0.03 (For dynamic edge weighting regularization)
Usage Pipeline
The framework operates in a sequential pipeline. Follow these steps to reproduce the main experimental results.
Step 1: Graph Learning & Dynamic Weighting
Train the Gene-Pathway Heterogeneous Graph model. This script trains the GIN backbone to predict gene mutations and applies the Dynamic Edge Weighting Mechanism to incorporate Cancer Gene Census (CGC) priors.
Bash
# Update 'csv_file_gene' and 'feature_path' in GIN_TaT.py first
python GNN_train_and_test.py
-
Function: Trains the model using multi-label graph classification.
-
Key Logic: Implements the dynamic weighting formula:
\Delta w_{gp}=\gamma_{gp}\cdot e\cdot w_{gp}-\lambda\cdot\frac{w_{gp}}{|w_{gp}|_{2}} -
Expected Output: Trained model checkpoints (e.g.,
epoch_97.pth) saved in the output directory and training logs showing Accuracy/AUC metrics.
Step 2: Node Sorting & Selection
Run inference on the test set to identify the "Top-K" most structurally important patches (Global Sort Pooling).
Bash
# Update 'model_path' to point to the best checkpoint from Step 1
python ke_data.py
- Function: Loads the best checkpoint and extracts patch indices contributing to the prediction.
- Expected Output:
test_data_patch.pth(list of important patch paths) andselect_index_all.pth.
Step 3: Feature Embedding
Extract visual feature embeddings for the specific patches identified in Step 2. These embeddings are required for building the inter-individual graph.
Bash
python ke_embeding.py
- Function: Uses ResNet-18 to generate tensor embeddings for the selected patches.
- Expected Output: A directory
result_dict/containing.ptembedding files for the top-ranked patches.
Step 4: KePathGraph Construction & Knowledge Enhancement
Construct the KePathGraph and apply Logical Clauses (e.g., Mutual Exclusivity, Hierarchy). This step refines the predictions using the Knowledge Enhancer (KE) module from KENN.
Bash
# Ensure 'logic_rules_hsa04151.txt' is available
python ke_graph_s.py
- Function: Builds the inter-individual graph and applies logic rules (Equations 4-9 in the manuscript).
- Expected Output:
mismatched_rows.csv: Analysis of predictions refined by logic constraints.- Comparative metrics showing performance with vs. without logic constraints.
Inputs and Outputs Summary
| Script | Input Data | Output Data |
|---|---|---|
GNN_train_and_test.py |
Graph feature JSONs, Label CSVs | Model checkpoints (.pth), Training logs |
ke_data.py |
Trained Model (.pth), Test Dataset |
Selected patch indices (.pth) |
ke_embeding.py |
Selected patch images | Visual embeddings (.pt) |
ke_graph_s.py |
Embeddings, Logic Rules (.txt) |
Final Predictions, Consistency CSVs |
Citation
If you find this code or framework useful for your research, please cite our paper:
@article{LCG-HGNN,
title={Inferring signaling pathway abnormalities from histopathological images via logic-constrained gene-pathway heterogeneous knowledge graph},
author={Yu, Yu and Shi, Wen and Chen, Xin and Feng, Jinghui and Huang, Simin and Zeng, Shixian and Bo, Xiaolin and Xi, Jianing},
journal={npj Biomedical Innovations},
year={2025}
}