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.

In the sections below, we describe the group arrays and attributes associated with each Zarr file in the Xenium output bundle.

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 (csc/ added in XOA v3.1):

Copy
(root)
└── cell_features
    ├── cell_id
    ├── csc
    │   ├── data
    │   ├── indices
    │   └── indptr
    ├── 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
├── metrics_density
├── density
│   └── gene
│       ├── data
│       ├── indices
│       └── indptr
└── grids
    ├── 0
    │   ├── 0,0
    │   │   ├── codeword_identity
    │   │   ├── gene_identity
    │   │   ├── gene_offset
    │   │   ├── id
    │   │   ├── location
    │   │   ├── quality_score
    │   │   ├── status
    │   │   ├── uuid
    │   │   └── valid
    │   ├── 0,1
    │   │   ├── codeword_identity
    │   │   ├── gene_identity
    │   │   ├── gene_offset
    │   │   ├── 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"