README

This study investigates the performance of data preprocessing and enhancement methods in the context of deep learning on detecting cancerous cells in histopathologic scans of lymph node sections. Recent developments have given rise to deep learning models that already outperform a panel of trained pathologists in identifying cancerous cells in whole slide images. In an attempt to improve on these methods, we evaluate the effect of several different data enhancements on the performance of state-of-the-art rotation equivariant convolutional neural networks used for classification of slides from whole slide images. In particular, we investigate the effect of luminosity standardization, stain normalization, and concatenation of various nuclei segmentation masks on different networks. While stain normalization markedly increased model performance, the effects of one or more segmentation masks had a negligible, albeit positive, effect on the performance. In addition, we observe that the attentive network failed to outperform its non-attentive variant, in spite of a significantly greater number of parameters.

setup

.env

We use .env files to keep track of machine-specific variables. Create a .env in the root of this project with the following values set:

PROJECT_DIR=/path/to/root/of/project/
DATA_DIR=/path/to/root/of/project/data/
SRC_DIR=/path/to/src/dir/ # where to install any packages from source

To access these variables in python code run:

from decouple import config
config("PROJECT_DIR")

virtualenv

Initialize a virtualenv in python3.8

virtualenv ~/.virtualenvs/pcam --python=python3.8
source ~/.virtualenvs/pcam/bin/activate

pytorch

Install pytorch using the following command (but look at https://pytorch.org/ if you’re not using Linux).

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu116

wandb

Set up an wandb account on. To setup wandb, run:

pip install wandb
wandb login

custom code

Run the following to install the contents under src/ as a package:

pip install -e .

other requirements

After having run this, install the rest of the requirements using:

pip install -r requirements.txt

data

Download this drive folder as a .zip. Move out of the folder, right click on this folder, and select Download. This will download both a .zip and a .gz named like pcamv1-<timestamp>-001.zip and *gz. The .gz file is likely to fail as it is too big. You can use this link to download it separately.

Find the exact names of the files and run the following:

source .env
mkdir -p $DATA_DIR
unzip ~/Downloads/pcamv1-20220914T134745Z-001.zip -d /tmp/ # change the exact name of the file here
mv /tmp/pcamv1/* $DATA_DIR/
gunzip $DATA_DIR/*gz
#mv ~/Downloads/ add .gz instructions

hovernet

source .env
cd $SRC_DIR
git clone https://github.com/vqdang/hover_net

And download the file hovernet_fast_pannuke_type_tf2pytorch.tar from here and put it in pretrained_hovernet_weights/ dir in project directory (make if it does not exist yet).

script usage

merge_segmentations.py

Makes sure the per-sample saved output of segmentation network are merged into a tensor of size <nof_samples> x 96 x 96, stored under DATA_DIR / <model_name>_<split_name>.pt.

run_segmentation.py

Preprocesses the data to be used by HoVerNet and runs HoVerNet. Takes model_name (options defined in src.hovernet_utils.MODEL_NAME2FPATH) and split_name. start_idx and end_idx allow you to specifically only run it on a subset of the data defined by the given range.

paulodder/pcam