<LinkableSection id={"intro"} title={"Overview"}>

Starting in XOA v3.2, the `gene_panel.json`, `analysis_summary.html`, and `transcripts.parquet` files will display additional information when Xenium Prime 5K datasets contain pre-designed genes with additional probe sets per gene ("gene boosting"). Learn more about gene boosting in the panel design process on the [Xenium Panel Designer website](/support/software/xenium-panel-designer/latest/tutorials/xenium-panel-design-concepts-terms).

<SupportCallout level={"warning"}>{"While no impact on assay performance is anticipated, 10x Genomics does not support or experimentally validate the use of custom probes, and thus cannot guarantee that custom probes will successfully detect their targets."}</SupportCallout> 

</LinkableSection>

<LinkableSection id={"gene-panel"} title={"Gene panel JSON"}>

The `gene_panel.json` format is unchanged, however boosted genes will be listed twice: 1) with the 10x Genomics pre-designed `gene_coverage` and 2) with the boosted `gene_coverage` and `source` information.

Below is an example where the original coverage for ACKR3 is 3 probe sets and the boosted coverage is 5 probe sets, for a total of 8 probe sets for this gene:

```
{
 "codewords": [
 5226,
 6589,
 17780
 ],
 "info": {
 "gene_coverage": 3
 },
 "source": {
 "category": "base",
 "identity": {
 "design_id": "hAtlas_v1.1",
 "name": "Xenium Human 5K Pan Tissue & Pathways Panel",
 "version": "1.1.0"
 }
 },
 "type": {
 "data": {
 "id": "ENSG00000144476",
 "name": "ACKR3"
 },
 "descriptor": "gene"
 }
},
{
 "codewords": [
 9397,
 17171,
 4676,
 2240,
 11249
 ],
 "info": {
 "gene_coverage": 5
 },
 "source": {
 "category": "current",
 "identity": {
 "design_id": "XXXXXX",
 "name": "hMulti_100g",
 "version": "1.0.0"
 }
 },
 "type": {
 "data": {
 "id": "ENSG00000144476",
 "name": "ACKR3"
 },
 "descriptor": "gene"
 }
}
```

</LinkableSection>

<LinkableSection id={"analysis-summary"} title={"Analysis summary file"}>

The `analysis_summary.html` file provides information about boosted genes on the Summary, Decoding, and Cell segmentation tabs.

On the **Summary tab**, the Panel Specification table provides the number of boosted genes as part of "Total custom targets (RNA)" metric.

Both plots on the **Decoding tab** include a category called "Boosted Genes". In particular, the Gene-Specific Transcript Quality plot shows the breakdown of mean Q-Score and total transcript information, which help to assess added probe performance, when hovering over the boosted gene point on the plot. For the example below, the mean Q-Score and total transcripts metrics are shown per gene for:

- Total: the combined result from add-on + pre-designed probe sets
- Add-on probe sets: the added probe sets result alone (light blue diamond icon)
- Pre-designed probe sets: the original pre-designed probe sets result alone (purple circle icon)

In this example, gene boosting added 78.1k transcripts for this gene:

<Flex style={{
 justifyContent: "center"
}}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1732740399/software-support/Xenium-onboard-analysis/analysis_summary_html/gene-specific-txquality-with-boost.png"} width={"500px"} length={"500px"} />
</Flex>
 

The Counts per Gene plot also indicates the number of transcripts from add-on probe sets and pre-designed probe sets. In this example, gene boosting added 283 transcripts for this gene:

<Flex style={{
 justifyContent: "center"
}}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1732732685/software-support/Xenium-onboard-analysis/analysis_summary_html/gene-count-with-gene-boost.png"} width={"500px"} length={"500px"} />
</Flex>
 

The metrics in the **Decoding tab** Decoding Yield and **Cell Segmentation tab** Segmentation Metrics
include separate metrics for pre-designed genes and custom genes. If boosted genes are present, transcripts from boosted genes are included in the pre-designed gene metrics. For example:

- The `median predesigned transcripts per cell` metric is calculated as the median number of high-quality (Q >= 20) transcripts per cell from pre-designed genes (10x-designed) _and_ boosted genes (pre-designed genes for which extra probe sets were added).
- The `median custom transcripts per cell` metric does not include counts from boosted genes.

</LinkableSection>

<LinkableSection id={"transcripts"} title={"Transcripts parquet file"}>

To assess add-on probe performance further, use the `codeword_category` column (2nd to last column) in the `transcripts.parquet` file. You can examine information for transcripts (`predesigned_gene`) targeted by the pre-designed probes vs. transcripts (`custom_gene`) targeted by the added probes.

Add-on probe performance can be assessed with the plots and metrics described above in the `analysis_summary.html` and the `transcripts.parquet` file for XOA v3.2 outputs. For XOA v3.0 - 3.1 data, you can examine the `transcripts.parquet` file to distinguish the contributions from pre-designed vs. added probes.

```python language="python"
import dask.dataframe as dd

# Read in the parquet file, edit path to where parquet file saved
df = dd.read_parquet('transcripts.parquet')

# Print information about the data frame
df.info()

# Print first 5 rows of the dask data frame
df.head()

# Subset by the boosted gene, example is IL1B
boosted_genes = df[df['feature_name'] == 'IL1B']
print(boosted_genes.compute())

# save the subset as a CSV
boosted_genes.to_csv('subset_IL1B_transcript_info', index=False)
```

The subset CSV file looks something like this (scroll right to see the `codeword_category` distinction):

```python language="python"
transcript_id,cell_id,overlaps_nucleus,feature_name,x_location,y_location,z_location,qv,fov_name,nucleus_distance,codeword_index,codeword_category,is_gene
281474976719863,fajfmnbb-1,0,IL1B,37.453125,64.5625,19.09375,40.0,Y12,3.046875,383,predesigned_gene,True
281474976719903,fbifjjcc-1,0,IL1B,64.46875,110.28125,15.3125,30.25,Y12,1.140625,383,predesigned_gene,True
281474976719934,fcknkoij-1,0,IL1B,83.65625,125.328125,15.4375,40.0,Y12,0.28125,383,predesigned_gene,True
281474976719949,fclbhomd-1,1,IL1B,92.5,122.328125,17.171875,40.0,Y12,0.0,383,predesigned_gene,True
281474976719954,fclbhomd-1,0,IL1B,93.328125,122.734375,18.46875,40.0,Y12,0.265625,383,predesigned_gene,True
...
281474976710687,fchcbdda-1,0,IL1B,7.078125,227.125,14.75,40.0,Y12,1.78125,416,custom_gene,True
281474976710696,faljlgoo-1,0,IL1B,10.140625,39.546875,15.0,40.0,Y12,1.421875,416,custom_gene,True
281474976710741,fahehfcf-1,0,IL1B,15.890625,53.890625,18.765625,40.0,Y12,1.703125,416,custom_gene,True
281474976710771,faflhkgm-1,0,IL1B,20.3125,23.359375,17.0,40.0,Y12,1.578125,416,custom_gene,True
281474976710773,UNASSIGNED,0,IL1B,18.171875,246.78125,18.03125,40.0,Y12,5.765625,416,custom_gene,True
281474976710783,fahklcna-1,0,IL1B,20.453125,102.78125,18.796875,40.0,Y12,3.453125,416,custom_gene,True
...
```

</LinkableSection>

Overview

Gene panel JSON

Analysis summary file

Transcripts parquet file

Boosted Genes Outputs

Xenium Onboard Analysis

Xenium

Gene Expression

Our diverse panel menu of pre-validated biologically relevant targets can be customized with up to 100 additional targets. Standalone custom panels can also be designed for your specific research questions.

Expertly curated, easily customizable in situ panels

Xenium Analyzer

Powerful in situ profiling platform using curated panels, powerful visualization software, and easy-to-follow workflow.

In Situ Gene Expression

Enables subcellular profiling of 100s of RNA targets from Fresh Frozen or FFPE tissues.

Details about the algorithms and output files generated by the Xenium Onboard Analysis pipeline.

Outputs for Boosted Genes on Xenium Prime 5K Custom Panels

On this page, we provide some example code from a few commonly used software packages to help you start exploring several Xenium Onboard Analysis output file formats. Read this [Analysis Guide](/analysis-guides/continuing-your-journey-after-xenium-analyzer) for an introduction to a variety of analysis tools for data exploration and downstream analysis.

<SupportCallout level={"info"}>10x Genomics does not provide support for community-developed tools and makes no guarantees regarding their function or performance. Please contact tool developers with any questions.</SupportCallout>

<LinkableSection id={"view-imgs"} title={"Multi-file OME-TIFF images"}>

[Multi-file OME-TIFF images](/support/software/xenium-onboard-analysis/3.4/analysis/xoa-output-understanding-outputs#images) can be viewed with the commonly used Python package, [Tifffile](https://pypi.org/project/tifffile). However, it does not open downsampled multi-file images by default. Downsampled images may be useful for converting to other image file types or for viewing the image if the full resolution is too large. The code snippet below illustrates how to open either full or downsampled resolution images.

To open all of the multi-tissue stain images together, all four `morphology_focus_xxxx.ome.tif` files must be present in the `morphology_focus/` directory.

```python language="python"
# Import Python libraries
# This code uses python v3.12.0, tifffile v2023.9.26, matplotlib v3.8.2
import tifffile
import matplotlib.pyplot as plt

# Option 1: Load full resolution image channels
# The following may produce a warning: 'OME series cannot read multi-file pyramids'. This is because tifffile does not support loading a pyramidal multi-file OME-TIFF file. Only the full resolution (level=0) data will load for all channels in the directory.
fullres_multich_img = tifffile.imread(
"morphology_focus/morphology_focus_0000.ome.tif", is_ome=True, level=0, aszarr=False)

# Examine shape of array (number of channels, height, width), e.g. (4, 40867, 31318)
fullres_multich_img.shape

# Extract number of channels, e.g. 4
n_ch = fullres_multich_img.shape[0]

# Plot each channel
fig, axes = plt.subplots(ncols=n_ch, nrows=1, squeeze=False)
for i in range(n_ch):
 axes[0, i].imshow(fullres_multich_img[i], cmap="gray")
 axes[0, i].set_title(f"Channel: {i}")
plt.savefig('tifffile_fullres_four_channels.png')

# Option 2: Load a single channel image at any resolution, e.g., level=0 or level=1. Note 'is_ome' is set to False.
# Load one of the multi-file OME-TIFF files as a regular TIFF file at full resolution.
fullres_img_tiff = tifffile.imread(
 "morphology_focus/morphology_focus_0000.ome.tif", is_ome=False, level=0)

# Now load the file at downsampled resolution
downsampled_img = tifffile.imread(
 "morphology_focus/morphology_focus_0000.ome.tif", is_ome=False, level=1)
# Examine shape of array (number of channels, height, width)
downsampled_img.shape

# Plot the full resolution and downsampled images side-by-side
fig, axes = plt.subplots(ncols=2, nrows=1, squeeze=False)
axes[0, 0].imshow(fullres_img_tiff, cmap="gray")
axes[0, 0].set_title(f"Full resolution: {fullres_img_tiff.shape}")
axes[0, 1].imshow(downsampled_img, cmap="gray")
axes[0, 1].set_title(f"Downsampled: {downsampled_img.shape}")
plt.savefig('example_fullres_downsample.png')
```

</LinkableSection>

<LinkableSection id={"parquet"} title={"Parquet files"}>

Some Xenium Onboard Analysis output files are provided in the [Parquet](https://parquet.apache.org/docs/file-format) file format to enable faster loading and reading of data. The code below can be used to explore any of the XOA [cell Parquet files](/support/software/xenium-onboard-analysis/3.4/analysis/xoa-output-understanding-outputs#segmentation) (`cell_boundaries.parquet`, `cells.parquet`, and `nucleus_boundaries.parquet`) or [transcript Parquet file](/support/software/xenium-onboard-analysis/3.4/analysis/xoa-output-understanding-outputs#transcript-file) (`transcripts.parquet`).

**We highly recommend working with the Parquet file format itself.** However, if the CSV format is needed, the examples below demonstrate how to use either Python or R packages to view and convert the `transcripts.parquet` file to CSV format. For larger datasets, you may encounter memory limits for reading and converting the data to CSV. In these situations, we suggest writing the CSV file in chunks.

The example for Python uses [dask](https://docs.dask.org/en/latest/install.html). See the documentation for installation and usage guidance.

```python language="python"
# Import Python libraries
# Examples tested with python v3.12.0, dask v2024.5.2
import dask.dataframe as dd

# Read in the parquet file, edit path to where parquet file saved
df = dd.read_parquet('path/to/your/transcripts.parquet')
# Print information about the data frame
df.info()
# Print first 5 rows of the dask data frame
df.head()

# Optional: convert parquet data frame to CSV, edit path and output name for new file
# dask automatically figures out chunk size and saves each as a CSV file in the directory path specified below
df.to_csv('path/to/your/transcripts_csv_directory', index=False)
```

The example for R uses the [arrow](https://arrow.apache.org/docs/r) package. See the documentation for installation and usage guidance.

For Windows, Mac, or Linux, install in R with `install.packages('arrow')`. Alternatively, install with conda: `conda create -n r -c conda-forge r-base r-arrow`.

```r language="r"
# Install arrow with this command:
# install.packages('arrow')
# If not already installed, install 'data.table' as well.

# Import R package
library(arrow)

# Path to your parquet file, edit path to where parquet file saved
PATH <- 'transcripts.parquet'
# Edit path and output name for new file
OUTPUT <- gsub('\\.parquet$', '.csv', PATH)
# Specify chunk size
CHUNK_SIZE <- 1e6

# Read in the parquet file
# This reads in the data as an arrow table
parquet_file <- arrow::read_parquet(PATH, as_data_frame = FALSE)
# To read in the table as a tibble, set data frame to true:
# parquet_file <- arrow::read_parquet(PATH, as_data_frame = TRUE)

# Optional: convert parquet data frame to CSV.
start <- 0
while(start < parquet_file$num_rows) {
 end <- min(start + CHUNK_SIZE, parquet_file$num_rows)
 chunk <- as.data.frame(parquet_file$Slice(start, end - start))
 data.table::fwrite(chunk, OUTPUT, append = start != 0)
 start <- end
}
if(require('R.utils', quietly = TRUE)) {
 R.utils::gzip(OUTPUT)
}
```

</LinkableSection>

<LinkableSection id={"json"} title={"Panel JSON file"}>

Python or other tools can be used to parse the [gene panel JSON file](/support/software/xenium-onboard-analysis/3.4/analysis/xoa-output-understanding-outputs#panel). Here is example Python code to extract gene name, Ensembl ID, and gene coverage information for each gene target in a given panel:

```python language="python"
# Import Python libraries
# Example with python v3.12, pandas v2.1.1
import json
import pandas as pd

# Open JSON file
f = open('gene_panel.json') # Edit file name here

# Return JSON object as a dictionary
data = json.load(f)

# Create lists to store extracted information
gene = []
ensembl = []
cov = []
# Iterate through the JSON list to extract information
for i in data['payload']['targets']:
 if (i['type']['descriptor'] == "gene"): # Only collect info for genes, not controls
 gene_name = i['type']['data']['name']
 ensembl_id = i['type']['data']['id']
 coverage = str(i['info']['gene_coverage'])

 gene.append(gene_name)
 ensembl.append(ensembl_id)
 cov.append(coverage)

# Create output CSV file
out_df = pd.DataFrame(list(zip(gene, ensembl, cov)), columns=['Gene name', 'Ensembl ID', 'Gene coverage'])
out_df.to_csv('my_panel_gene_info.csv', index=False)

# Close file
f.close()
```

</LinkableSection>

<LinkableSection id={"zarr"} title={"Zarr files"}>

The `zarr` Python library documentation and tutorials are available [here](https://zarr.readthedocs.io/en/stable/tutorial.html). These code snippets below show how to read a Zarr array into `numpy` [N-dimensional arrays](https://numpy.org/doc/stable/reference/arrays.ndarray.html). This code can be used to explore any of the XOA [Zarr output files](/support/software/xenium-onboard-analysis/3.4/advanced/xoa-output-zarr): `cells.zarr.zip`, `analysis.zarr.zip`, `cell_feature_matrix.zarr.zip`, and `transcripts.zarr.zip`.

In this first example, we read in the `cells.zarr.zip` file and take a look at the file's structure:

```python language="python"
# Import Python libraries
# This script was tested with zarr v2.13.6, v2.18.3, and v3.0.5
import zarr
import numpy as np

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

# 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:

```python language="python"
# 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]
```

</LinkableSection>

Multi-file OME-TIFF images

Parquet files

Panel JSON file

Zarr files

Code examples

Viewing Output Files with Example Code

<LinkableSection id={"metadata"} title={"Field descriptions"}>
The `experiment.xenium` file is an output from the Xenium Onboard Analysis pipeline. The metadata fields in this file are described below:

| Field | Description |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `major_version` | Indicates major version of analysis output file formats read by Xenium Explorer |
| `minor_version` | Indicates minor version of analysis output file formats read by Xenium Explorer |
| `patch_version` | Patch version of analysis output file formats read by Xenium Explorer |
| `run_name` | User-specified Run Name entered on instrument |
| `run_start_time` | Instrument run start time |
| `region_name` | User-specified name for region selected on instrument |
| `preservation_method` | User-specified sample preservation method |
| `num_cells` | Cells detected by Xenium Onboard Analysis pipeline |
| `transcripts_per_cell` | Median transcripts per cell calculated by Xenium Onboard Analysis pipeline |
| `transcripts_per_100um` | Transcripts per 100 &micro;m2 calculated by Xenium Onboard Analysis pipeline |
| `region_area` | Total area of imaged field of views (FOVs) |
| `total_cell_area` | Summed area of detected cells |
| `thickness_of_high_quality_decoded_transcripts` | Width in Z of high-quality transcripts measured in microns |
| `non_zero_matrix_entries` | Number of nonzero entries in the sparse CSC cell-feature matrix in the `cell_feature_matrix.zarr.zip` file |
| `nuclear_transcripts_per_100um` | Number of high-quality, decoded-to-gene nuclear transcripts divided by the total segmented nuclear area |
| `num_transcripts` | Total number of transcripts including low-quality transcripts |
| `num_transcripts_high_quality` | Total high quality decoded transcripts (≥ Q20) |
| `fraction_transcripts_assigned` | Percent of high-quality transcripts that are found within cells |
| `segmented_cell_stain_frac` | Sum of `segmented_cell_boundary_frac` and `segmented_cell_interior_frac` |
| `segmented_cell_boundary_frac` | Number and percent of cells where the cell segmentation boundary is derived from the boundary stain |
| `segmented_cell_interior_frac` | Number and percent of cells where the boundary is from expansion of the nucleus using interior stain information |
| `segmented_cell_nuc_expansion_frac` | Number and percent of cells where the boundary is an isotropic expansion from the nucleus boundary |
| `imported_cell_frac` | Fraction of cells that were imported by Xenium Ranger `import-segmentation` |
| `cassette_name` | User-specified Xenium Cassette Name entered on instrument |
| `slide_id` | User-specified Xenium Slide ID entered on instrument |
| `panel_type` | Panel type specified by the `gene_panel.json` file ("Predesigned", "custom", or "add_on") |
| `panel_design_id` | Panel design ID specified by panel selection on instrument (additionally `panel_predesigned_id` is included for add-on custom panel designs) |
| `panel_designer_version` | Xenium Panel Designer software version used for the custom panel design |
| `panel_name` | Panel name specified by panel selection on instrument |
| `panel_organism` | Sample organism specified by selected gene panel |
| `panel_tissue_type` | User-specified tissue type selected on instrument |
| `panel_num_targets_predesigned` | Number of gene targets from the pre-designed gene panel |
| `panel_num_targets_custom` | Number of gene targets from add-on custom panel if included in panel design |
| `chemistry_version` | Assay chemistry specified by the `gene_panel.json` file ("v1" = Xenium v1, "v2" = Xenium Prime) |
| `pixel_size` | Pixel size in the `morphology.ome.tif` image file (in &micro;m) |
| `instrument_sn` | Xenium Analyzer instrument serial number |
| `instrument_sw_version` | Version of the Xenium Analyzer firmware used during analysis run |
| `analysis_sw_version` | Version of Xenium Onboard Analysis pipeline used to analyze data |
| `analysis_uuid` | Instrument metadata |
| `experiment_uuid` | Instrument metadata |
| `cassette_uuid` | Instrument metadata |
| `roi_uuid` | Instrument metadata |
| `z_step_size` | Z-step size (in &micro;m) used for [subsampling](/support/software/xenium-onboard-analysis/3.4/algorithms-overview/image-processing#dapi) the `morphology.ome.tif` image Z-stacks |
| `well_uuid` | Instrument metadata |
| `calibration_uuid` | Instrument metadata |
| `images` | Specifies the file paths to the morphology image files; used by Xenium Explorer to find input files |
| `xenium_explorer_files` | Specifies the file paths to transcript, cell, secondary analysis, and analysis summary files; used by Xenium Explorer to find input files |
| `segmentation_stain` | Specifies the stain method selected on instrument for cell segmentation ("Xenium Multi-Tissue Stain" or "Nuclei (DAPI)"). |
| `xenium_ranger` | If the data was reanalyzed with Xenium Ranger, this section specifies the `run_id`, Xenium Ranger version, and commands used to analyze the data. |

</LinkableSection>

<LinkableSection id={"expt-file-versions"} title={"Experiment file versions"}>

The `major_version` field in this file indicates when there are changes to Xenium Onboard Analysis (XOA) output file formats that affect forwards-compatibility with other software.

Updates to `major_version` are associated with new releases of the XOA software on the Xenium Analyzer (XA) instrument. This format version is used by Xenium Explorer (XE) and Xenium Ranger (XR) to determine input file compatibility across the Xenium software suite. This table summarizes when file format major versions were introduced by XOA software version.

| XOA version | `experiment.xenium` major version |
| --------------- | --------------------------------- |
| XOA v3.2 - 3.3 | 5.2 |
| XOA v3.1 | 5.1 † |
| XOA v3.0 | 5.0 |
| XOA v2.0 | 4.0 |
| XOA v1.7 - v1.9 | 3.0 |
| XOA v1.6 | 2.0.2 |
| XOA v1.5 | 2.0.1 |
| XOA v1.3 - v1.4 | 2.0 |
| XOA v1.2 | 1.1 |
| XOA v1.0 - v1.1 | (no version fields) |

† Reanalysis with Xenium Ranger v3.0 generates outputs that align with the XA/XOA v3.1 output format and `experiment.xenium` major version v5.1.

</LinkableSection>

Field descriptions

Experiment file versions

Experiment File

Xenium Experiment File Metadata and Versions

<LinkableSection id={"decoding-metric-calc"} title={"Negative control metrics"}>

The [XOA output files](/support/software/xenium-onboard-analysis/3.4/analysis/xoa-output-understanding-outputs) `analysis_summary.html` and `metrics_summary.csv` report negative control metrics.

The "Negative control probe counts per control per cell" metric is derived first from calculating the absolute number of negative control probe counts and then calculating the metric per control probe per cell. The "Estimated number of false positive transcripts per cell" is derived from this metric. Derived values may differ slightly from those reported in summary outputs due to using rounded values.

They are calculated using the following inputs:

- Total high quality decoded transcripts: displayed on the Summary and Decoding tabs, includes genes (Q-Score ≥ 20) and negative controls
- Percent of transcripts within cells: displayed on the Cell Segmentation tab
- **Adjusted negative control probe rate**: displayed on the Decoding tab
- Number of target genes: the sum of genes in the pre-designed panel and any add-on custom genes, displayed on the Summary tab
- **Number of negative control probes in the panel**: in Xenium v1, each pre-designed and add-on panel contains 20 negative control targets (except runs that use the Xenium Mouse Brain base panel, which have 27 negative targets). In Xenium Prime, each pre-designed and add-on panel contains 40 negative control targets.
- Number of cells detected: hero metric on the Summary tab

1. The _Negative control probe count_ is calculated as:

 $$ \footnotesize{\text{Q20 decoded transcripts in cells}\times{\text{Adjusted negative control probe rate}}\times{\frac{\text{Number of negative control probes}}{\text{Number of target genes}}}} $$

 where _Q20 decoded transcripts in cells_ is calculated as:

 $$ \footnotesize{\text{Total high quality decoded transcripts}\times{\text{Percent of transcripts within cells}}} $$

2. The `Negative control probe count per control per cell` is then calculated as:

 $$ \footnotesize{{\text{Negative control probe count}}\div{\text{Number of negative control probes}}\div{\text{Number of cells detected}}} $$

3. The `Estimated number of false positive transcripts per cell` is calculated as:

 $$ \footnotesize{{\text{Negative control probe counts per control per cell}}\times{\text{Number of target genes}}} $$

The calculations for "Genomic control probe counts per control per cell" and "Estimated number of false positive transcripts per cell including genomic counts" are analogous to the calculations shown above. Both metrics are available in outputs generated with Xenium Onboard Analysis v3.0.

The inputs are:

- Total high quality decoded transcripts
- Percent of transcripts within cells
- **Adjusted genomic control probe rate**
- Number of target genes
- **Number of genomic control probes in the panel** (21 for Xenium Prime 5K pre-designed panels)
- Number of cells detected

</LinkableSection>

Negative control metrics

Metric Calculations

Calculating Negative Control Metrics

Cells

Arrays

Attributes

Secondary analysis

Cell-feature matrix

Transcripts

Cell ID format mapping

Explore Zarr files

Overview of Xenium Zarr Output Files

Getting Started

Analysis

Algorithms

Example Datasets

Release Notes

Advanced

Xenium Explorer

Xenium Ranger

Xenium Panel Designer

Analysis Guides

Xenium Onboard Analysis 3.4

Estimate and Monitor Xenium Analyzer Instrument Run Time

Estimate and Monitor Run Time

A table of Xenium onboard analysis pipeline output files.

Outputs at a Glance

Overview of all Xenium onboard analysis pipeline output files.

Understanding Xenium Outputs

Overview of the interactive Xenium analysis summary output file metrics and plots.

Analysis Summary Overview

Troubleshooting guide for the Xenium analysis summary alerts.

Analysis Summary Alerts

Storing Xenium raw data for reanalysis or grant requirements.

Archiving Xenium Data

The Xenium In Situ software suite is a set of software applications for analyzing and visualizing in situ gene expression data produced by the Xenium Analyzer. The Xenium Onboard Analysis pipeline enables simultaneous on-instrument data collection and analysis.

What is Xenium Onboard Analysis?

View the latest updates to Xenium Onboard Analysis algorithms.

View the latest updates to Xenium Onboard Analysis.

Visualize data from Xenium In Situ solutions.

Reanalyze data from Xenium In Situ solutions.

Browse Q&As from the 10x Genomics support team.

A collection of introductions, tutorials, and blogs for data analysis beyond 10x Genomics software.