Code for Kluger Lab project to classify breast cancer tissue into HER2+ or HER2- using CNNs. (Work in progress)

• Python 3.4 or higher
• Numpy
• PIL
• matplotlib
• tensorflow
• tensorflow-hub
• OpenSlide

Openslide can be installed by following the instructions at https://openslide.org/download/. All other libraries can be installed via pip.

Assumptions: The library assumes that the user has available a collection of whole-slide images (WSIs) whose region of interests have been annotated using the open source program QuPath.

Usage: Starting from QuPath, the user should first open their qpproj file encompassing their annotations and then run the extract_polygons.groovy script from QuPath's automation interface. Doing so will generate a folder for each slide containing CSV files with the coordinates of that slide's annotations.

Usage: python3 construct_training_dataset

Description: Creates a dataset of non-overlapping patches from the slides.

Relevant Constants:

* `SLIDE_FILE_DIRECTORY`
* `SLIDE_FILE_EXTENSION`
* `PATCH_OUTPUT_DIRECTORY` 
* `LABEL_FILE_PATH`
* `ANNOTATION_CSV_DIRECTORY`

Usage: python3 train_network_kfold.py. Outputs trained model files to MODEL_FILE_FOLDER found in constants.py.

Description: Retrains the final layer of a pre-trained model (ex. Inceptionv3, ResNet50) to classify patches of whole-slide images. To better evaluate the robustness of the model, the script will train k models, each with a different train-test split. Train/test data split are determined as in k-fold cross validation. A good starting point is k = 5 giving a train/test ratio of 80%/20%.

Relevant Constants:

* `NUM_FOLDS`
* `TFHUB_MODULE`
* `HOW_MANY_TRAINNG_STEPS`
* `RANDOM_CROP`
* `RANDOM_SCALE`
* `RANDOM_BRIGHTNESS`
* `FLIP_LEFT_RIGHT`
* `MODEL_FILE_FOLDER`
* `INPUT_LAYER`
* `OUTPUT_LAYER`
* `TEST_SLIDE_FOLDER`
* `TEST_SLIDE_LIST`

Usage: python3 create_visualization_helper_files.py

Description: Evaluates model on testing data and saves results in helper files used in the visualization scripts (below).

Relevant Constants:

* `TEST_SLIDE_FOLDER`
* `MODEL_FILE_FOLDER`
* `LABEL_FILE_PATH`
* `INPUT_LAYER`
* `OUTPUT_LAYER`
* `HISTOGRAM_FOLDER`
* `FOLD_VOTE_CONTAINER_LISTS`
* `PATCH_CONFIDENCE_FOLD_SUBFOLDER`
* `CONFIDENCE_CONTAINER_LIST`
* `PATCH_NAME_TO_CONFIDENCE_MAP`
* `POS_SLIDE_CONFIDENCE_LISTS`
* `NEG_SLIDE_CONFIDENCE_LISTS`

Usage: python3 draw_histograms.py. Outputs PNG files in the directory HISTOGRAM_FOLDER as specified in constants.py.

Description: Display the relative frequencies of patches for each test patient classified as positive by the network for a given fold.

Relevant Constants:

* `POS_SLIDE_CONFIDENCE_LISTS`
* `NEG_SLIDE_CONFIDENCE_LISTS`
* `HISTOGRAM_FOLDER`
* `HISTOGRAM_SUBFOLDER` 

Example:

Usage: python3 draw_kfold_roc_curve.py. Outputs PNG file in the directory from which the script is run.

Description: Computes ROC curves for each of the k trained networks. Displays these as well as averages them into a single curve with accompanying error bars.

Relevant Constants:

* `FOLD_VOTE_CONTAINER_LISTS_PATH`

Example:

Usage: python3 patch_visualizer.py --which_fold = placeholder_fold_number. Output displays in new window, patches can be scrolled through using arrow keys, as well as number keys to jump to the corresponding decile (ex. hitting 4 goes to the 40th percentile). Hitting the '-' key moves to the slide with the highest confidence.

Description: Displays patches for test patients in a given fold. Patches are shown with their confidence value for being classified as positive.

Relevant Constants:

* `CONFIDENCE_CONTAINER_LIST`

Example:

Usage: python3 view_confidence_heatmaps.py --which_fold = placeholder_fold_number. Output displays in a new window, slides can be scrolled through using arrow keys.

Description: Overlays heatmaps onto whole slide image thumbnails describing the confidence of patches being classified as positive.

Relevant Constants:

* `PATCH_NAME_TO_COORDS_MAP`
* `SLIDE_NAME_TO_TILE_DIMS_MAP`
* `SLIDE_NAME_TO_PATCHES_MAP`
* `PATCH_NAME_TO_CONFIDENCE_MAP`
* `TEST_SLIDE_FOLDER`
* `TEST_SLIDE_LIST`
* `SLIDE_FILE_DIRECTORY` 

Example: