.

Related articles

Import annotations into Xenium Explorer

Question: How can I import tissue or pathology annotations in Xenium Explorer? 

Answer: A feature to import annotations directly as a selection layer in Xenium Explorer is on the development roadmap. In the meanwhile, one workaround to view annotations within Xenium Explorer is to create a flattened image of the H&E image with annotations to load into Xenium Explorer to facilitate the exploration of cells and transcripts within those regions. 

 

  1. Annotate the image with QuPath. 
    1. A video tutorial on creating annotations in QuPath is at https://www.youtube.com/watch?v=dZYjIOI76WM. 
    2. One tip is to increase the thickness of the outlines to increase their visibility across zoom levels. In Qupath, set the thickness to 10 with Edit > Preferences >Objects > Annotation Line Thickness. 
    3. It is possible to export the annotations as a geojson from QuPath with File > Export objects as GeoJSON > Export > All objects. 
  2. Export the annotations as a flattened image with File > Export images... > Rendered RGB (with overlays) > OME TIFF. 
    1. Leaving the downsample factor at 1 recapitulates the full resolution microscopy image. However, if compute memory is limiting or if lower resolution image features are acceptable, change the downsample factor, e.g. to 8. 
    2. If the starting image was a tiled, pyramidal OME TIFF, then great. If not, then convert by opening the rendered RBG image in QuPath. Save with File > Export images... > OME TIFF. The tutorial here shows compression type should be ZLIB, pyramidal scale 2 and tile size 1024 px. Large images can take a while to write. 
  3. Import and register the image in Xenium Explorer following instructions here. 

 

Pathologist annotations on public Ovarian 5K data set here. 

 

To continue to interactively explore cells within the annotations in Xenium Explorer, retrace the annotation outlines with Xenium Explorer’s lasso selection tool. Export the cell IDs within the region. Use the cell IDs to subset the cell count matrix or to create new cell groups for import back into Xenium Explorer. Support site documentation details how.

 

Advanced discussion

For researchers comfortable with coding, it is possible to create an image layer consisting only of annotation polygons to load into Xenium Explorer. Use the Xenium Explorer opacity slider to view the annotations over morphology images. Some Python code to help get started follows. The code uses a geojson format file from QuPath exported with File > Export objects as GeoJSON > Export > All objects. 

import numpy as np
import pandas as pd
import skimage as ski
import tifffile

# Read one of the morpohology_focus layers and the geojson of polygons
a = tifffile.imread(aurl, is_ome=False, level=level)
gdf = pd.read_json(gjurl)

# Create an array the same shape as the full resolution morphology image
image = np.zeros(a.shape, dtype=np.uint8)

# Draw the polygon outlines
for i,row in gdf.iterrows():
    polygon = np.array(row['features']['geometry']['coordinates'][0])
    rr, cc = ski.draw.polygon_perimeter(polygon[:, 1], polygon[:, 0], shape=image.shape)
    image[rr, cc] = 255

# Save the image as TIFF
tifffile.imwrite("polygon_outline.tif", image, compression="zlib")

The TIF file will be dramatically small due to compression. For loading into Xenium Explorer it is still necessary to convert the image to tiled, pyramidal OME TIFF, e.g. via QuPath. When importing the image into QuPath, select the middle Other image type option. The outlines may not be not visible in QuPath. When importing the converted image into Xenium Explorer, select Immunofluorescence (multi-channel) image type. 

 

The screenshots show the result of importing the image here created from the geojson here that annotates some adipocytes in the public Xenium Prime Human Lymph Node FFPE data. The transcripts layer shows one gene, ADIPOQ.

 

Initial polygon image import covers the Xenium Morphology image.

 

Reducing the ‘Opacity’ of the imported image shows the morphology stain.

 

Researchers can apply geojson polygon coordinates directly to cells in spatial AnnData or Seurat objects to subset cells. Furthermore, it is possible to run xeniumranger import-segmentation with the geojson to assign transcripts to the polygons. See here for details on xeniumranger compatible formatting. Xenium Ranger then creates an output bundle for Xenium Explorer visualization.

 

Product: Xenium In Situ Gene Expression
Last modified: October 17, 2024