Dana-Farber-AIOS/pathml

Tools for computational pathology

PathML – a Python toolkit for computational pathology

What it is

  • An open‑source Python library (available on PyPI and Docker) that helps researchers work with whole‑slide pathology images.
  • It focuses on three design goals: scalability (handling huge image collections), standardisation (common file‑format handling, preprocessing pipelines) and ease of use (high‑level APIs, Jupyter notebooks, Docker image).

Key capabilities

Capability How PathML supports it
Image loading Supports >160 slide formats via OpenSlide and Java‑based readers; one‑line pathml.load_image() loads whole‑slide images (WSIs).
Pre‑processing Built‑in pipelines for stain deconvolution, colour normalisation, tile extraction, and GPU‑accelerated transforms that can be chained together.
Machine‑learning ready Converts pre‑processed tiles into PyTorch tensors; includes example pipelines that feed data into deep‑learning models (e.g., HoVer‑Net for nucleus detection, HACTNet for cancer sub‑typing).
Graph construction Provides a Graph API that builds cell‑ and tissue‑level graphs from segmented images, ready for graph‑neural‑network training.
Model inference Utilities to run ONNX models at scale on whole slides.
Workflow orchestration Works on local machines, clusters, or in Docker/Jupyter environments; can be scripted or run interactively.

Typical workflow

  1. Install – via micromamba + pip, Conda, Docker, or Google Colab (the README gives step‑by‑step commands).
  2. Load a slide – slide = pathml.load_image('my_slide.svs').
  3. Build a pipeline – chain transforms like StainNormalization, TileExtractor, Resize, etc.
  4. Run preprocessing – execute the pipeline on a local or cluster compute backend; results are stored as tensors or image tiles.
  5. Train / infer – feed the tensors into PyTorch models (examples include HoVer‑Net, HACTNet) or run ONNX models.
  6. Analyse – use the Graph API to create cell‑level graphs, then apply GNNs for tasks such as cancer sub‑typing.

Why it matters

  • Whole‑slide images can be gigapixels in size; manual analysis is infeasible. PathML automates the heavy lifting, letting researchers focus on the scientific question.
  • By providing a unified, well‑documented interface, it reduces the engineering overhead that often blocks pathology‑AI projects.
  • The library is already cited in dozens of high‑impact papers (Nature Medicine, Lancet Digital Health, etc.), showing it is trusted by the community.

Getting started quickly

# Pull the ready‑made Docker image and launch Jupyter Lab
docker pull pathml/pathml
docker run -it -p 8888:8888 pathml/pathml

Then open the URL shown in the terminal to explore the example notebooks (e.g., loading images, stain normalisation, training HoVer‑Net).

Community & support

  • Open‑source under GPL‑v2 with optional commercial licensing.
  • Contributions are welcomed (bug reports, new transforms, model wrappers, documentation).
  • Contact via innovation@dfci.harvard.edu for questions.

Bottom line PathML is a production‑ready, research‑focused toolkit that bridges digital pathology data and modern AI/ML methods, making large‑scale slide analysis accessible to labs without extensive engineering resources.