DOCSEARCHbyAlgolia
Submit Docs

SurvPath: Multimodal Patient Survival Prediction Framework

repository·main·Indexed 41 days ago

https://github.com/mahmoodlab/survpath

A multimodal framework for predicting patient survival by modeling interactions between biological pathways from transcriptomics and histology from Whole Slide Images (WSIs). It includes a training and evaluation pipeline via main.py, a SurvivalDatasetFactory for managing omics and histology data, and integration with the CLAM toolbox for WSI pre-processing using CTransPath.

Tokens
1.4K
Snippets
2
Records
6
Agent score
1%

What's inside SurvPath

  1. Configure Training-Validation Splits

    main

    SurvPath uses 5-fold cross-validation stratified by the site of histology slide collection.

    Using provided splits: Splits are located in the splits/5foldcv folder. Each folder contains splits_{k}.csv (where k = 1 to 5). In these files:

    • The first column contains TCGA Case IDs for training.
    • The second column contains TCGA Case IDs for validation.
    • Note: Slides from a single case are never split between training and validation sets.

    Using custom splits: If you define your own splits, they must follow the same two-column CSV format. To load these splits, use the return_splits function within the SurvivalDatasetFactory class.

  2. Process Whole Slide Images (WSIs) for SurvPath

    main

    WSIs must be pre-processed into feature vectors before being used as input to the SurvPath network. The workflow is as follows:

    1. Segmentation: Use Otsu's Segmentation on a downsampled WSI via OpenSlide to identify tissue regions.
    2. Patch Extraction: Extract 256 x 256 non-overlapping patches from the segmented tissue at the desired magnification.
    3. Feature Encoding: Use an SSL pre-trained Swin Transformer (CTransPath) to encode raw image patches into 768-dimensional feature vectors.
    4. Storage: Save these features as .pt files for each WSI.

    All WSI pre-processing should be performed using the CLAM toolbox.

  3. Install SurvPath on Linux using Anaconda

    main

    To set up the SurvPath environment on Linux (tested on Ubuntu 18.04), ensure you have an NVIDIA GPU with CUDA 11.0 and cuDNN 7.5. The following Python dependencies are required:

    • Python 3.8.13
    • h5py 2.10.0
    • matplotlib 3.6.3
    • numpy 1.21.6
    • opencv-python 4.5.1.48
    • openslide-python 1.2.0
    • openslide 3.4.1
    • pandas 1.4.2
    • pillow 9.0.1
    • PyTorch 1.6.5
    • scikit-learn 1.2.1
    • scipy 1.9.0
    • torchvision 0.13.1
    • captum 0.6.0
    • shap 0.41.0

  4. Run SurvPath training experiments

    main
    Training scripts for SurvPath and the baseline models described in the paper are located in the scripts directory. To run experiments, refer to the CVPR 2024 paper for the specific hyperparameters required for training.

  5. Run the SurvPath training and evaluation pipeline via main.py

    main

    The main.py script serves as the entrypoint for executing survival prediction experiments using the SurvPath model. It implements a k-fold cross-validation loop that handles dataset splitting, model training, validation, and result aggregation.

    When executed, the script performs the following workflow:

    1. Argument Parsing: Uses _process_args() and _prepare_for_experiment() to initialize configuration.
    2. Dataset Factory Initialization: Creates a SurvivalDatasetFactory instance which manages the loading of omics data and survival labels.
    3. Cross-Validation: Iterates through defined folds, retrieving train/val splits via args.dataset_factory.return_splits().
    4. Training/Validation: Executes the core training loop using _train_val().
    5. Result Persistence: Saves individual fold results as .pkl files and generates a summary.csv (or summary_partial_*.csv if the full k-fold is not completed) containing aggregated metrics like val_cindex, val_cindex_ipcw, val_BS, val_IBS, val_iauc, and val_loss.
    # The script is intended to be run as a standalone CLI entrypoint
# It expects arguments to be processed via _process_args()

python main.py --study <study_name> --label_file <path> --omics_dir <path> --modality <modality_type> ...

  6. Configure the SurvivalDatasetFactory

    main

    The SurvivalDatasetFactory is responsible for preparing the multimodal datasets (omics and histology) for the training pipeline. It is initialized within main.py using the following parameters:

    ParameterDescription
    studyThe specific study identifier (e.g., TCGA)
    label_filePath to the file containing survival labels
    omics_dirDirectory containing transcriptomics/pathway data
    seedRandom seed for reproducibility
    n_binsNumber of bins (mapped from args.n_classes)
    label_colThe column name in the label file used for survival data
    num_patchesNumber of histology patches to use
    is_mcatBoolean; set to True if coattn is in args.modality
    is_survpathBoolean; set to True if args.modality is "survpath"
    type_of_pathwayThe type of pathway data being used
    epsSmall epsilon value (default 1e-6)
    print_infoBoolean to toggle info printing

    It provides the method return_splits(args, csv_path, fold) to retrieve specific training and validation subsets for a given fold.

    args.dataset_factory = SurvivalDatasetFactory(
    study=args.study,
    label_file=args.label_file,
    omics_dir=args.omics_dir,
    seed=args.seed, 
    print_info=True, 
    n_bins=args.n_classes, 
    label_col=args.label_col, 
    eps=1e-6,
    num_patches=args.num_patches,
    is_mcat = True if "coattn" in args.modality else False,
    is_survpath = True if args.modality == "survpath" else False,
    type_of_pathway=args.type_of_path
)