Package overview

Package dplabtools provides a set of Python classes for automating tasks typical in Digital Pathology experiments. The package has been thoughtfully designed, keeping scalability, performance and ease of future maintenance in mind. Currently the package is covered by over 850 test cases with over 2450 assertions.

Main features

  • Support for different Whole Slide Image (WSI) reading libraries by introducing the concept of GenericSlide class.

  • WSI foreground/background Masks generation.

  • Support for different Patch locations/sampling methods and the ability to generate patch location preview images.

  • Efficient Patch Extraction methods for calculated patches.

  • Support for Multi resolution patches (MRP) across the whole package.

  • Inference class capable of running trained models on WSIs.

  • Integrated Heatmaps class for visualizing inference results.

  • Support for the most popular WSI Annotations types.

  • Specialized Pool classes for parallel WSI processing.

  • Extensive but not exhausting documentation :-)

Installation

To install the latest version available in the linked repository:

pip install dplabtools

To install any previous/specific version:

pip install dplabtools==X.Y.Z

All required dependencies will be installed automatically, apart from PyTorch, which should be installed manually if dplabtools classes that depend on it are to be used. In that case, it is recommended that PyTorch be installed first, followed by dplabtools.

Note

To function properly, OpenSlide Python package requires OpenSlide binaries to be installed. This installation process varies between operating systems, more details can be found at openslide.org.

Code repository

Package dplabtools is hosted on GitHub.

Requirements

Package dplabtools is developed on Linux and tested on Linux. While most of the classes are expected to work on other operating systems, there are also areas which have a high likelihood of not functioning properly (e.g. low level multiprocessing code).

General requirements:

  • Any Linux operating system

  • Currently supported Python versions: 3.10 - 3.13

  • Currently supported PyTorch versions: 1.x - 2.x

Note

Python 3.14 is not currently supported.

Conventions

The following conventions are used across the package:

  • All user classes should be called with keyword-only arguments e.g.:

s = GenericSlide(wsi_file="file1.svs")

not: s = GenericSlide("file1.svs").

Typical error when this convention is not followed:

TypeError: __init__() takes 1 positional argument but N were given

  • All strings representing colors (e.g. “red”, “blue”) are defined in the Matplotlib library.

Acknowledgements

Thanks to the following Digital Pathology projects and their maintainers/contributors, whose libraries improved this project: