10x Genomics Support/Xenium Explorer/Tutorials/

Navigating Xenium Explorer

Open Xenium Explorer by double-clicking the application icon.

There are a few options to open datasets in Xenium Explorer (see Xenium Explorer Input Files). You can drag and drop or click Open New File to select the .xenium file. There is also a dropdown menu to either Select file (same as Open New File) or Open file from path. If you open a file from path, enter the path to the location where the .xenium file is stored on your computer or network drive.

The screenshots in this tutorial come from 10x public datasets. Click the links to download and explore these human pancreatic cancer and human lung cancer datasets.

The Xenium Onboard Analysis output files must be in the same directory path as this file (unless you have modified the file paths).

Recent Files

Once you have opened a dataset, the Xenium Explorer home page displays options to open or clear recent files. Metadata are shown on the recent file tiles. The ten most recent datasets and any saved views will be displayed.

When you close a dataset, the view settings will be saved automatically as an unnamed saved view (similar to explicitly saving current views. If you open a dataset from the Recent Files menu, Xenium Explorer will restore your last view. However, if you open the same dataset from outside the Recent Files menu (drag and drop, double-click .xenium file, or Open New File), Xenium Explorer will open with the default initial view (grayscale DAPI image) and the unnamed saved view will be lost. The best way to ensure you can reopen the view state again later is to save your current view before closing Xenium Explorer.

After the dataset loads, you should see an image of the nuclei-stained (DAPI) sample. The following image shows the key components of the Xenium Explorer interface. In this Getting Started tutorial, we provide a brief overview of the image, cell, transcript, and lasso features. The Save Current View and Share features are described in the Saving and Sharing Results tutorial.

Settings and keyboard shortcuts

Click the 10x Genomics icon in the top left-hand corner to return to the home screen, open a new dataset, or find support documentation.

The Xenium Explorer interface settings are controlled in the Settings menu and with keyboard shortcuts. The Settings menu allows you to show or hide transcript and cell tooltips, image scale axes, the user interface (UI) itself, and the image navigator in the bottom left-hand corner.

Keyboard shortcuts:

TabSettings buttonShow/hide UI
= (equals key)Scroll with mouseZoom in
- (hyphen key)Scroll with mouseZoom out
LLasso buttonDraw a freehand shape with lasso selection tool
RLasso buttonDraw a rectangle with selection tool
PPan buttonMove the image up and down, or left and right

Sample Information

The Sample Information pop-up window displays metadata about the sample run, analysis, and panel. The Run and Panel sections show information entered on the Xenium Analyzer instrument during the run set up; they are stored in the experiment.xenium manifest file. From the Analysis section, you can open the analysis summary HTML file in another Xenium Explorer window.

Starting in Xenium Explorer v1.2, this window also displays the "Panel Design ID" for Xenium Gene Expression panels and if used, Xenium Ranger metadata.

The Images, Cells, and Transcripts menus allow you to layer multiple pieces of information in the explorer viewing area. We will discuss the options for each layer below.

The Images menu shows settings to adjust the 3D image stack of the nuclei-stained (DAPI) cells and autofocus stain image(s). The Image layer is automatically checked when Xenium Explorer is opened.

The Xenium Analyzer captures vertical stacks of images every cycle and in every channel for multiple fields of view. The stacks are processed and stitched together to build a single image of the tissue section. Xenium Explorer displays the X-Y dimensions of the image. The Image options panel allows you to explore the Z-dimension. The zoom slider controls zooming in/out on the image. All data in the main Xenium Explorer window can be rotated in 90 degree increments by clicking the Rotate Image button (Per-Gene Localization images cannot be rotated at this time).

When Z-Slices is selected as the image view, you can view the 3D DAPI morphology.ome.tif tissue images from different Z-plane depths. The Z-slice depth in µm is shown in the lower left-hand corner. Zoom in to a region of the image, and click through different Z-slices. The nuclei should look fuzzy, come into focus, and then go out of focus again as you sweep through the Z-plane of that region of the tissue. This feature can be useful for examining cell structure within the tissue volume.

The Autofocus option displays the single best-focus Z-plane from the morphology stain Z-stack morphology_focus/morphology_focus_[xxxx].ome.tif images. The background is minimized in this image. It works best for cells in the tissue that approximate a monolayer, while cells above or below the focal Z-plane may be missed.

  • In XOA v2.0 and later, the directory contains the DAPI-stained image, as well as boundary and interior cell images for the multimodal cell segmentation workflow. For multimodal cell segmentation datasets, the DAPI morphology_focus_0000.ome.tif file must be present in the directory to load the dataset. To load data without the DAPI image, the OME-XML metadata information must be modified. Python tools such as ome-types can be used to view and modify metadata if needed.
  • In XOA v1.0 - 1.9, the autofocus output file is called morphology_focus.ome.tif and it is the DAPI stained image.

The maximum intensity projection technique converts a 3-dimensional stack of microscope images into a 2-dimensional image. The Maximum Intensity Projection of the DAPI Z-stack morphology_mip.ome.tif image displays the brightest pixel from each layer (generated in XOA v1.0 - 1.9). All the cells will be visible, however there may be higher background from out-of-focus light.

You can change the image channel intensity and contrast (gamma correction) with sliders. The channel color can be changed either by clicking the three vertical dots or the current color circle. The channel intensity is auto-leveled by default; click the three dots and select Auto-level channel to reset.

Post-Xenium H&E images (Xenium Explorer v1.2+) and IF images (Xenium Explorer v1.3+) can be viewed and aligned in the UI. See the Image alignment tutorial for details. Starting in v2.0, Xenium Explorer can open IF images with more than six channels and display six at a time (check box next to stain name to select).

Beginning in Xenium Explorer v2.0, the Images layer loads all morphology channels for multichannel images from multimodal cell segmentation datasets. The channels are labeled by purpose: Nuclear, Boundary, Interior - RNA, and Interior - Protein. Clicking the info icon will switch the labels to the name of the stain(s). Select and layer all channel images to view them simultaneously (Multi Channel) or view one channel at a time (Single Channel).

The default channel colors can be changed by clicking on the circle icon. It is also possible to toggle between viewing channels with colors or in grayscale. By default, channel colors are displayed with uniform colors (based on CIELAB color space). This color map is intended to display channel colors with uniform lightness and contrast to evenly distribute multichannel stain signals. When disabled, channels are displayed with a standard color map.

Uniform colorsStandard colors

The Cells menu displays nuclei and cell borders based on cell segmentation results. Check the box next to the layer name to view.

Set the Boundaries button to view outlines for cells, nuclei, or both. Set the View cell as button to view the cell boundaries as filled, outlined, or both. These features are useful for checking cell segmentation quality (see Checking Xenium Data Quality tutorial).

When tooltips are shown (Settings > Show Tooltips), you will see cluster, location, area, and transcript counts for individual cells as you move the cursor over each cell.

Default or custom cell colors (fill and outline) can be displayed by:

  • Secondary analysis cluster group affiliation (graph-based, K-means, custom)
  • Transcript density map
  • Single color
  • Cell segmentation method (for multimodal segmentation outputs only)

The Cells menu also shows cells colored by pre-computed graph-based or K-means cluster groups. The clusters are generated by the Xenium Onboard Analysis pipeline and are stored in the analysis.zarr.zip file. This feature is useful for assessing whether cell clusters align with known cell types or regions of interest in the sample (see Checking Xenium Data Quality tutorial).

The cluster name and color can be edited by clicking the three vertical dots next to each cluster label. You can reset the original cluster color or name by selecting the Edit Color or Edit Name and Reset to default. The clusters can be renamed based on cell type annotation using marker genes.

This option allows you to upload custom cell clusters as a CSV file on the Cells menu.

Create a cell group comma-separated value (CSV) file in a text editor, such as Microsoft Excel. The format of the CSV file is as follows:

  • The first row must have two column headers in this order with these exact names: "cell_id" and "group".
  • The first column is a list of cell ID names.
  • The second column is a list of group labels.
  • There should only be two columns in this file. At this time, multiple custom cell groupings must be uploaded as separate CSV files. You can select each group in the "Cell groups" dropdown list.

Here is an example from the pancreatic cancer dataset (download custom cell group file here):

Note that you must wait for cells to load in the window before the CSV file can be uploaded. Click the plus sign to add the CSV file. Then click Upload Custom Groups.

The uploaded cell groups can be saved to Saved Views. To share with colleagues, they will need to reupload the cell group CSV file. The custom cell groups look like this:

The transcript density is determined by the genes that are selected on the Transcripts menu. Cell colormap lower/upper bounds and fill opacity can be adjusted with the slider (click arrow above maximum threshold value to reset). There are several color palette options.

When colored by the transcript density map, the lowest transcript density cell maps to the lower end of the palette (i.e., viridis=purple), while the highest transcript density cell maps to the upper end of the palette (i.e., viridis=yellow), with a linear distribution in between. The Transcript density map count threshold slider allows you to choose a different mapping range, which can help to visualize cells that are at or beyond the limits of the density range.

In the multimodal cell segmentation analysis workflow, three methods are used to segment cells (read more in the XOA algorithms page). You can visualize the segmentation methods starting in Xenium Explorer v2.0. This feature is useful for qualitatively checking nucleus and cell segmentation results (see more on the checking data quality page).

To view all cells by segmentation method, select Segmentation Method in the dropdown menu for Cell Color. The inferred cell segmentation polygon boundaries are shown in Xenium Explorer. To view the segmentation method for an individual cell, click on a cell to view information in the Selection pop-up window.

The Transcript menu displays transcript count data. Check the box next to the layer name to view.

When tooltips are shown (Settings > Show Tooltips), you will see ID, location, and Q-Score for individual transcripts as you move the cursor over each transcript point. By default, the full gene panel will be displayed in the Transcripts menu. You can look for a specific transcript in the gene panel search bar or organize the genes by group labels. Genes will be categorized by panel design source (i.e., "Predesigned" or "Custom").

First, decide which genes you want to create groups for. The cell_feature_matrix/features.tsv.gz file in the output directory contains the full list of pre-designed panel genes, as well as any custom add-on genes. For each feature, the Ensembl ID and gene name are stored in the first and second column of the features.tsv.gz file, respectively. The third column identifies the feature type (Gene Expression). You can copy/paste a list of Gene Expression genes from the second column of this file. Xenium Explorer does not use the negative control rows (Negative Control Probe, Negative Control Codeword, Unassigned Codeword); they are used for calibration during the on-instrument analysis.

# to view the file gzip -cd features.tsv.gz | less # to uncompress the file gunzip features.tsv.gz


ENSG00000121270 ABCC11 Gene Expression
ENSG00000107796 ACTA2 Gene Expression
ENSG00000163017 ACTG2 Gene Expression
ENSG00000168615 ADAM9 Gene Expression
ENSG00000123146 ADGRE5 Gene Expression
ENSG00000196616 ADH1B Gene Expression
ENSG00000181092 ADIPOQ Gene Expression

Next, create a gene group comma-separated value (CSV) file in a text editor, such as Microsoft Excel. The format of the CSV file is as follows:

  • The first row must have two column headers in this order with these exact names: "gene" and "group".
  • The first column is a list of gene names.
  • The second column is a list of group labels. The CSV file may contain an arbitrary number of columns for other group labels.
The column header row was added in Xenium Explorer v1.2. For Xenium Explorer v1.0 - 1.1, there should be no column headers in the gene group CSV file.

Here is an example from the pancreatic cancer dataset (download custom gene group file here):

Next, click the three vertical dots and select Create gene groups. Click Upload Gene Group CSV and choose your CSV file.

The gene list will now display the group names with dropdown menus. Grouped genes are automatically assigned the same point color. If panel genes were not included in the CSV file, they will be automatically grouped into an "Ungrouped" category. Ungrouped genes have a gray circle icon by default.

If the CSV file contains multiple group name columns, all group names will be listed alphabetically. Individual genes may be assigned to multiple groups and will be listed under each group name.

The imported gene list and associated transcript icon color and shape changes can be saved with the Saved Current Views option.

Transcript counts can be shown as points or as a density map.

When displayed as points, checked gene icons will be visible in the viewing area and unchecked genes will be invisible. Low quality transcripts (Q-Score < 20) are filtered out by default. Switch the toggle to display them as gray circles (note: these are not the same as "Ungrouped" gene gray icon points).

The individual transcript or gene group icon and color can be changed (depending on whether point style is "Icons" or "Circles"). You can reset to the original (prior to creating grouped genes) point color and icon by selecting Reset to default. Transcripts are plotted by default as small points, with the ability to customize point size and type to enable better visualization of transcript distribution across the sample.

To hide unchecked genes from the gene list area of the Transcripts menu, click the three vertical dots and select Only show visible genes in list. To show all genes in the list again, click the X by Only showing visible genes.

When displayed as a density map, the cumulative density of all checked genes will be visible in the viewing area. The density map opacity, bin size, and scale threshold can be adjusted with the sliders (click arrow above maximum threshold value to reset). There are several density map palette options as well.

When colored by the density map, the lowest transcript density bin maps to the lower end of the palette (i.e., viridis=purple), while the highest transcript density bin maps to the upper end of the palette (i.e., viridis=yellow), with a linear distribution in between. The Density map scale threshold slider allows you to choose a different mapping range, which can help to visualize bins that are at or beyond the limits of the density range.

Transcript point subsampling

When viewing transcripts as points, the transcript points are subsampled when zoomed out. The transcript subsampling ratio is displayed in the lower left-hand corner. You will see more transcript points as you zoom in.

For example, the zoomed out image has a 1:256 transcript subsampling ratio:

After zooming in, here is a 1:16 transcript subsampling ratio:

Per-gene localization

The per-gene localization feature is useful for assessing the spatial location of genes in the entire sample area. It displays spatial density map plots of total transcript counts (Q-Score ≥ 20) per gene and for all selected genes (combined counts if more than one gene is selected).

There are two lasso shape options - rectangle and freehand lasso. Both are useful for selecting Regions of Interest (ROIs). For example, the freehand lasso tool is useful for counting genes per cell in specific tissue structures. Learn how to make multiple selections and export information in the Multiple Selections tutorial.

Choose the shape (keyboard shortcuts: L or R) and then use your mouse to draw the shape (release mouse to complete selection shape). If genes are checked in the Transcripts menu, the selection box displays transcript and cell information for the selected area (transcripts do not need to be displayed to appear in the selection box). The selection box displays the cell clusters that are checked in the Cells menu (cells may be viewed as filled, outlined, or both).

Transcript counts are not shown for very large selections for optimal performance. If your selection reaches the limit, you will see the message "Decrease the selection size to see transcript counts.

Here's an example using the lasso to select a region with CFTR- tumor cells (see pancreatic cancer explorer page):

The Go to location button enables you to jump to a specific X-Y coordinate location in the image, open a saved view, or transfer a permalink view from another session. X-Y coordinate values are shown in the lower left-hand corner of the viewing area in µm. The X-Y format must be comma-separated (i.e., 8609, 272). Lists of coordinates from selected Regions of Interest or cells should be pasted with the Lasso button’s Paste coordinates feature (see Multiple Selections tutorial).

Editing the manifest file to visualize custom analyses

The experiment.xenium manifest file contains metadata read in by Xenium Explorer about the experiment, including the paths to the input files listed above. The file names in the images and xenium_explorer_files sections use the default output file names from Xenium Onboard Analysis.

In order to view and interact with custom analysis results in Xenium Explorer, you can edit these sections of the manifest file. Because the experiment.xenium file is a text file in JSON format, changes can be made in any text editor. The file paths can be absolute or relative. However, relative paths should not use a tilde (~) for home directory path expansion.