
<LinkableSection id={"relabel-algo"} title={"Relabel"}>

The `relabel` pipeline works by building a 1:1 map between the previously used gene panel and the new gene panel. This map is used to correct the gene labels given to each of the discovered transcripts. After correcting the labels, all results are recomputed using the same methods employed by the [Xenium Onboard Analysis pipeline](/support/software/xenium-onboard-analysis/latest/algorithms-overview/xoa-algorithms).

</LinkableSection>

<LinkableSection id={"reseg-algo"} title={"Resegment"}>
</LinkableSection>

<LinkableSection id={"reseg-algo-nucleus"} title={"Nucleus segmentation"} nested={true}>

The `resegment` pipeline uses the same nucleus segmentation model as the corresponding Xenium Onboard Analysis (XOA) version's segmentation algorithm. For example, Xenium Ranger v3.0 uses the nucleus segmentation model included in the XOA v3.0 release. XOA segmentation algorithm changes by software version are summarized in [this table](/support/software/xenium-ranger/3.1/getting-started#seg-algo-table).

Nucleus segmentation will always be done using the 3D DAPI Z-stack image. Nuclei are filtered by 95th percentile pixel intensity (the intensity threshold can be adjusted with the `--dapi-filter` parameter).
</LinkableSection>

<LinkableSection id={"reseg-algo-cell"} title={"Cell segmentation"} nested={true}>

See [Xenium Onboard Analysis](/support/software/xenium-onboard-analysis/latest/algorithms-overview/segmentation#seg) algorithm overview for details about the nuclear expansion-only and multimodal cell segmentation algorithms.

**Resegment with multimodal cell segmentation**

In the Xenium Onboard Analysis pipeline v2.0 and later, the multimodal cell segmentation algorithm results are prioritized in this order for each cell:

- **Segment cells based on their cell boundary stain:** The inferred segmentation from this method should be closest to the true cell membrane boundary. It uses cell-surface marker antibodies to target epithelial markers (ATP1A1, E-Cadherin) and immune markers (pan-lymphocyte: CD45). This method can split nuclei, define cells missing a nucleus, and identify multinucleate cells. Nuclei that overlap with anucleate cells are assigned to the cell.
- **Segment cells based on expansion from the nucleus to the cell interior stain edge:** This method includes both a deep learning model and a nuclear expansion method using the interior stain to infer cell boundaries. It uses the interior stain (18S rRNA marker) and the DAPI stain for nuclei.
- **Nuclear expansion:** For cases where cells that do not have boundary or interior stains, segment cells with a nuclear (DAPI) expansion distance of 5 &micro;m or until another cell boundary is encountered (described more on the [XOA segmentation algorithms page](/support/software/xenium-onboard-analysis/latest/algorithms-overview/segmentation#seg-nucleus-expansion)).

In Xenium Ranger:

- If `--boundary-stain` is enabled (default), the algorithm will do cell segmentation using the selected boundary stain and DAPI nuclear expansion for any cells that do not have a boundary stain. If disabled, Xenium Ranger will not use the boundary stain segmentation method.
- If `--interior-stain` is enabled (default), the algorithm will do interior segmentation and expansion with selected stain and DAPI nuclear expansion for any cells that do not have an interior stain. If disabled, Xenium Ranger will not use the interior stain segmentation method.

Next, **if boundary cell segmentation results are available**, Xenium Ranger can assign nuclei that overlap significantly with a boundary-segmented cell to that cell. A boundary-segmented cell can have multiple overlapping nuclei. For each nucleus, if 50% or more of that nucleus _overlaps with the cell boundary_, the overlapping portion of the nucleus is assigned to that cell. For each nucleus, if 50% or more of that nucleus is _outside the boundary-segmented cell_, the algorithm designates it as a new nucleus outside of that cell and continues to the next prioritized segmentation method (interior segmentation or free expansion). This guarantees that a nucleus will never partially overlap a boundary-segmented cell in the final result. If the nucleus and cell overlap is < 50%, it will be removed from the outputs.

For the remaining nuclei, **if interior segmentation is available**, the algorithm then finds the nuclei that have significant overlap with the interior stain and expands those nuclei with the interior stain mask. Finally, the remaining nuclei that do not overlap significantly with either boundary-segmented or interior-segmented cells will expand isotropically by the `--expansion-distance` parameter (5 &micro;m default in v2.0).

</LinkableSection>

<LinkableSection id={"import-seg-algo"} title={"Import-segmentation"}>

Xenium Ranger can import a variety of community-developed and XOA segmentation formats. XOA segmentation algorithm changes by software version are summarized in [this table](/support/software/xenium-ranger/3.1/getting-started#seg-algo-table).

The methods used to incorporate new segmentations fall under three scenarios (read more below):

1. Import nucleus and cell labeled segmentation masks (TIFF or NPY), where each pixel is an integer corresponding to the cell ID
1. Import nucleus and cell segmentation polygons (GeoJSON)
1. Import transcript-based segmentations

For every scenario, a unique random ID is assigned to each cell in the same [string format](/support/software/xenium-onboard-analysis/latest/advanced/xoa-output-zarr#cellID) used by the XOA pipeline.

</LinkableSection>

<LinkableSection id={"import-mask"} title={"Segmentation masks"} nested={true}>

In scenario 1, if the user only imports a nuclear segmentation mask, then a new cell segmentation is generated by nuclear expansion. If both nuclei and cells are imported, then Xenium Ranger will inspect the masks for consistency.

- If **nuclei and cells are imported**, imported nuclei are treated as nuclei and imported cells are treated in the same way as boundary-segmented cells (described above for `resegment` pipeline). An imported cell can have multiple overlapping nuclei. For each nucleus, if 50% or more of that nucleus _overlaps with the cell boundary_, the overlapping portion of the nucleus is assigned to that cell. For each nucleus, if 50% or more of that nucleus is _outside the imported cell_, the algorithm designates it as a new nucleus outside of that cell and continues to the next prioritized segmentation method (nuclear expansion). This guarantees that a nucleus will never partially overlap an imported cell in the final result. If the nucleus and cell overlap is < 50%, it will be removed from the outputs.
- If **only cells are imported**, Xenium Ranger will produce two polygon sets and masks in the `cells.zarr.zip` [file](/support/software/xenium-onboard-analysis/latest/advanced/xoa-output-zarr#cells), where the polygon set and mask that are usually reserved for nuclei will be empty.
- If **only nuclei are imported**, Xenium Ranger will isotropically expand using the `--expansion-distance` parameter (5 &micro;m default in v2.0 and later).

</LinkableSection>

<LinkableSection id={"import-polygons"} title={"Segmentation polygons"} nested={true}>

In scenario 2, Xenium Ranger first takes the input GeoJSON polygons and converts them into labeled masks. Given the flexibility of the GeoJSON format, it is possible the input polygons do not fit neatly into a mask. For example, two polygons could overlap one another. In the process of converting polygons into masks, Xenium Ranger detects polygons that overlap one another and marks the overlapping pixels as ambiguous. The ambiguous pixels are then resolved by assigning the pixel to the object with the most neighboring pixels. Metrics are generated to explain how many ambiguous pixels were found. For polygons with holes ("non-simple polygons"), the holes are removed. For cells defined as multipolygons, the cell is removed entirely. Metrics are generated to report these removals. After masks have been generated, _the remaining methods follow scenario 1_.

</LinkableSection>

<LinkableSection id={"import-tx"} title={"Transcript-based segmentation"} nested={true}>

In scenario 3, when importing a transcript-based segmentation, Xenium Ranger records the cell assignments for each of the transcripts. Subsequently, all results are recomputed using the imported transcript assignments. When constructing the cell-feature matrix, Xenium Ranger uses the transcript quality score from the [transcripts output file](/support/software/xenium-onboard-analysis/latest/analysis/xoa-output-understanding-outputs#transcript-file) and only includes transcripts with Q-score ≥ 20. If any cells only have low quality transcripts, this will result in cells with zero transcripts in the cell-feature matrix file.

As mentioned [above](/support/software/xenium-ranger/3.1/algorithms-overview/XR-algorithms-doc#import-polygons), there can potentially be issues in converting imported polygons into a mask. For the case of importing transcript assignments, Xenium Ranger will not try to convert the visualization polygons into a mask. Instead, it will generate an empty mask and leave the polygons untouched.

To combine spatial data in the `--viz-polygons` GeoJSON with transcript data in the `--transcript-assignment` segmentation CSV, Xenium Ranger matches the CSV file's integer suffix (e.g., "3" in `cell` = "CRc17aaabcd-3" for a Baysor ID) to the GeoJSON file's integer value (e.g., `"cell":3` for a Baysor ID). Every cell in the visualized polygons must have a transcript assigned to it or Xenium Ranger will error. See this [Knowledge Base article](https://kb.10xgenomics.com/hc/en-us/articles/29144571911821-How-can-I-ensure-each-cell-has-a-high-quality-transcript-when-importing-third-party-segmentation-for-Xenium-Ranger) for information about cleaning transcript-based segmentation inputs.

**How do transcript-based method (i.e., Baysor) cell IDs map to Xenium Ranger cell IDs?**

The Xenium `label_id` is found in the `cell_boundaries` [file](/support/software/xenium-onboard-analysis/latest/analysis/xoa-output-understanding-outputs#segmentation) and corresponds to the integer value of segmentation mask image pixels for non-transcript-assignment segmentations. It is always contiguous from 1 - N, where N is the number of cells.

Xenium Ranger `import-segmentation` sorts the imported cell ID integer suffixes (e.g., "3" in "CRc17aaabcd-3" for a Baysor ID) and then maps them to `label_ids` 1 - N.

If the imported cell IDs skip any integers or start from 0 instead of 1, they will be shifted relative to the Xenium `label_id`.

</LinkableSection>


Xenium Ranger Algorithms Overview

Overview

Getting Started

Download Center

Xenium Ranger Commands

Analysis

Algorithms

Advanced

Troubleshooting

Release Notes

Xenium Onboard Analysis

Xenium Explorer

Example Datasets

Analysis Guides

Xenium Ranger 3.1

Xenium Ranger

Learn more about input files required for Xenium Ranger

Inputs

Input Overview

Segmentation Inputs

Learn how to run Xenium Ranger subcommands.

Running Pipelines

Guidance for choosing a Xenium Ranger pipeline.

Choosing a Pipeline

Relabel

Rename

Modify the Xenium Onboard Analysis cell segmentation results.

Resegment

Import segmentation results from community-developed tools.

Import-segmentation

Learn more about output files generated by Xenium Ranger

Outputs

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. Xenium Ranger provides flexible off-instrument reanalysis of Xenium In Situ data. Relabel transcripts, resegment cells, import your own segmentation data, or rename datasets.

What is Xenium Ranger?

Learn about Xenium Ranger, software compatibility, and analysis workflows.

Getting Started with Xenium Ranger

New to Xenium Ranger?

We provide resources from protocols, user guides, and free-to-use analysis tools.

View the latest updates to Xenium Ranger algorithms.

View the latest updates to Xenium Ranger.

Learn more about Xenium In Situ instrument analysis software.

Visualize data from Xenium In Situ solutions.

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

Access free, publicly available data generated with Xenium In Situ solutions.

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