User Guide for ecPICK – Deep Learning-based ecDNA Prediction Tool in Pathological Sections

Introduction

This is a deep learning-based tool designed to predict the content and localization of ecDNA in HE-stained pathological section images (SVS/TIF/JPG files). It primarily offers two core functions:

1. Predict ecDNA content and localization from input images
2. Perform SHAP interpretability analysis on images

Installation

Ensure Python (version 3.11.10 or higher) is installed in your environment.

git clone https://github.com/zhangheng43/ecPICK  
cd ecPICK  
pip install -r requirements.txt

Download H5 Model file combined_model.h5 here and place it in the model/ directory.

Usage

1. Predict ecDNA Content and Localization from Input Images

Used to analyze pathological section files in SVS/TIF/JPG formats, generating prediction results and visualized images.

python run_model.py predict_svs --input <path_to_image_file> --output <output_directory> --downsample <downsampling_rate>  

Parameter descriptions: --input: Required. Path to the input image file, supporting SVS/TIF/JPG formats. --output: Required. Directory for saving output results. --downsample: Optional. Downsampling rate for output images (default: 1).

Output contents:

• Cropped image patches
• Prediction result Excel file (predict_result.xlsx)
• Annotated visualization image (output.png)

2. Image SHAP Interpretability Analysis

Used to generate interpretability analysis of model predictions.

python run_model.py shap --input <input_file_path> --output <output_path> --max_eval <max_evaluation_count>  

Parameter descriptions:

• --input: Required. Path to the input file.
• --output: Required. Path for saving output files.
• --max_eval: Optional. Maximum number of evaluations (default: 500).

Usage Examples

1. Run pathological section prediction:

python run_model.py predict_svs --input ./samples/example.svs --output ./results --downsample 2

2. Run SHAP analysis:

python run_model.py shap --input ./samples/test.jpg --output ./results/shap_result --max_eval 1000

Notes

1. Ensure OpenSlide DLL files are installed correctly.
2. The output directory must have write permissions.
3. Processing large SVS files may take a significant amount of time (approximately 10 minutes).
4. It is recommended to adjust the downsample parameter based on actual needs to balance image quality and file size.