Analyze OMERO data using QuPath

Description

QuPath is a cross-platform software application designed for bioimage analysis - and specifically to meet the needs of whole slide image analysis and digital pathology. See https://github.com/qupath/qupath/wiki/

We will show:

  • How to open an image from OMERO server in QuPath
  • How to draw annotations and perform simple Cell detection in QuPath
  • How to export the ROIs from QuPath as OME-XML
  • How to import the OME-XML to the OMERO.server and attach the QuPath ROIs to the original image in OMERO

Resources

  • Data: example images from
    • IDR project referenced as idr0018. Note that the data also have been imported into an OMERO.server where the possibility to write annotations exists (not the IDR server itself). See the Step-by-step section for further details.
  • Plugin ome-omero-roitool v0.2.1 for import and export of ROIs to or from OMERO using OME-XML format. The ome-omero-roitool-xxx.zip under Releases also contains the scripts for export and import of ROIs from/to QuPath in OME-XML format. For precise installation steps, see below the Step-by-step section.

Setup

Download QuPath v0.2.0 from https://qupath.github.io/.

Step-by-step

  1. You can go through this workflow directly with the image in the IDR. QuPath will open that image without problems and no credentials are needed. Nevertheless, as you cannot write any data directly into IDR during your analysis, you will not be able to successfully import the resulting ROIs back into the OMERO in IDR. Thus, you might consider using another OMERO.server which you can write data to and upload this or another RGB large image into it.

  2. In OMERO.web, identify an image in the idr0018 project and the dataset Baz1a-14-100-gastrointestinal contained in that project.

  3. Select the first image and double-click on it. This will open the image in OMERO.iviewer, in a new tab of your browser.

  4. In the OMERO.iviewer tab, select the whole URL in the address bar of your browser and copy it, for example using right-click and Copy.

  5. In QuPath, select File > Open URL... and paste the link into the dialog.

    image0

  6. Click OK.

  7. If you are using a link not from IDR, but from a different OMERO.server protected by credentials, in the following dialog, enter your credentials.

    image1

  8. Set image type to Brightfield H&E in the following dialog. Click OK.

  9. Find a region with well-defined cells and nuclei in the image, zoom in.

  10. Draw an ROI Annotation which denotes the region in which the cells will be detected using the Wand tool image2.

  11. Adjust your ROI Annotation using the Brush tool image3.

  12. Select Analyze > Cell detection > Cell detection.

  13. You can adjust the parameters. Click Run. This will draw red ROIs around cells and nuclei inside your ROI Annotation.

    image4

  14. Select Measure > Show detection measurements.

    image5

  15. Note: You can save the results locally by clicking Save in the bottom right of the Detection results table. If you are using your own server, you can upload the results and link them to the Image.

  16. In the following steps, we will show how to convert the ROIs your just created in QuPath into OMERO ROIs and attach them to the image in OMERO.

  17. First, use the ROI OME-XML export script to export your ROIs from QuPath into OME-XML file. Find the version of ome-omero-roitool mentioned in Resources on ome-omero-roitool releases and from there download the ome-omero-roitool-xxx.zip. The downloaded zip contains both the plugin and the QuPath scripts needed for this workflow.

  18. Unzip the downloaded artifact and drag and drop the OME_XML_export.groovy into your QuPath.

  19. To run the script, select Run > Run.

  20. Note: If you run a Cell detection in QuPath, the nuclei ROIs will be drawn as well as the ROIs around the cells. The ROI OME-XML export script will export both the ROIs around the cells as well as the nuclei ROIs.

  21. Import the OME-XML with the ROIs from QuPath into OMERO. These steps must be run on a command line. If you did not do so already, find the version of the ome-omero-roitool mentioned in Resources on ome-omero-roitool releases. From there, download the ome-omero-roitool-xxx.zip. Open your terminal window.

  22. Unzip the downloaded file and go into the resulting folder as follows:

    unzip ome-omero-roitool-xxx.zip
cd ome-omero-roitool-xxx
cd bin

  23. On Mac or Linux, run:

    ./ome-omero-roitool import --help

  24. On Windows, run:

    ome-omero-roitool.bat import --help

  25. The --help option will give you a helpful output about how to construct the import command.

  26. In the command below, replace the $IMAGE_ID parameter with the ID of the image in OMERO. You can obtain this ID for example from OMERO.iviewer (see beginning of this workflow).

  27. To achieve the import of the ROIs to OMERO, you can run:

    ./ome-omero-roitool import --password $PASSWORD --port 4064 --server $SERVER --username $USERNAME $IMAGE_ID $PATH/TO/OME-XML/FILE

    Note: if you are using websockets, set the port to 443 and the server with the protocol e.g. wss://outreach.openmicrocopy.org/omero-ws.

  28. After you executed the import command above, go to OMERO.iviewer in your browser and view the ROIs on the image. The Annotation from QuPath is displayed as a mask ROI in OMERO.iviewer (the yellow ROI in the screenshot below). Masks cannot be edited in OMERO.iviewer at the moment, but they can be viewed. The mask, when selected displays a blue bounding box around the Annotation on the image.

    image6