Question: What are the Xenium image scale factors?
Answer: Xenium image results are pyramidal TIFFs that store different resolution images as separate series or levels. The pixel size to micron (µm) conversion factors differ for each series and are given in the table.
Level refers to resolutions in 0-based indexing, while Fiji’s series uses 1-based indexing. For the full-resolution (series 1) image, the pixel size is 0.2125 microns. The µm x µm image size is invariant. The higher the series, the fewer pixels make up the image. The table gives example X and Y pixel values for the morphology_mip.ome.tif DAPI stain from Xenium v1 human breast cancer sample replicate 1. Each level increases pixel size by a factor of two.
The Xenium cell feature matrix and transcripts result coordinates are in microns. Plotting functions interpret pixel values as the image’s XY coordinates. Thus, to overlay cells or transcripts onto the image, it is necessary to divide their micron values by the matching pixel size. Alternatively, use an image converted to micron coordinates. The series with the closest pixel size to microns is series 3. It requires a small amount of downsampling or interpolation to match cell and transcript coordinates.
The Xenium Explorer desktop software already factors for conversions when overlaying cell and transcript information onto the image. We recommend starting Xenium data exploration with Xenium Explorer.
The figure below shows how external desktop tool Fiji (ImageJ) gives options to open the different resolution images for the morphology_mip.ome.tif DAPI stain from Xenium v1 human breast cancer sample replicate 1.
If the import option Metadata viewing > Display metadata is checked, Fiji displays the metadata in a separate window. The figure below shows a truncated view and labels some of the parts.
The metadata information is accessible programmatically. Code tested with Python v3.9.13 follows to view the metadata (1 and 2), to plot the image (3), to resample the image (4) and to overlay transcripts (5) on the example DAPI image. The anaconda download from https://www.anaconda.com/products/distribution for Python 3.9 should install most dependent Python packages. An additional installation of either pyarrow or fastparquet may be necessary for code in [5].
Disclaimer: The code-snippets are provided as-is for instructional purposes only. 10x Genomics does not support nor guarantee the code.
[1] Print metadata tag
import tifffile
mipurl = '/path/to/outs/morphology_mip.ome.tif'
with tifffile.TiffFile(mipurl) as tif:
for tag in tif.pages[0].tags.values():
if tag.name == 'ImageDescription':
print(tag.name+":", tag.value)
[2] Print dimensions of the pyramid level images
with tifffile.TiffFile(mipurl) as tif:
for i in range(len(tif.series[0].levels)):
print(i, tif.series[0].levels[i].shape)
[3] Plot Level 2 DAPI image with inverted color scale
import tifffile
from matplotlib import pyplot as plt
with tifffile.TiffFile(mipurl) as tif:
image = tif.series[0].levels[2].asarray()
plt.imshow(image, cmap='binary')
plt.title('Level 2 DAPI', size=16)
plt.axis('scaled')
plt.show()
[4] Resample Level 0 image dimensions
Resample to match pixels to microns using the scale factor (0.2125) and plot.
import scipy
import tifffile
from matplotlib import pyplot as plt
with tifffile.TiffFile(mipurl) as tif:
image = tif.series[0].levels[0].asarray()
print(image.shape)
resample = scipy.ndimage.zoom(image, 0.2125)
print(resample.shape)
(25778, 35416)
(5478, 7526)
plt.imshow(resample, cmap='binary')
plt.title('Resampled DAPI', size=16)
plt.axis('scaled')
plt.show()
[5] Overlay select (qv >= 20) transcripts on resampled image
import pandas as pd
import seaborn as sns
# Read transcripts table
wdir = ‘/path/to/’
transcriptsurl = f'{wdir}outs/transcripts.parquet'
transcripts = pd.read_parquet(transcriptsurl)
transcripts['feature_name'] = transcripts['feature_name'].apply(lambda x: x.decode('utf-8'))
# Subset transcripts to region of interest and quality value >= 20
subset = transcripts[
(transcripts['x_location'] > 4000) & (transcripts['x_location'] < 4400) &
(transcripts['y_location'] > 4700) & (transcripts['y_location'] < 5100) &
(transcripts['qv'] >= 20)]
# Define transcript features of interest
genes = ['LUM', 'KRT5', 'EPCAM']
# Plot resampled image from [4]
plt.rcParams["figure.figsize"] = (10,10)
plt.imshow(resample, cmap='binary')
# Plot features of interest
sns.scatterplot(
x = 'x_location', y = 'y_location',
data = subset[subset['feature_name'].isin(genes)],
hue = 'feature_name', s = 5, alpha = 1,
)
plt.title('Transcripts of interest with qv >=20 overlaid on DAPI', size=16)
plt.legend(bbox_to_anchor=(1, 1), loc='upper left', ncol=1)
plt.axis('scaled')
plt.xlim(4000,4400)
plt.ylim(4700,5100)
plt.show()
Related resources:
- Public Xenium v1 human breast cancer dataset https://www.10xgenomics.com/products/xenium-in-situ/preview-dataset-human-breast and related Nature Communications publication https://www.nature.com/articles/s41467-023-43458-x
- Companion Python functions used to wrangle data in the above publication https://github.com/10XGenomics/janesick_nature_comms_2023_companion/blob/main/companion_functions.py
- Description of Xenium results files https://www.10xgenomics.com/support/in-situ-gene-expression/documentation/steps/onboard-analysis/understanding-xenium-outputs
- Xenium Explorer tutorial to get started https://www.10xgenomics.com/support/software/xenium-explorer/tutorials/getting-started-with-xenium-explorer
- Xenium Explorer tutorial on checking data quality https://www.10xgenomics.com/support/software/xenium-explorer/tutorials/checking-xenium-data-quality
- Introduction to using Fiji (ImageJ) using Visium images Testing microscope image compatibility with Space Ranger
- Introduction to image registration using Fiji (ImageJ) with Xenium images H&E to Xenium DAPI image registration with Fiji
Product: Xenium In Situ Gene Expression
Last modified: December 20, 2023
Last modified: January 11, 2023