2_Segment_gaps.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Segment gaps between cells  \n",
    "## 2.1 Option A: Applying an existing pixelclassifier \n",
    "We have trained a pixelclassifier (```edema_20241006```) to segment gaps between cells labelled as \"fluid\".  \n",
    "Download the classifier from the ```pixel_classifiers``` folder in GitHub and place it your QuPath project folder under ```classifiers/pixel_classifiers/```  \n",
    "Then **skip to 2.2**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.1. Option B: Training and applying a pixelclassifier from scratch  \n",
    "#### 2.1.1 Sample training regions \n",
    "The following script samples non-overlapping square regions of interest within all regions classed as \"tissue\".  \n",
    "Modify these variables as necessary:  \n",
    "**```sidelength```** makes the boxes bigger or smaller  \n",
    "**```n_regions```** changes the number of regions of interest to sample.  \n",
    "\n",
    "Run the script [for all](https://qupath.readthedocs.io/en/0.4/docs/scripting/workflows_to_scripts.html#running-a-script-for-multiple-images) images you want to include in training.  \n",
    "\n",
    "The regions are named \"Other\" to distinguish them from training annotations for the tissue training image.  \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import qupath.lib.roi.RectangleROI\n",
    "import qupath.lib.objects.PathAnnotationObject\n",
    "import qupath.lib.images.servers.ImageServer\n",
    "\n",
    "double sidelength = 500 // side-length of square ROI in um\n",
    "int n_regions = 10 // number of regions to generate\n",
    "\n",
    "int seed = -1\n",
    "def rng = new Random()\n",
    "if (seed >= 0)\n",
    "    rng.setSeed(seed)\n",
    "\n",
    "\n",
    "\n",
    "selectObjectsByClassification(\"tissue\");\n",
    "def selected = getSelectedObject()  \n",
    "\n",
    "\n",
    "tissueAnnotation = getAnnotationObjects().find{it.getPathClass() == getPathClass(\"tissue\")}\n",
    "tissueroi = tissueAnnotation.getROI()\n",
    "println(tissueroi.getClass())\n",
    "\n",
    "def imageData=getCurrentImageData()\n",
    "pixelwidth = imageData.getServer().getPixelCalibration().getPixelWidth()\n",
    "\n",
    "println(pixelwidth)\n",
    "pxsidelength = sidelength/pixelwidth\n",
    "\n",
    "\n",
    "int count = 0\n",
    "double x = 0\n",
    "double y = 0\n",
    "\n",
    "def xs = [];\n",
    "def ys = [];\n",
    "\n",
    "while (count < n_regions) {\n",
    "    println count\n",
    "    if (Thread.currentThread().isInterrupted()) {\n",
    "        println 'Interrupted!'\n",
    "        return\n",
    "    }\n",
    "    x = tissueroi.getBoundsX() + rng.nextDouble() * tissueroi.getBoundsWidth()\n",
    "    y = tissueroi.getBoundsY() + rng.nextDouble() * tissueroi.getBoundsHeight()\n",
    "\n",
    "    if (!tissueroi.contains(x + 0.5*pxsidelength, y + 0.5*pxsidelength)) //if the centre of the box is contained in tissueroi, incresase count\n",
    "        continue\n",
    "        \n",
    "    // discard a box if it overlaps with an already existing box \n",
    "    def grx = xs.collect{ it - pxsidelength < x }\n",
    "    def smlx = xs.collect{ it + pxsidelength > x }\n",
    "    def gry = ys.collect{ it - pxsidelength < y }\n",
    "    def smly = ys.collect{ it + pxsidelength > y }\n",
    "    def istrue = [grx, smlx, gry, smly].transpose().collect {it.every{ it }}\n",
    "    \n",
    "    if (istrue.any {it})\n",
    "        continue\n",
    "    \n",
    "    xs.add(x);\n",
    "    ys.add(y);\n",
    "    count++\n",
    "    \n",
    "    // generate ROIs for boxes that passed all conditions\n",
    "    roi = ROIs.createRectangleROI(x, y, pxsidelength, pxsidelength, ImagePlane.getDefaultPlane())\n",
    "    pathObject = PathObjects.createAnnotationObject(roi, getPathClass(\"Region_gap*\") )\n",
    "    addObject(pathObject) \n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1.2 Create the training image from annotations \n",
    "Run ```Classify ‣ Training images ‣ Create training image```\n",
    "\n",
    "and select \"Other\" in the drop-down menu under Classification. Then click \"Ok\". "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1.3 Generate training annotations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Good to know: General tips when generating training annotations  \n",
    "> * Stay away from the edges of each patch.  \n",
    "> * Make annotations small and roughly equal size — Many small annotations will better represent the diversity of your data than few large annotations.  \n",
    "> * Annotations should not overlap  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Step by step: \n",
    "1. Open the newly generated composite image\n",
    "2. On each patch derived from each training image, draw a small region that represents the class \"gap\". Skip a patch if it has no gap in it.  \n",
    "3. All thus-far made selections therefore belong to the class \"gap\". Mark all of them in the ```Annotations``` tab.  \n",
    "(To do so, click \"Select all\". or shift+click on the first and last annotation. Or cmd+click (ctrl+click on Windows) on each annotation belonging to \"gap\").\n",
    "4. With all relevant annotations highlighted, click on the corresponding class in the classification list to the right a click \"set selected\". All marked annotations should now be assigned to the class \"gap\".  \n",
    "5. Repeat steps 2-4, but this time mark regions that are not gaps. Asign these to the class \"Ignore*\". Be careful not to wrongly re-assign annotations of class \"gap\" to ignore (and vice versa).  \n",
    "6. Open ```Classify > Pixel classification > Train Pixel classifier```. Follow [the documentation to train your pixel classifier](https://qupath.readthedocs.io/en/stable/docs/tutorials/pixel_classification.html#getting-started). In short:\n",
    "7. Below are example settings for the pixel classifier: Only values deviating from standard settings are shown. I recommend experimenting with these settings.  \n",
    "8. Name your classifier: enter a name in the Classifier name field. Click ```Save```.  \n",
    "9. Click on ```Live prediction```. This may take some time to load  \n",
    "10. Inspect the result:  \n",
    "    * To toggle the prediction on and off, press C on your keyboard.  \n",
    "    * You can toggle Output from Classification to Probability. Classification shows binary classification, whereas Probability colorcodes the confidence of the prediction.  \n",
    "    * The accuaracy of the trained pixel classifier can be viewed in the Log. Use shift+cmd(ctrl)+L to open the log. Look for a message that starts with \"Current accuracy on the TRAINING SET...\" \n",
    "\n",
    "11. Once you are happy with the filters, turn off live prediction by clicking on \"Live prediction\".  \n",
    "12. Correct wrongly predicted pixels. When output is \"Probability\", you can search for the most confidently incorrect prediction per patch.  \n",
    "Repeat point 2-4, except marking regions that were wrongly classified.  \n",
    "13. Click on \"Live prediction\" again to re-compute the classification.  \n",
    "14. Once happy, save your classifier by clicking ```Save```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ">A pixelclassifier with these settings can be found in ```pixel_classifiers``` in GitHub named ```gaps_tutorial.json```\n",
    ">* **Classifier**: Random trees (RTrees)\n",
    ">* **Resolution**: Very high (0.5 um/px)\n",
    ">* **Features** > Edit:   \n",
    ">    - **Channels**:  \n",
    ">    Hematoxylin,\n",
    ">    Eosin, \n",
    ">    Residual  \n",
    ">    - **Scales**:  \n",
    ">    1.0, \n",
    ">    4.0, \n",
    ">    8.0   \n",
    ">    - **Features**:  \n",
    ">    Gaussian, \n",
    ">    Gradient magnitude"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.2 Apply the classifier to all images"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This step may take a long time depending on your image size, compute capability, and classifier settings. Computation on a compute cluster may be necessary.  \n",
    "You can test it on a single image/small tissue region first.  \n",
    "\n",
    "Run the following script for one/all images. Modify these variables as necessary:  \n",
    "\n",
    "**```classifier_name```**: enter the name of the classifier you trained. The classifier should be in ```classifiers/pixel_classifiers```  \n",
    "**Change this variable to ```\"edema_20241006\"``` if you want to use the downloaded classifier**   \n",
    "**```min_area```**: The the minimum area of a region to keep.  Smaller fragments will be discarded.  \n",
    "**```min_hole_size```**: minimum hole area. Holes smaller than this area will be filled.  \n",
    "**```name_gaps```**: The name of the QuPath class for gaps between cells. For instance \"gaps\".  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "classifier_name = \"gaps_tutorial\" // Enter the name of the classifier you want to use.\n",
    "min_area = 5.0 // Minimum area (um^2) of fragments to keep \n",
    "min_hole_size = 15.0 // minimum area of holes to keep (um^2)\n",
    "name_gaps = \"fluid\"\n",
    "\n",
    "fluid = getAnnotationObjects().findAll{it.getPathClass() == getPathClass(name_gaps)}\n",
    "\n",
    "\n",
    "if (!fluid) { // only run if fluid is not already annotated\n",
    "    selectObjectsByClassification(\"tissue\") // Only classify within the tissue annotation\n",
    "    createAnnotationsFromPixelClassifier(classifier_name, min_area, min_hole_size) \n",
    "    fireHierarchyUpdate()\n",
    "}"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}