PatchSorter

PatchSorter is an open-source digital pathology tool for histologic object labeling.

Requirements

Tested with Python 3.8 and Chrome

Requires: 1. Python 2. pip

And the following additional python package: 1. FlaskSQLAlchemy 2. scikitimage 3. scikitlearn 4. opencvpythonheadless 5. scipy 6. requests 7. SQLAlchemy 8. torch 9. torchvision 10.FlaskRestless 11. numpy 12. Flask 13. umap_learn 14. Pillow 15. tensorboardX 16. ttach 17. albumentations 18. config 19. dill 20. Shapely 21. tables 22. tqdm

You can likely install the python requirements using something like (note python 3+ requirement): pip3 install -r requirements.txt

The library versions have been pegged to the current validated ones. Later versions are likely to work but may not allow for cross-site/version reproducibility

We received some feedback that users could installed torch. Here, we provide a detailed guide to install Torch

Torch's Installation

The general guides for installing Pytorch can be summarized as following: 1. Check your NVIDIA GPU Compute Capability @ https://developer.nvidia.com/cuda-gpus 2. Download CUDA Toolkit @ https://developer.nvidia.com/cuda-downloads 3. Install PyTorch command can be found @ https://pytorch.org/get-started/locally/

Run

E:\<<folder_path>>\PatchSorter>python3 -m patchsorter By default, it will start up on localhost:5555

Warning: virtualenv will not work with paths that have spaces in them, so make sure the entire path to env/ is free of spaces.

Config Sections

There are many modular functions in QA whose behaviors could be adjusted by hyper-parameters. These hyper-parameters can be set in the config.ini file

• [common]
• [flask]
• [sqlalchemy]
• [pooling]
• [make_patches]
• [frontend]
• [train_tl]
• [embed]

Naming Conventions

• image name eg : train_1.png
• mask image name eg : train1mask.png
• csv file name eg: train_1.csv

Docker requirements

Docker is a set of platform as a service products that use OS-level virtualization to deliver software in packages called containers. Containers are isolated from one another and bundle their own software, libraries and configuration files.

In order to use Docker version of QA, user needs: 1. Nvidia driver supporting cuda. See documentation, here. 2. Docker Engine. See documentation, here 3. Nvidia-docker https://github.com/NVIDIA/nvidia-docker

Depending on your cuda version, we provide Dockerfiles for cuda_10 and cuda_11.

To start the server, run either: docker build -t patchsorter -f cuda_10/Dockerfile . or docker build -t patchsorter -f cuda_11/Dockerfile . from the PatchSorter folder.

When the docker image is done building, it can be run by typing:

docker run --gpus all -v /data/$CaseID/PatchSorter:/opt/PatchSorter -v /data/$CaseID/<location_of_images>/:/opt/imagedata -p 5555:5555 --shm-size=8G patchsorter

In the above command, -v /data/$CaseID/PatchSorter:/opt/PatchSorter mounts the PS on host file system to the PS inside the container. /data/$CaseID/PatchSorter should be the PS path on your host file system, /opt/PatchSorter is the PS path inside the container, which is specified in the Dockerfile. If image files will be uploaded using the upload folder option image directory needs to be mounted as well. /data/$CaseID/<location_of_images>/ would be the path for images on your host file system, /opt/imagedata will be the path for the images inside the container.

Note: This command will forward port 5555 from the computer to port 5555 of the container, where our flask server is running as specified in the [config.ini]. The port number should match the config of running PS on host file system.

Usage Documentation

See wiki
User Manual
FAQ

Citation

Please use below to cite PatchSorter if you find this repository useful or if you use the software shared here in your research.

Walker, C., Talawalla, T., Toth, R. et al. PatchSorter: a high throughput deep learning digital pathology tool for object labeling. npj Digit. Med. 7, 164 (2024). https://doi.org/10.1038/s41746-024-01150-4.

Paper available at Nature Digital Medicine.