qupath-for-python-programmers.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# QuPath for Python Programmers 🐍\n",
    "**Alan O'Callaghan, Léo Leplat, Peter Bankhead, Fiona Inglis, Laura Nicolás Sáenz**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Presenting QuBaLab\n",
    "\n",
    "This is a Python package for exploring quantitative bioimage analysis... *especially* (but not exclusively) in combination with QuPath (https://qupath.github.io/).\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Why use QuBaLab?\n",
    "\n",
    "QuBaLab isn't QuPath - they're just good friends.\n",
    "\n",
    "* **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.\n",
    "* **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.\n",
    "\n",
    "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.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### How does QuBaLab compare to paquo?\n",
    "\n",
    "[paquo](https://paquo.readthedocs.io/) is an existing library linking Python and QuPath that provides a pythonic interface to QuPath.\n",
    "\n",
    "_We think paquo is great - we don't want to replace it!_\n",
    "\n",
    "Here are the 3 main differences as we see them:\n",
    "\n",
    "1. **Target audience**\n",
    "    - paquo is written mostly for Python programmers who need to work with QuPath data\n",
    "    - QuBaLab is written mostly for QuPath users who want to dip into Python\n",
    "2. **Convenience vs. Efficiency**\n",
    "    - paquo is based on [JPype](http://jpype.readthedocs.io/) to provide full & efficient access to Java from Python\n",
    "    - QuBaLab is based on [Py4J](https://www.py4j.org) to exchange data between Java & Python - preferring convenience to efficiency\n",
    "3. **Pixel access**\n",
    "    - paquo is for working with QuPath projects and objects - accessing pixels is beyond its scope (at least for now)\n",
    "    - QuBaLab enables requesting pixels as numpy or dask arrays, and provides functions to convert between thresholded images & QuPath objects\n",
    "\n",
    "So if you're a Python programmer who needs an intuitive and efficient way to work with QuPath data, use paquo.\n",
    "\n",
    "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.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting started\n",
    "\n",
    "You can find the documentation on https://qupath.github.io/qubalab-docs/.\n",
    "\n",
    "We'll go through some examples that are adapted from the notebooks hosted there. We hope to add more workflows soon!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Downloading sample images\n",
    "\n",
    "If you downloaded the sample project for this notebook: https://github.com/qupath/i2k-qupath-for-python-programmers/releases/download/v0.1.0/i2k-qupath-python-project.zip\n",
    "\n",
    "and extracted it to the notebook directory, this code won't do anything. Otherwise, this code will download two images we'll use for this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "cache_folder = \"./i2k-qupath-python-project/images\"\n",
    "\n",
    "# Define a utility function to find or download an image\n",
    "\n",
    "from pathlib import Path\n",
    "import urllib.request\n",
    "\n",
    "if cache_folder != \"\":\n",
    "    Path(cache_folder).mkdir(parents=True, exist_ok=True)\n",
    "\n",
    "def get_image(image_name, image_url):\n",
    "    if cache_folder == \"\":\n",
    "        filename = None\n",
    "    else:\n",
    "        filename = Path(cache_folder) / image_name\n",
    "    \n",
    "    if filename is None or not(filename.exists()):\n",
    "        print(f\"Downloading {image_name}...\")\n",
    "        path, _ = urllib.request.urlretrieve(image_url, filename=filename)\n",
    "        print(f'{image_name} saved to {path}')\n",
    "    else:\n",
    "        path = filename\n",
    "        print(f'{image_name} found in {path}')\n",
    "\n",
    "    return path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Download or get image\n",
    "cmu_path = get_image(\"CMU-1.svs\", \"https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/CMU-1.svs\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Download or get image\n",
    "fluoro_path = get_image(\"Patient_test_1.ome.tiff\", \"https://ftp.ebi.ac.uk/biostudies/fire/S-BIAD/463/S-BIAD463/Files/my_submission/Validation_raw/DCIS/Patient_test_1.ome.tiff\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## ImageServer\n",
    "\n",
    "QuBaLab provides a number of ImageServers, that allow you to read images\n",
    "just as QuPath would.\n",
    "\n",
    "\n",
    "OpenSlide for RGB images:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.images.openslide_server import OpenSlideServer\n",
    "\n",
    "print(cmu_path)\n",
    "openslide_server = OpenSlideServer(cmu_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "source": [
    "AICSImageIO for general purpose images (this may soon be replaced with BioIO):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.images.aicsimageio_server import AICSImageIoServer\n",
    "\n",
    "print(fluoro_path)\n",
    "aicsimageio_server = AICSImageIoServer(fluoro_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "source": [
    "ICC profile servers that wrap other servers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.images.icc_profile_server import IccProfileServer\n",
    "\n",
    "icc_profile_server = IccProfileServer(openslide_server)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "source": [
    "Since we're using an RGB image, we'll use OpenSlide."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "server = openslide_server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## ImageServer operations\n",
    "\n",
    "We can easily query image metadata usign an ImageServer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "metadata = server.metadata\n",
    "\n",
    "print(f'Image name: {metadata.name}')\n",
    "print('Levels:')\n",
    "for level, shape in enumerate(metadata.shapes):\n",
    "    print(f'Shape of level {level}: {shape}')\n",
    "print('Pixel calibration:')\n",
    "print(f'Pixel length on x-axis: {metadata.pixel_calibration.length_x}')\n",
    "print(f'Pixel length on y-axis: {metadata.pixel_calibration.length_y}\\n')\n",
    "print(f'Pixel type: {metadata.dtype}')\n",
    "print(f'Downsamples: {metadata.downsamples}\\n')\n",
    "print('Channels:')\n",
    "for channel in metadata.channels:\n",
    "    print(channel)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Reading images\n",
    "\n",
    "ImageServer provides a simple API for reading whole images:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "highest_downsample = server.metadata.downsamples[-1]\n",
    "lowest_resolution = server.read_region(highest_downsample)\n",
    "\n",
    "print(f'Image shape: {lowest_resolution.shape}')\n",
    "\n",
    "from qubalab.display.plot import plotImage\n",
    "import matplotlib.pyplot as plt\n",
    "_, ax = plt.subplots()\n",
    "plotImage(ax, lowest_resolution)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Reading regions\n",
    "\n",
    "Similarly, we can request just part of an image:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "downsample = 1\n",
    "x = 13000\n",
    "y = 15000\n",
    "width = 2000\n",
    "height = 1000\n",
    "tile = server.read_region(downsample, x=x, y=y, width=width, height=height)\n",
    "\n",
    "print(f'Tile shape: {tile.shape}')\n",
    "\n",
    "_, ax = plt.subplots()\n",
    "plotImage(ax, tile)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Reading images lazily\n",
    "\n",
    "Images can be read to numpy or dask arrays, which can be computed on demand:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "last_level = server.metadata.n_resolutions - 1\n",
    "lowest_resolution = server.level_to_dask(last_level)\n",
    "\n",
    "# Pixel values are not read yet, but you can get the shape of the image\n",
    "print(f'Image shape: {lowest_resolution.shape}')\n",
    "\n",
    "# Compute array. This will read the pixel values\n",
    "lowest_resolution = lowest_resolution.compute()\n",
    "\n",
    "_, ax = plt.subplots()\n",
    "plotImage(ax, lowest_resolution)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Reading tiles lazily\n",
    "\n",
    "We can also read tiles into dask arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "highest_resolution = server.level_to_dask(0)\n",
    "print(f'Full resolution image shape: {highest_resolution.shape}')\n",
    "\n",
    "x = 13000\n",
    "y = 15000\n",
    "width = 2000\n",
    "height = 1000\n",
    "tile = highest_resolution[:, y:y+height, x:x+width]\n",
    "print(f'Tile shape: {tile.shape}')\n",
    "\n",
    "tile = tile.compute() #  This will only read the pixel values of the tile\n",
    "_, ax = plt.subplots()\n",
    "plotImage(ax, tile)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Interacting with QuPath\n",
    "\n",
    "So far, we've been working just in the Python world. However, QuBaLab also provides and easy-to-use connection to QuPath.\n",
    "\n",
    "## Setting up a gateway\n",
    "\n",
    "The main method of interacting with QuPath\n",
    "is through a *gateway*, which operates using\n",
    "a websocket connection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.qupath import qupath_gateway\n",
    "\n",
    "token = None\n",
    "port = 25333\n",
    "gateway = qupath_gateway.create_gateway(auth_token=token, port=port)\n",
    "\n",
    "gateway"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## QuPath setup\n",
    "\n",
    "We're using a [CC0 TMA image](https://dataverse.harvard.edu/file.xhtml?persistentId=doi:10.7910/DVN/GG0D7G/VCRA28&version=1.0). We can take a snapshot of the QuPath GUI. This notebook assumes you've opened the `HE_Hamamatsu.tiff` image in the example project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.imshow(qupath_gateway.create_snapshot())\n",
    "plt.axis(False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Basic gateway operations\n",
    "\n",
    "A gateway provides us with an *entry point*,\n",
    "which allows us to call Java methods from python. This is an instance of the `QPEx` class, for anybody well-versed in the QuPath groovy API.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(f\"Extension version: {gateway.entry_point.getExtensionVersion()}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(f\"Current image name: {gateway.entry_point.getCurrentImageName()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Mixing 🐍 and ☕\n",
    "\n",
    "Since the entry point exposes the QuPath scripting interface, you can do lots of basic scripting operations in python by calling object methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "cores = gateway.entry_point.getTMACoreList()\n",
    "\n",
    "positive_cores = [core for core in cores if core.getClassification() == \"Positive\"]\n",
    "\n",
    "[(core.getName(), core.getChildObjects().size()) for core in positive_cores]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Downsides\n",
    "\n",
    "However, it's not ideal to write Java code in python, and we wouldn't necessarily encourage it.\n",
    "\n",
    "For one, we don't provide wrappers for Java objects, so finding the right methods can be tricky.\n",
    "\n",
    "Furthermore, it'll be very difficult to maintain complex scripts, especially if and when implementation details change in QuPath.\n",
    "\n",
    "If you just want to script QuPath, groovy will\n",
    "remain the best bet."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Objects\n",
    "\n",
    "We can request objects from QuPath and get references to Java objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.objects.object_type import ObjectType\n",
    "\n",
    "object_type = ObjectType.ANNOTATION    # could be DETECTION, TILE, CELL, TMA_CORE"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "annotations = qupath_gateway.get_objects(object_type = object_type)\n",
    "annotation = annotations[0]\n",
    "\n",
    "annotation.setName(\"Hello from Python\")\n",
    "print(annotation)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "qupath_gateway.refresh_qupath()\n",
    "\n",
    "plt.imshow(qupath_gateway.create_snapshot())\n",
    "plt.axis(False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Converting objects\n",
    "\n",
    "We can also specify a converter when requesting objects, meaning we actually retrieve simple Python objects. This makes it easy to write proper Python code to process objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "annotations = qupath_gateway.get_objects(object_type = object_type, converter='geojson')\n",
    "\n",
    "print(type(annotations[0]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from shapely.geometry import shape\n",
    "\n",
    "shape(annotations[0].geometry)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Adding and deleting objects\n",
    "\n",
    "We can modify properties of these Python objects, and then add them back to QuPath!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "for annotation in annotations:\n",
    "    annotation.color = (random.randint(0, 255), random.randint(0, 255), random.randint(0, 255))\n",
    "\n",
    "qupath_gateway.add_objects(annotations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Building a workflow using ImageServer and python\n",
    "\n",
    "Now that we've shown, let's walk through a short workflow that pieces these things together!\n",
    "\n",
    "### Reading the image currently open\n",
    "\n",
    "Let's use a `QuPathServer` to read pixels from the currently-open image in QuPath.\n",
    "\n",
    "**Note: this will be slower than reading from disk.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from qubalab.images.qupath_server import QuPathServer\n",
    "\n",
    "qupath_server = QuPathServer(gateway) # use image currently opened in QuPath\n",
    "downsample = 20 # reduce size by 20x\n",
    "image = qupath_server.read_region(downsample=downsample)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### Converting to grayscale and filtering\n",
    "\n",
    "With image in hand, we can first convert the image to greyscale and apply a simple Gaussian filter\n",
    "to remove some high-frequency content."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from skimage.filters import gaussian\n",
    "from skimage.color import rgb2gray\n",
    "\n",
    "# If the image is RGB, we convert it to grayscale\n",
    "# read_region() returns an image with the (c, y, x) shape.\n",
    "# To use rgb2gray, we need to move the channel axis so that\n",
    "# the shape becomes (y, x, c)\n",
    "image = np.moveaxis(image, 0, -1)\n",
    "image = rgb2gray(image)\n",
    "\n",
    "# Apply a gaussian filter\n",
    "image = gaussian(image, 2.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "### Identifying and applying a threshold\n",
    "\n",
    "Now we can identify the threshold using the Otsu method, and apply the threshold to the filtered image to make a mask"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "from skimage.filters import threshold_otsu\n",
    "\n",
    "threshold = threshold_otsu(image)\n",
    "\n",
    "mask = image < threshold"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Converting a mask to an ImageFeature\n",
    "\n",
    "We can use a QuBaLab method to convert from a labelled image into a Python ImageFeature --- something like a QuPath object as we worked with earlier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qubalab.objects.image_feature import ImageFeature\n",
    "\n",
    "mask_annotation = ImageFeature.create_from_label_image(\n",
    "    mask,   \n",
    "    scale=downsample,   # mask is 20 times smaller than the QuPath image, so we scale\n",
    "                        # the annotations to fit the QuPath image\n",
    "    classification_names=\"Otsu\",  # set a single classification to the detected annotations\n",
    ")\n",
    "\n",
    "## add the object back to QuPath\n",
    "qupath_gateway.add_objects(mask_annotation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualising our mask\n",
    "\n",
    "Before showing what it looks like in QuPath, let's visualise it in Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "fragment"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.imshow(mask)\n",
    "plt.title(f'Otsu (threshold={threshold:.2f})')\n",
    "plt.axis(False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Other workflow ideas\n",
    "\n",
    "- Object classifiers using scikit-learn\n",
    "- Object clustering using graph clustering\n",
    "- Assessing classifier feature importance\n",
    "- Your ideas or requests...?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}