Knowledge-Enhanced Pathway--Protein Network with Biomedical Semantic Augmentation for Primary--Metastatic Status Prediction

KEPPNet is a dual-branch deep learning framework for cancer treatment response classification. It combines a knowledge-enhanced pathway-protein structural network (structural branch) with a biomedical language model (semantic branch), fusing both at decision level.

Model Overview

Genomic Input (mut + CNA)          Patient Text Summary
        ↓                                   ↓
  Structural Branch                  Semantic Branch
  (PathProNet)                       (BioLORD-2023)
        ↓                                   ↓
   h_bio (pathway repr.)            h_llm (768-dim)
        ↓                                   ↓
        └──────── Late Fusion ─────────────┘
                       ↓
               p_final (prediction)

Structural Branch

A biologically-constrained sparse neural network built on:

• Reactome pathway hierarchy as scaffold (leaf-to-root aggregation)
• PPI-supported protein-mediated routing between pathway layers (STRING v12)
• KG-based relation completion (ReactomeProteinNetworkKGEnhanced)
• Hierarchy-aware thresholding and hub protein filtering
• Mask-constrained sparse layers (CustomizedLinear)

Semantic Branch

• Patient molecular alterations converted to structured text (no label leakage)
• Encoded by BioLORD-2023 (MPNet backbone, frozen) → 768-dim embedding
• Lightweight MLP classifier head trained on top of frozen embeddings

Fusion

• Late Fusion (main result): p_final = λ·p_bio + (1-λ)·p_llm, λ optimized on validation set
• Feature Fusion (ablation): MLP(concat(h_bio, h_llm))

Repository Structure

KEPPNet_open_source/
├── configs/
│   ├── model/                # 8 configs: 2 best + 6 ablation (BRCA + PRAD)
│   └── dataset/              # breast_kg.json, prostate_kg.json
├── src/
│   ├── models/
│   │   ├── pathpronet.py             # Structural branch model
│   │   └── custom/                   # Diagonal, CustomizedLinear, builder_utils
│   ├── data/
│   │   ├── dataset.py                # BnetData — genomic data loading
│   │   ├── dataload.py               # BnetDataLoader
│   │   └── processor/
│   │       ├── pathway_protein/      # KG-enhanced network builder (core)
│   │       ├── pathways/             # Reactome hierarchy + GMT reader
│   │       ├── protein/              # STRING PPI network
│   │       └── medical_data/         # Data preparation and splitting
│   ├── training/                     # Trainer with multi-task BCE loss
│   ├── evaluation/                   # Metrics (AUC, AUPRC, F1, etc.)
│   ├── interpretability/             # Attribution analysis (3 methods)
│   │   ├── attribution_methods.py    # DeepLIFT / IG / GradientSHAP
│   │   ├── run_attribution.py        # CLI entry point
│   │   ├── summarize_multi_attribution.py  # Stability analysis
│   │   └── attribution_perturbation.py     # Perturbation analysis
│   ├── utils/                        # Sankey, logging, animator, general
│   └── config/                       # Configuration system
├── scripts/
│   ├── train.py                      # Unified training entry point
│   ├── evaluate.py                   # Unified evaluation entry point
│   ├── run_demo.py                   # Minimal demo (runs on example_data/)
│   ├── train/                        # train_pathpronet.py, train_dual_branch.py
│   ├── evaluate/                     # eval_late_fusion.py, eval_llm_only_baselines.py, etc.
│   ├── prepare_data/                 # build_patient_summaries.py, build_biolord_embeddings.py, etc.
│   └── analyze/                      # Cross-branch support, complementarity, h_bio export
├── example_data/                     # Synthetic placeholder data (format reference)
├── docs/
│   ├── data_preparation.md
│   └── model_architecture.md
├── requirements.txt
└── LICENSE

Installation

git clone https://github.com/your-username/KEPPNet.git
cd KEPPNet_open_source
conda create -n keppnet python=3.10
conda activate keppnet
pip install -r requirements.txt

Quick Demo

Run a minimal forward-pass demo using synthetic example data (no real data required):

python scripts/run_demo.py

Data Preparation

Real patient data is not included due to data use agreements. See example_data/README.md for expected formats and docs/data_preparation.md for download instructions.

# 1. Build patient text summaries
python scripts/prepare_data/build_patient_summaries.py --cancer_type prostate

# 2. Build BioLORD embeddings
python scripts/prepare_data/build_biolord_embeddings.py --cancer_type prostate

# 3. Define experiment sets (dual_strict_set)
python scripts/prepare_data/define_experiment_sets.py

Training

# Train structural branch (PRAD)
python scripts/train.py --mode pathpronet --cancer_type prostate

# Train structural branch (BRCA)
python scripts/train.py --mode pathpronet --cancer_type breast

# Train full dual-branch model
python scripts/train.py --mode dual_branch

Evaluation

# PathProNet structural branch baseline
python scripts/evaluate.py --mode pathpronet --cancer_type prostate

# BioLORD-only baseline (LR / LinearSVM / MLP)
python scripts/evaluate.py --mode llm_only --cancer_type prostate

# Late fusion — main result
python scripts/evaluate.py --mode late_fusion --cancer_type prostate

# Feature-level fusion — ablation
python scripts/evaluate.py --mode feature_fusion --cancer_type breast

Interpretability Analysis

Three attribution methods are supported, all operating on the structural branch:

# DeepLIFT (recommended)
python src/interpretability/run_attribution.py --method deeplift --cancer_type prostate

# Integrated Gradients
python src/interpretability/run_attribution.py --method integratedgradients --cancer_type prostate

# GradientSHAP
python src/interpretability/run_attribution.py --method gradientshap --cancer_type prostate

# Multi-run stability analysis
python src/interpretability/summarize_multi_attribution.py \
    --model prad-best --dataset prostate --n-runs 10

# Attribution-guided perturbation analysis
python src/interpretability/attribution_perturbation.py \
    --cancer_type prostate --method deeplift --layer h2

Attribution outputs are saved to results/attribution/<method>_<cancer>/extracted/:

• gradient_importance_0.csv — gene-level attribution scores
• topk_layer_*.csv — top-k nodes per layer
• topk_summary.csv — combined summary across all layers
• node_importance_graph_adjusted.csv — full node importance table
• sankey.html — interactive Sankey diagram

Data and Weights Availability

Resource	Availability
Patient genomic data	Not included (cBioPortal, data use agreement)
BioLORD-2023 weights	HuggingFace: FremyCompany/BioLORD-2023
Trained model weights	Available upon reasonable request
Reactome pathway data	reactome.org/download-data (public)
STRING PPI data	string-db.org/cgi/download (public)

Code–Paper Correspondence

Component	Code Location
Structural branch (PathProNet)	src/models/pathpronet.py
KG-enhanced network builder	src/data/processor/pathway_protein/pathway_protein_kg_enhanced.py
Semantic branch (BioLORD)	scripts/prepare_data/build_biolord_embeddings.py
Late Fusion	scripts/evaluate/eval_late_fusion.py
Feature Fusion	scripts/evaluate/eval_feature_fusion.py
DeepLIFT / IG / GradientSHAP	src/interpretability/attribution_methods.py
Attribution stability	src/interpretability/summarize_multi_attribution.py
Perturbation analysis	src/interpretability/attribution_perturbation.py
Sankey visualization	src/utils/sankey_hybrid.py
Cross-branch support analysis	scripts/analyze/analyze_cross_branch_support.py

Citation

If you use KEPPNet in your research, please cite:

@article{keppnet2025,
  title   = {KEPPNet: Knowledge-Enhanced Pathway-Protein Network with Biomedical Language Model Fusion for Cancer Treatment Response Classification},
  author  = {[Authors]},
  journal = {[Journal]},
  year    = {2025}
}

License

MIT License. See LICENSE for details.