The Xenium Onboard Analysis pipeline generates several output files using the Zarr format. Xenium Explorer reads these files to display cell segmentation, secondary analysis clustering results, and transcript assignment on the nuclei-stained tissue morphology images.

The Zarr format saves large amounts of data by storing them as compressed chunks of N-dimensional arrays. Zarr files can be read and modified with Python. The zarr Python library documentation and tutorials are available here.

In the sections below, we describe the group arrays and attributes associated with each Zarr file in the Xenium output bundle, along with example Python code for viewing these files.

The cells.zarr.zip output file contains the cell and nucleus segmentation masks used for transcript assignment and the polygon boundaries used for visualization. It is the only file in the output bundle where you can find the cell and nucleus segmentation data.

It has the following hierarchy of array data:

Copy
(root)
├── cell_id
├── cell_summary
├── masks
│   ├── 0
│   ├── 1
│   └── homogeneous_transform
└── polygon_sets
     ├── 0
     │   ├── cell_index
     │   ├── method
     │   ├── num_vertices
     │   └── vertices
     └── 1
         ├── cell_index
         ├── method
         ├── num_vertices
         └── vertices

Arrays

Description of root group arrays:

Description of segmentation /masks arrays:

Description of segmentation /polygon_sets arrays:

Attributes

Description of root group attributes:

Description of the /cell_summary array columns (type f64):

The analysis.zarr.zip output file contains the automated secondary analysis clustering results. It has the following hierarchy of array data:

Copy
(root)
└── cell_groups
    ├── 0
    │   ├── indices
    │   └── indptr
    ├── 1
    │   ├── indices
    │   └── indptr
    ├── [...]
    └── 9
        ├── indices
        └── indptr

There are 10 cell clustering results (clustering_index = 0 - 9) stored in this file - the first for graph-based clustering and the remaining for K-means clustering (K = 2 - 10). Descriptions for /cell_groups/[clustering_index] group arrays:

Descriptions for the cell_groups group attributes:

The cell_feature_matrix.zarr.zip output file contains a matrix of counts per cell and per feature (including gene and non-gene codewords), which have passed the default quality value (Q-Score) threshold of Q20. It has the following hierarchy of array data:

Copy
(root)
└── cell_features
    ├── cell_id
    ├── data
    ├── indices
    └── indptr

Description for /cell_features group arrays:

Description for /cell_features group attributes:

The transcripts.zarr.zip output file contains data to evaluate transcript quality and localization. It has the following hierarchy of array data:

Copy
(root)
├── codeword_category
├── gene_category
├── density
│   └── gene
│       ├── data
│       ├── indices
│       └── indptr
└── grids
    ├── 0
    │   ├── 0,0
    │   │   ├── codeword_identity
    │   │   ├── gene_identity
    │   │   ├── id
    │   │   ├── location
    │   │   ├── quality_score
    │   │   ├── status
    │   │   ├── uuid
    │   │   └── valid
    │   ├── 0,1
    │   │   ├── codeword_identity
    │   │   ├── gene_identity
    │   │   ├── id
    │   │   ├── location
    │   │   ├── quality_score
    │   │   ├── status
    │   │   ├── uuid
    │   │   └── valid
    │   ├── [X,Y]
[...]

The /density array and associated attributes contain transcript density bin information, which is shown in the analysis_summary.html Region Details panel and in the transcript density view in Xenium Explorer.

The /grids arrays contain a pyramid structure of downsampled transcript levels. The transcript information is stored in this structure as a way to divide it into smaller chunks and for subsampling at zoomed out views. The number of levels corresponds to the selected tissue region size; smaller regions require fewer levels to store subsampled transcript information.

For example, if there are seven levels in total, grids/0 is the most zoomed in level and grids/6 is the most zoomed out level. The most zoomed out level contains a subsample of the transcript information and can fit in a single file (0,0). The most zoomed in level describes where every transcript is located, and consequently the chunks of data need to be stored in more files ((0,0), (0,1), etc.); the arrangement of the files is specified in the file names.

Arrays

Description for root group arrays:

Description for /density/gene group arrays:

Description for /grids/[grid_index]/[grid_position] group arrays:

Attributes

Description for root group attributes:

Note: The key root group attributes used by Xenium Explorer are shown above. This is not a comprehensive attribute list from all Xenium Onboard Analysis versions.

Description for /density/gene array attributes:

Description for /grids array attributes:

The cells.zarr.zip and cell_feature_matrix.zarr.zip have cell_id arrays in integer format (uint32). The first column describes the cell_id_prefix. The polygon vertices of all cells in the dataset determine these integer values. The second column describes the dataset_suffix, and is an integer value defaulting to 1 that may be changed to designate cells originating from different datasets.

Other files (e.g., H5/MTX, CSV) have cell_id in string format (e.g., cmlbdfdf-1). To map between these formats, here is the conversion process from integer to string:

1. Convert the cell_id_prefix to its hexadecimal (hex) representation. Pad it with leading zeroes so that it has eight digits (i.e., 3d51 becomes 00003d51).
2. Shift the characters from the normal hex range [0 - 9, a - f] to the range [a - p]:

3. Add a dash and append the dataset_suffix as an unpadded integer.

For example: given an integer cell_id_prefix = 1437536272 and dataset_suffix = 1

1. Hex conversion of prefix = "55af1010"
2. Shifted code = "ffkpbaba"
3. Append suffix for the final string cell_id = "ffkpbaba-1"

This code snippet shows how to read a Zarr array into numpy N-dimensional arrays:

Copy
# Import Python libraries
# This script was tested with zarr v2.13.6
import zarr
import numpy as np

# Function to open a Zarr file
def open_zarr(path: str) -> zarr.Group:
    store = (zarr.ZipStore(path, mode="r")
    if path.endswith(".zip")
    else zarr.DirectoryStore(path)
    )
    return zarr.group(store=store)

# For example, use the above function to open the cells Zarr file, which contains segmentation mask Zarr arrays
root = open_zarr("cells.zarr.zip")

# Look at group array info and structure
root.info
root.tree() # shows structure, array dimensions, data types

# Create cell and nucleus segmentation mask np array objects to read or modify
cellseg_mask = np.array(root["masks"][1])
nucseg_mask = np.array(root["masks"][0])

# Show dimensions of the 2D segmentation mask arrays (also shown in .tree())
# .ndim() shows number of dimensions
# The shape should match the number of pixels in the morphology image.
cellseg_mask.shape
nucseg_mask.shape

# Show max value of cells in the masks (value=0 are background pixels)
# The .max() method counts all the values that are not 0, which should equal
# the total cells detected in the dataset (reported in e.g., analysis_summary.html
# summary tab metric).
cellseg_mask.max()
nucseg_mask.max()

# Examples for exploring file contents
# How to show array
root["masks"][0][0:9] # or root["masks/0"]
root["cell_summary"][0:9]
# How to show attribute values
root.attrs["major_version"]
root.attrs["segmentation_methods"]
# How to list out attribute names and values
dict(root.attrs.items())
dict(root['cell_summary'].attrs.items())

Using the same Python function as above to read in the file, here are a few example lines to view the analysis.zarr.zip and transcripts.zarr.zip arrays and attributes:

Copy
# Read in secondary analysis Zarr arrays
root = open_zarr("analysis.zarr.zip")
# Examples for exploring file contents
# How to show a slice of the clustering_index arrays
root["cell_groups"][0]["indices"][0:9]
# How to show attributes
root["cell_groups"].attrs["group_names"]


# Read in transcripts Zarr arrays
root = open_zarr("transcripts.zarr.zip")
# Examples for exploring file contents
# How to show array info
root['grids'][0]['0,0']['gene_identity'].shape
root['grids'][0]['0,0']['quality_score'][0:9]
root['grids'][0]['0,0']['location'][0:9,]
# How to show array attributes
root.attrs['major_version']
root['density']['gene'].attrs['gene_names'][0:9]