Run QERA on Your Own Machine

This is a user guide. Please follow the steps below:

1. Feature Extraction

Extract features using your model according to the PrePATH method and save them as HDF5 (.h5) files.

2. Configuration Setup

Specify your desired parameters in ./config/main_config.yml. This configuration file contains four sections: main_wsi, main_roi, main_sa, and main_ret, corresponding to slide classification, tile classification, survival analysis, and tile retrieval, respectively. Each section requires specific user-defined parameters:

• For main_wsi:
  • root: Path to the root directory where WSI feature files are stored.
• For main_roi:
  • root: Path to the root directory of the tile dataset.
  • user_path: Path to the root directory containing your model definition files. Defaults to ./models. Place your model definition file (model.py) in this folder.
    • The model.py file must define three elements:
      1. embed_dim: Model output embedding dimension.
      2. model: An instantiated model object.
      3. transform: Preprocessing transform for input images.
    • Example model.py:

      import torch
      import timm
      from torchvision import transforms
      
      embed_dim = 1024
      transform = transforms.Compose([
          transforms.ToTensor(),
          transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
      ])
      model = timm.create_model("vit_large_patch16_224", img_size=224, patch_size=16, init_values=1e-5, num_classes=0, pretrained=False)
      

    • Model weights should be placed in the checkpoints subdirectory within user_path (default: ./models/checkpoints). The weight file name is specified by model_name (defaults to "model.bin").
• For main_sa:
  • fea_dir: Path to the root directory of extracted WSI features.
  • feat_size: Dimensionality of the features (must be specified).
• For main_ret:
  • root, user_path, and model_name: Have the same meanings as described above for main_roi.

Example configurations for all sections can be found within the project.

3. Evaluation Dataset Configuration

For each evaluation dimension (Privacy, Fairness, OOD), you can specify the datasets to use in the corresponding YAML files located in ./config/:
* privacy.yml
* fairness.yml
* ood.yml

By default, all public datasets used in our paper are included. You can remove entries to speed up evaluation.

4. Running Evaluations

Execute the evaluation scripts directly using Python commands. No additional arguments are needed.

Navigate to the project directory first:

git clone https://github.com/birkhoffkiki/PrePATH.git
cd QERA
conda create --name qera python=3.10
conda activate qera
bash pip_install.sh

Then run the desired script:

# Evaluate Privacy:
python main_privacy.py
# Evaluate Fairness:
python main_fairness.py
# Evaluate OOD (Out-of-Distribution):
python main_ood.py

In the ./labels directory, we have provided the label information used in the experiment. You can view all label divisions under ./labels/all_labels.

5. Output Results

By default, results are saved in the ./results directory. You can customize the output location by modifying the following parameters in main_config.yml:
* output_dir
* task
* result_dir