QuBaLab

⚠️ Important

• 🆕 This is a new Python package for interacting with QuPath!
• 💻 For a stable, established solution, check out paquo (although we aim to meet different needs, see below)
• 🐛 Please report any bugs through the issues page

This is a Python package for exploring quantitative bioimage analysis... especially (but not exclusively) in combination with QuPath.

The name comes from Quantitative Bioimage Analysis Laboratory. This is chosen to be reminiscent of QuPath (Quantitative Pathology), but recognizes that neither is really restricted to pathology.

Why use QuBaLab?

QuBaLab isn't QuPath - they're just good friends.

• QuPath is a user-friendly Java application for bioimage analysis, which has some especially nice features for handling whole slide and highly-multiplexed images. But lots of bioimage analysis research is done in Python, and is hard to integrate with QuPath.
• QuBaLab's main aim is to help with this, by providing tools to help exchange data between QuPath and Python without any direct dependency on QuPath and Java. It therefore doesn't require QuPath to be installed, and can be used entirely from Python.

QuBaLab doesn't share code with QuPath, but is uses many of the same conventions for accessing images and representing objects in a GeoJSON compatible way. By using the same custom fields for things like measurements and classifications, exchanging data is much easier.

How does QuBaLab compare to paquo?

paquo is an existing library linking Python and QuPath that provides a pythonic interface to QuPath.

We think paquo is great - we don't want to replace it!

Here are the 3 main differences as we see them:

1. Target audience
   • paquo is written mostly for Python programmers who need to work with QuPath data
   • QuBaLab is written mostly for QuPath users who want to dip into Python
2. Convenience vs. Efficiency
   • paquo is based on JPype to provide full & efficient access to Java from Python
   • QuBaLab is based on Py4J to exchange data between Java & Python - preferring convenience to efficiency
3. Pixel access
   • paquo is for working with QuPath projects and objects - accessing pixels is beyond its scope (at least for now)
   • QuBaLab enables requesting pixels as numpy or dask arrays, and provides functions to convert between thresholded images & QuPath objects

So if you're a Python programmer who needs an intuitive and efficient way to work with QuPath data, use paquo.

But if you're a QuPath user who wants to switch to Python for some tasks, including image processing, you might want to give QuBaLab a try.

Getting started

You can find the documentation on github pages.

This project contains the QuBaLab package in the qubalab folder. Take a look at the Installation section to install it.

Some notebooks in the notebooks folder demonstrate how to use QuBaLab. If you want to run them, you can take a look at the Development section. If you just want to browse the content in them, look at the documentation.

Installation

QuBaLab is on PyPI, so you can install it with pip:

pip install --upgrade qubalab

Development

This part is useful if you want to run the notebooks or contribute to this project.

First, run:

git clone https://github.com/qupath/qubalab.git         # clone this repository
cd qubalab                                              # go to the project directory
python -m venv ./.venv                                  # create a local virual environment
source ./.venv/bin/activate                             # activate the venv
pip install -e ".[dev,test]"                  # install qubalab (-e means changes are loaded dynamically)
jupyter lab .                                           # to start the Jupyter notebooks
pytest                                                  # to run unit tests

Releases

This repository is set up to automagically push releases to pypi. To roll a new release, go to Releases --> Draft a new release, then under Tag and Release Title, enter a new (matching) SemVer. Then click Generate release notes and add any additional information. You shouldn't need any artifacts. However this ensures the GitHub and PyPi release history is synchronised.