OPSCCnet

Welcome to the reposiroty of OPSCCnet! OPSCCnet is an open source tool that allows users to determine HPV-association in dedicated head and neck tumors. In its current version, OPSCCnet is built around the most used and most succesfull open-source tool for digital pathology (QuPath, at the time of latest commit at version 0.4.3), which has been built by Pete Bankhead from the The University of Edinburgh Shoutout.

📋 Table of content

1. Requirements
2. Installation
3. Configuration of paquo
4. How to run OPSCCnet browser
5. How to run OPSCCnet using command line
6. Examples
7. Shoutout
8. Citing
9. License
10. Acknowledgements

🚧 Requirements

Please consider that OPSCCnet has been tested using unix based systems (MacOS and Ubuntu). A GPU is advantegous but not necessary. OPSCCnet can be run using regular clients.
Requirements:

• Unix based system
• QuPath [anything above 0.3.1 should work, tested 0.4.3 at the time of latest commit] installed on your system
• How to install QuPath 0.4.3
• Anaconda (recommended) / Miniconda installed on your system
• How to install anaconda
• git installed / or manually downloaded the OPSCCnet repository
• How to install git

Clone repository

git clone https://github.com/OPSCCnet/OPSCCnet.git

🧨 Installation

conda create --name OPSCCnet python=3.9
conda activate OPSCCnet
pip install -r requirements.txt # please only use this if you are running a non MacOS system
pip install -r requirementsMacOS.txt # MacOS users: please use this

OPSCCnet is using paquo to generate project files. It is necessary for paquo to know where QuPath is installed. Please read the docs where to put the QuPath directory path in order to let paquo access it.

• You have cloned / downloaded the OPSCCnet.git repository and installed the pip requirements
• You have installed QuPath 0.4.3 (see above) on your system
• You now have a directory where OPSCCnet is installeg, e.g. /media/somewhere/OPSCCnet

It appears there is some misunderstanding of how to configure paquo, I have put a description below on how to set the path.

If you have installed QuPath on a MacOS system with default parameters, you can skip this part!

🧨 Configuration of paquo

cd /media/somewhere/OPSCCnet
python -m paquo config --list --default
python -m paquo config -l -o .
nano .paquo.toml

👇

💁 Details on how to use nano and set up the path

skip this part if you have installed QuPath on a MacOS system using the default location. //// Using nano: STRG + O writes the output and STRG + X exits the file. //// Once you have opened the paquo configure file, set the QuPath dir, e.g. qupath_dir "/home/sebastian/DeepLearning_Image/QuPath043/QuPath-0.4.3-Linux/QuPath/" [Please pay attention! The QuPath dir to be set for OPSCCnet either in the browser version or the command line version would be QuPathApp="/home/sebastian/DeepLearning_Image/QuPath043/QuPath-0.4.3-Linux/QuPath/bin/QuPath"; so they differ!]

• You have put a reference of your QuPath APP to paquo (you don't have to do this if you have installed it on a MacOS system with default parameters; otherwise please see above)

You are ready to go

🎯 How to run OPSCCnet using a browser

If you are using a MacOS system, the correct directory to set for the QuPath app in the browser is "/Applications/QuPath.app/Contents/MacOS/QuPath"

streamlit run OPSCCnet.py

🎯 How to run OPSCCnet using the command line

💁 Prepare the bash script of run_OPSCCnet.sh

Please set the QuPath App directory, e.g. "QuPathApp="/home/sebastian/DeepLearning_Image/QuPath043/QuPath-0.4.3-Linux/QuPath/bin/QuPath" in the run_OPSCCnet.sh //// If you are using a MacOS System and have installed QuPath using the system defaults, this path is "QuPathApp="/Applications/QuPath.app/Contents/MacOS/QuPath"

chmod +x run_OPSCCnet.sh #If you are starting the bash script for the first time, you need to include "chmod +x run_OPSCCnet.sh"
./run_OPSCCnet.sh -i '/media/sebastian/8e545a02-8515-436b-9abe-f0b9ba1489d1/WSI/test_folder/WSI' -o '/media/sebastian/b4215009-f647-4cf3-97fe-038c17c9f61e/OPSCCnet' -p '/media/sebastian/8e545a02-8515-436b-9abe-f0b9ba1489d1/WSI/test_folder/test'

🎯 Examples

OPSCCnet has essentially three parts:

• Segmentation of viable tumor areas using a FPN with a ResNet-18 encoder
• Classification of image tiles for HPV-association using a ResNet-18
• Visualizing HPV-association on whole slide level (WSI) and giving tabular data as output for individual WSI's

Cite our work

Klein, S., Wuerdemann, N., Demers, I. et al. Predicting HPV association using deep learning and regular H&E stains allows granular stratification of oropharyngeal cancer patients. npj Digit. Med. 6, 152 (2023).

Please get me to the article

Shoutout

You should visit this page which is a great ressource for questions regarding QuPath. Snippets and parts from scripts have been copied from there.

• A big shoutout to Pete Bankhead and his crew for making this available to the community
• Recently, Pete Bankhead has published a book, I have not had the chance to take a look, but I would recommend it either way
• A big shoutout to segmentation models for PyTorch, which has been built by Pavel Iakubovskii

Licence

OPSCCnet is made for academic bodies, and its research use only. This is not a medical product.

Acknowledgements

Figures were created with https://biorender.com/ and Adobe illustrator version 26.4.