EvoPath

A representation-grafting framework that transforms pathology slide-level foundation models from monolithic, encoder-locked systems into composable and continuously evolving infrastructure for precision oncology.

Overview

Pathology foundation models are often organized as two separate tiers: Patch-FMs learn local patch representations, while Slide-FMs learn slide-level context from a fixed native patch encoder. This creates a practical barrier to model evolution: stronger or newer Patch-FMs cannot be directly used by a pretrained Slide-FM because their feature manifolds are mismatched.

EvoPath addresses this by learning a lightweight representation grafting module that maps source Patch-FM features into the input space expected by a frozen Slide-FM. The framework decomposes source features into an alignment component and a complementary component, enabling the Slide-FM to reuse its pretrained slide-level context while absorbing discriminative information from stronger or modality-specific Patch-FMs.

EvoPath is designed to support:

• Temporal evolution: upgrade a frozen Slide-FM with newer or stronger Patch-FMs.
• Cross-modality evolution: transfer H&E slide-level context to other pathology modalities.
• Lightweight training: update only EvoPath heads and the final task head while keeping the Slide-FM frozen.

Installation

Python 3.10 or 3.11 is recommended.

conda create -n evopath python=3.10 -y
conda activate evopath

cd /path/to/EvoPath-open-source
pip install -r requirements.txt

By default, EvoPath loads slide encoders through Hugging Face transformers:

• TITAN: MahmoodLab/TITAN
• PRISM: paige-ai/Prism

Some models may require Hugging Face access approval or authentication:

huggingface-cli login

Data Preparation

Raw WSIs and extracted features are not included. To reproduce a run, prepare:

1. WSI files for TCGA-BRCA and CPTAC-BRCA.
2. Patch-level feature H5 files from the native Patch-FM paired with the target Slide-FM.
3. Patch-level feature H5 files from the source Patch-FM to be grafted by EvoPath.
4. Label CSV files.
5. Split CSV files.

Native Patch-FM features are used as alignment targets during training. After training, EvoPath prediction only depends on the source Patch-FM features, patch coordinates, and the frozen Slide-FM; the provided training/evaluation scripts still load both feature sets for a uniform data pipeline.

We recommend using TRIDENT for WSI preprocessing and feature extraction:

https://github.com/mahmoodlab/TRIDENT

TRIDENT provides WSI tissue segmentation, patch coordinate generation, and patch/slide embedding extraction. Its README documents one-command processing with --task all and stage-by-stage processing.

Expected Feature Layout

EvoPath expects feature directories in the following format:

<feature_base>/
`-- 20x_512px_0px_overlap/
    |-- features_conch_v15/
    |   |-- <slide_id>.h5
    |   `-- ...
    |-- features_hoptimus1/
    |   |-- <slide_id>.h5
    |   `-- ...
    |-- features_virchow2/
    |   |-- <slide_id>.h5
    |   `-- ...
    `-- features_virchow/
        |-- <slide_id>.h5
        `-- ...

Each slide H5 file must contain:

features: float array, shape [num_patches, feature_dim]
coords:   int array,   shape [num_patches, 2]

Optional but recommended:

coords.attrs["patch_size_level0"]

If this attribute is missing, the loader uses 512, matching the default 20x, 512-pixel grid. The same slide_id must exist in the primary and secondary feature directories. EvoPath uses H5 coordinates to align primary and secondary patch features when lengths differ, but reproducibility is best when all encoders are extracted from the same patch grid.

Feature dimensions and example feature-base paths are configured in scripts/tasks.json. The bundled configuration uses placeholder paths under data/; edit them to match your local labels, feature directories, and split files before running. Add new encoders to feat_dim_map if needed.

Labels, Splits, and Configuration

Each label CSV must contain slide_id, case_id, and label. Labels are mapped as IDC: 0 and ILC: 1.

Each split CSV should contain:

train,val,test

The train and val columns are matched against TCGA-BRCA labels. The test column is matched against CPTAC-BRCA labels. The provided scripts use --k 10 by default. Before running, edit scripts/tasks.json to point to your label files, feature directories, and split directory.

The shell scripts build feature directories as:

DATA_ROOT_DIR=<train_base>/features_<PRIMARY_FEATURE>
DATA_ROOT_DIR2=<train_base>/features_<SECONDARY_FEATURE>
EXTERNAL_DATA_ROOT_DIR=<test_base>/features_<PRIMARY_FEATURE>
EXTERNAL_DATA_ROOT_DIR2=<test_base>/features_<SECONDARY_FEATURE>

Training

The default training settings mirror the reported experimental setup:

• Optimizer: AdamW
• Learning rate: 2e-4
• Batch size: one slide
• Maximum epochs: 10
• Early stopping: enabled
• Hidden dimension: 1024
• Maximum token context length: 512
• Auxiliary loss weights: W_ALIGN=1, W_DISTILL=4, W_ORTHO=4, W_INFO=4
• Complementary fusion weight: W_COMP=2
• Slide-FM mode: frozen (lp)
• Sampling: the provided scripts enable class-balanced weighted sampling for the imbalanced BRCA_TYPE training set.

EvoPath-TITAN

bash scripts/evopath_titan.sh BRCA_TYPE conch_v15 hoptimus1 1.0

EvoPath-PRISM

bash scripts/evopath_prism.sh BRCA_TYPE virchow virchow2

For a one-fold smoke test, provide splits_0.csv and pass:

EXTRA_ARGS="--k 1 --overwrite" \
bash scripts/evopath_titan.sh BRCA_TYPE conch_v15 hoptimus1 1.0

Outputs

Results are written to:

results/<exp_code>/s<seed>_<test_name>/

Expected files:

training_log.log
experiment_<exp_code>.txt
split_<fold>_results_test.pkl
summary.csv

summary.csv contains:

test_auroc, test_f1, test_kappa, test_bacc

License

This project is released under the MIT License. See LICENSE.

Acknowledgments

This project builds on ideas, tools, and model interfaces from the following open-source resources:

• CLAM: https://github.com/mahmoodlab/CLAM
• TRIDENT: https://github.com/mahmoodlab/TRIDENT
• TITAN: https://github.com/mahmoodlab/TITAN
• PRISM: https://huggingface.co/paige-ai/Prism