<img src="https://img.shields.io/badge/PyTorch-EE4C2C?style=flat-square&logo=Pytorch&logoColor=white"/></a>

---

PathoPatch:

Accelerating Artificial Intelligence Based Whole Slide Image Analysis with an Optimized Preprocessing Pipeline

<div align="center">

Installation • Usage • Examples • Roadmap • Citation

</div>

---

<p align="center"> <img src="./docs/preprocessing_pipeline.png"/> </p>

---

Installation

[!CAUTION] Please use a Python Version smaller than 3.12, we recommend 3.10

Prerequisite

1. Openslide (>= 3.4.1) needs to be installed (either directly https://openslide.org/download/ or via conda)<details> <summary>OpenSlide conda</summary> - Recommended: conda install conda-forge::openslide=4.0.0 for DICOM support - Generic/minimum version: conda-forge::openslide>=3.4.1

   </details>

2. Openslide python: pip install openslide-python

3. Optional for speedup:

   • We recommend the following procedure to achieve to best speed-up:
     1. Install cupy for your cuda version, E.g., pip install cupy-cuda12x (CUDA >12.x) or pip install cupy-cuda11x (CUDA 11.0-11.8)
     2. Install cuCIM via pip: pip install cucim. We used the following version: pip install cucim==23.6.0
   • Not recommended but may be a helpful ressource if problems occur: Official cuCIM installation instructions

PIP-Package

The package can be found here: https://pypi.org/project/pathopatch/ Installation: pip install pathopatch

Troubleshooting

• torch: If you get problems with torch, install it accordingly for your setup by follow this instructions: https://pytorch.org/get-started/previous-versions/. After you have installed pytorch, some packages might have get an update, therefore please reinstall pathopatch: pip install --force-reinstall pathopatch

Development/from source

1. Clone the repository:
2. Create a conda environment with Python 3.10.12 version and install conda requirements: conda env create -f environment.yaml -vv. You can change the environment name by editing the name tag in the environment.yaml file. This step is necessary, as we need to install Openslide with binary files. This is easier with conda. Otherwise, installation from source needs to be performed and packages installed with pi
3. Activate environment: conda activate pathopatch_env
4. Optional: cuCIM Run conda install -c rapidsai cucim inside your conda environment. This process is time consuming, so you should be patient. Also follow their official guideline if any problems occur.

Commiting/Linting

1. Install pre-commit with pre-commit install This activates pre-commit hooks, files are edited when commited and need to added again as they might change

Usage

We provide different use cases - Offline-Dataset (Store on Disk :floppy_disk:) and Inference-Dataset for :zap: PyTorch :zap:

In our Pre-Processing pipeline, we are able to extract quadratic patches from detected tissue areas, load annotation files (.json) and apply color normlizations. We make use of the popular OpenSlide library, but extended it with the RAPIDS cuCIM framework for a speedup in patch-extraction.

We support all OpenSlide file formats + .dcm-File format (DICOM), by utilizing wsidicom and wsidicomizer.

Explanations for use cases :floppy_disk: vs :zap:

<details> <summary>Offline-Dataset</summary>

In general, our framework has the following commands registered in your shell:

wsi_extraction: Extract patches with specific configuration and store them on the disk annotation_conversion: Can be used to convert annotations macenko_vector_generation: To generate new macenko vectors for a new dataset, if custom vectors are tend to be used

Parameter handover and CLI

Option 1: Config.yaml

Arguments are passed via CLIs. In addition to the CLI, also a configuration file can be passed via

wsi_extraction --config path/to/config.yaml

Exemplary configuration file: patch_extraction.yaml.

Option 2: CLI

The CLI of the main script for patch extraction (wsi_extraction) is as follows:

wsi_extraction [-h]
    [--wsi_paths WSI_PATHS]
    [--wsi_filelist WSI_FILELIST]
    [--output_path OUTPUT_PATH]
    [--wsi_extension {svs}]
    [--config CONFIG]
    [--patch_size PATCH_SIZE]
    [--patch_overlap PATCH_OVERLAP]
    [--target_mpp TARGET_MPP]
    [--target_mag TARGET_MAG]
    [--downsample DOWNSAMPLE]
    [--level LEVEL]
    [--context_scales [CONTEXT_SCALES ...]]
    [--check_resolution CHECK_RESOLUTION]
    [--processes PROCESSES]
    [--overwrite]
    [--annotation_paths ANNOTATION_PATHS]
    [--annotation_extension {json,xml}]
    [--incomplete_annotations]
    [--label_map_file LABEL_MAP_FILE]
    [--save_only_annotated_patches]
    [--save_context_without_mask]
    [--exclude_classes EXCLUDE_CLASSES]
    [--store_masks]
    [--overlapping_labels]
    [--normalize_stains]
    [--normalization_vector_json NORMALIZATION_VECTOR_JSON]
    [--min_intersection_ratio MIN_INTERSECTION_RATIO]
    [--tissue_annotation TISSUE_ANNOTATION]
    [--tissue_annotation_intersection_ratio TISSUE_ANNOTATION_INTERSECTION_RATIO]
    [--masked_otsu]
    [--otsu_annotation OTSU_ANNOTATION]
    [--filter_patches FILTER_PATCHES]
    [--apply_prefilter APPLY_PREFILTER]
    [--log_path LOG_PATH]
    [--log_level {critical,error,warning,info,debug}]
    [--hardware_selection {cucim,openslide,wsidicom}]
    [--wsi_magnification WSI_MAGNIFICATION]
    [--wsi_mpp WSI_MPP]

options:
  -h, --help            show this help message and exit
  --wsi_paths WSI_PATHS
                        Path to the folder where all WSI are stored or path to a
                        single WSI-file. (default: None)
  --wsi_filelist WSI_FILELIST
                        Path to a csv-filelist with WSI files (separator: `,`), if
                        provided just these files are used.Must include full paths
                        to WSIs, including suffixes.Can be used as an replacement
                        for the wsi_paths option.If both are provided, yields an
                        error. (default: None)
  --output_path OUTPUT_PATH
                        Path to the folder where the resulting dataset should be
                        stored. (default: None)
  --wsi_extension {svs,tiff,tif,bif,scn,ndpi,vms,vmu}
                        The extension types used for the WSI files, the options
                        are: ['svs', 'tiff', 'tif', 'bif', 'scn', 'ndpi', 'vms',
                        'vmu'] (default: None)
  --config CONFIG       Path to a config file. The config file can hold the same
                        parameters as the CLI. Parameters provided with the CLI are
                        always having precedence over the parameters in the config
                        file. (default: None)
  --patch_size PATCH_SIZE
                        The size of the patches in pixel that will be retrieved
                        from the WSI, e.g. 256 for 256px (default: None)
  --patch_overlap PATCH_OVERLAP
                        The percentage amount pixels that should overlap between
                        two different patches. Please Provide as integer between 0
                        and 100, indicating overlap in percentage. (default: None)
  --target_mpp TARGET_MPP
                        If this parameter is provided, the output level of the WSI
                        corresponds to the level that is at the target microns per
                        pixel of the WSI. Alternative to target_mag, downsaple and
                        level. Highest priority, overwrites all other setups for
                        magnifcation, downsample, or level. (default: None)
  --target_mag TARGET_MAG
                        If this parameter is provided, the output level of the WSI
                        corresponds to the level that is at the target
                        magnification of the WSI. Alternative to target_mpp,
                        downsaple and level. High priority, just target_mpp has a
                        higher priority, overwrites downsample and level if
                        provided. (default: None)
  --downsample DOWNSAMPLE
                        Each WSI level is downsampled by a factor of 2, downsample
                        expresses which kind of downsampling should be used with
                        respect to the highest possible resolution. Medium
                        priority, gets overwritten by target_mag and target_mpp if
                        provided, but o