<LinkableSection id={"overview"} title={"Hardware"}>

Xenium Ranger pipelines run on Linux systems that meet the minimum requirements listed below.

Requirements for `rename` subcommand:

- 8-core processor
- 4GB RAM

Requirements for `relabel`, `resegment`, and `import-segmentation`:

- 8-core Intel or AMD processor (32 cores recommended) with `avx2`
- 64GB RAM (128GB recommended)
- 1TB free disk space
- 64-bit CentOS 7 and later/RedHat 7.4 or Ubuntu 16.04 and later. See the [10x Genomics OS Support](/support/software/cell-ranger/latest/miscellaneous/cr-os-requirements) page on the Cell Ranger support site for additional details.

Running the following tissue area and input data have higher minimum memory requirements:

| Tissue area | Transcript counts | Subcommand | Minimum memory |
| -------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------- | -------------- |
| 1cm2 dataset (e.g., full coronal mouse brain) | 500 million transcripts | Import transcript-assignment and viz-polygons (e.g., from Baysor) | 256GB RAM |
| 2cm2 dataset | 1 billion transcripts | Relabel | 256GB RAM |
| 2cm2 dataset | 1 billion transcripts | Import nucleus and cell boundary (e.g., GeoJSON from QuPath) | 488GB RAM |
| 2cm2 dataset | 1 billion transcripts | Import nucleus and cell label mask (e.g., from Cellpose) | 256GB RAM |

The pipeline can also run on clusters that meet these additional minimum requirements:

- Shared filesystem (e.g. NFS)
- Slurm batch scheduling system

</LinkableSection>

<LinkableSection id={"resource-limits"} title={"Resource limits"}>

- Xenium Ranger runs with `--jobmode=local` by default, using 90% of available memory and all available cores. To restrict resource usage, please see the `--localcores` and `--localmem` arguments for `xeniumranger` subcommands.
- In-house Xenium Ranger testing uses the following settings and we recommend customers do the same: `--localcores=32` and `--localmem=128`.
- Many Linux systems have default user limits (ulimits) for maximum open files and maximum user processes as low as 1024 or 4096. Because Xenium Ranger spawns multiple processes per core, jobs that use a large number of cores can exceed these limits. 10x Genomics recommends higher limits.

| **Limit** | **Recommendation** |
| ---------------- | ----------------------------------------- |
| user open files | 16k |
| system max files | 10k per GB RAM available to Xenium Ranger |
| user processes | 64 per core available to Xenium Ranger |

</LinkableSection>

<LinkableSection id={"computing-options"} title={"Computing options"}>

There are three primary ways to run Xenium Ranger:

1. **Single server**: Xenium Ranger can run directly on a dedicated server. This is the most straightforward approach and the easiest to troubleshoot. The majority of the information on this website uses the single server approach.
2. **[Job submission mode](/support/software/xenium-ranger/3.1/advanced/XR-job-submission-mode)**: Xenium Ranger can run using a _single_ node on the cluster. Less cluster coordination is required since all work is done on the same node. This method works well even with job schedulers that are not officially supported.
3. **[Cluster mode](/support/software/xenium-ranger/3.1/advanced/XR-cluster-mode)**: Xenium Ranger can run using _multiple_ nodes on the cluster. This method provides high performance, but is difficult to troubleshoot since cluster setup varies among institutions.

Recommendations and requirements, in order of computational speed (left to right):
| | Cluster Mode | Job Submission Mode | Single Server |
|---|---|---|----|
| **Recommended for** | Organizations using an HPC with SLURM for job scheduling | Organizations using an HPC | Users without access to an HPC |
| **Compute details** | Splits each analysis across multiple compute nodes to decrease run time | Runs each analysis on a single compute node | Runs each analysis directly on a dedicated server |
| **Requirements** | HPC with SLURM for job scheduling | HPC with most job schedulers |Linux computer with minimum 8 cores & 64 GB RAM (but see [above](#overview)) |

</LinkableSection>

<LinkableSection id={"time-trials"} title={"How memory affects runtime"}>

These runtimes and plots are based on time trials using [Amazon EC2 instances](https://aws.amazon.com/ec2/instance-types) and Xenium Ranger v3.1.0.

<SupportCallout level={"info"}>
<Text as={"span"}>The plots will be updated for subsequent releases of Xenium Ranger if pipeline performance changes significantly.</Text>
</SupportCallout>
 

Below, we show the runtime comparison for several Xenium Ranger pipelines to analyze a 200 FOV Xenium Prime 5K In Situ Gene Expression with Cell Segmentation Staining dataset (514,266,035 transcripts) on a r5.8xlarge Skylake machine with either solid state drive (SSD) or hard disk drive (HDD).

| Analysis | Runtime with SSD | Runtime with HDD |
| ------------------------------------------------- | ---------------- | ---------------- |
| `resegment` | 3h 21m | 3h 27m |
| `relabel` | 1h 14m | 1h 20m |
| Polygon input `import-segmentation` | 1h 33m | 1h 37m |
| Transcript assignment input `import-segmentation` | 1h 35m | 1h 58m |

Shown below is a `xeniumranger resegment` analysis for a 200 FOV Xenium Prime 5K In Situ Gene Expression with Cell Segmentation Staining dataset (514,266,035 transcripts) on a machine with a SSD drive:

- Wall time as a function of memory

<Image src={"https://cdn.10xgenomics.com/image/upload/v1734042968/software-support/Xenium-Ranger/xr3-1_resegment_200fov_walltime_as_memory.png"} />

- Wall time as a function of threads

<Image src={"https://cdn.10xgenomics.com/image/upload/v1734042968/software-support/Xenium-Ranger/xr3-1_resegment_200fov_walltime_as_threads.png"} /> 

Shown below is a `xeniumranger relabel` analysis for a 200 FOV Xenium Prime 5K In Situ Gene Expression with Cell Segmentation Staining dataset (514,266,035 transcripts) on a machine with a SSD:

- Wall time as a function of memory

<Image src={"https://cdn.10xgenomics.com/image/upload/v1734042968/software-support/Xenium-Ranger/xr3-1_relabel_200fov_walltime_as_memory.png"} />

- Wall time as a function of threads

<Image src={"https://cdn.10xgenomics.com/image/upload/v1734042968/software-support/Xenium-Ranger/xr3-1_relabel_200fov_walltime_as_threads.png"} />

</LinkableSection>

System Requirements

<LinkableSection id={"v-3-1-1"} title={"v3.1.1 (March 11, 2025)"}>

- Fixed a bug that could cause XR outputs to be missing all of the transcripts in 250 &micro;m x 250 &micro;m portions of the top and/or left of the image.
- Fixed unintended simplification of cell polygons that were imported using the `--viz-polygons` option.
- Fixed `import-segmentation` bug that causes pipeline to error when the cell with the last index is missing a nucleus.
- Fixed `resegment` pipeline bugs in the multimodal cell segmentation algorithm to prevent crashes in edge cases. This fix does not impact cell segmentation results.

</LinkableSection>

<LinkableSection id={"v-3-1"} title={"v3.1.0 (December 17, 2024)"}>

- Required for reanalysis of Xenium Onboard Analysis v3.2 and upcoming v3.3 data (see [table](/support/software/xenium-ranger/3.1/getting-started#compatibility)).
- Updates file formats to match XOA v3.2:
 - Enables per-codeword localization plots for custom and boosted genes in Xenium Explorer v3.2.
 - Enables QC of boosted genes in analysis summary.
- Multimodal cell segmentation algorithm: improved filtering of incorrect boundary-stain segmentations and merging segmentations of boundary-stain images.
- Bug fixes:
 - Fixed missing `aux_outputs/` directory and Image QC tab in the analysis summary.
 - Fixed misaligned Region Details plot in the analysis summary.
 - Fixed a `resegment` pipeline error that occurs when only `--interior-stain` or only `--boundary-stain` is disabled.
 - Fixed error when transcript-based `--viz-polygons` files are non-cyclic (missing closing vertex point) to enable importing results from Baysor v0.7.

</LinkableSection>

<LinkableSection id={"v-3-0-1"} title={"v3.0.1 (September 19, 2024)"}>

- Fixed a bug where pipeline errors due to the presence of unexpected files in the `aux_outputs/` directory, such as AppleDouble format files created by MacOS.

</LinkableSection>

<LinkableSection id={"v-3-0-0"} title={"v3.0.0 (September 4, 2024)"}>

- Required for reanalysis of Xenium Onboard Analysis v3.0 data (see [table](/support/software/xenium-ranger/3.1/getting-started#compatibility)).
- Reanalyze pre-v3.0 data to convert to XOA v3.0 file formats that support [scaled transcript view](/support/software/xenium-explorer/latest/tutorials/nav-transcripts#scaled-transcripts) in Xenium Explorer v3.0. When reanalyzing XOA v3.0+ data, Xenium Ranger recomputes the transcript clusters in a different order so the scaled transcript view may look slightly different.
- New `xeniumranger rename` [subcommand](/support/software/xenium-ranger/3.1/analysis/running-pipelines/rename) for editing the region name and cassette name specified on instrument.
- When only importing cell segmentations, Xenium Ranger no longer produces synthetic nucleus segmentations because visualization of a single polygon set is now supported in Xenium Explorer v3.0.
 - Importing transcript-based segmentation results with transcript assignments and boundaries will produce only one polygon set in the `cells.zarr.zip`.
 - Importing image-based segmentation results with cells will produce two polygon sets and masks in the `cells.zarr.zip` file, where the polygon set and mask that are usually reserved for nuclei will be empty.
 - Nuclear transcripts per 100 &micro;m2 will be `NaN` because the nuclei boundaries are not defined. Use cellular transcripts per 100 &micro;m2 instead to estimate transcript density.
- Output format changes (will be added to upcoming XOA v3.1 release):
 - The `cell_feature_matrix.zarr.zip` is zstd compressed and includes a compressed sparse column (CSC) matrix representation for enhanced performance of certain features in future Xenium Explorer releases.
 - Upgraded `experiment.xenium` version to v5.1 with new fields: `panel_designer_version`, `num_transcripts`, `num_transcripts_high_quality`, and `non_zero_matrix_entries`
 - `metrics_summary.csv` values truncated to 15 decimal places.
- General bug fixes and improvements:
 - Cell segmentation: Fixed a bug to guarantee every nucleus and cell segmentation mask is a single connected component. Cell segmentation algorithm matches algorithm in XOA v3.0.
 - (Note added 9/19/24) Cell segmentation: Improved multimodal cell segmentation by filtering incorrect segmentations of the boundary-stain images.
 - Robust to [transcript-assignment data](/support/software/xenium-ranger/3.1/analysis/inputs/segmentation-inputs#baysor-segmentation) where one or more cells have no > Q20 transcripts. This fixes a bug in XR v2.0.1 that could result in erroneous transcript assignment to cells when the transcript-assignment CSV included cells with only low-quality transcripts (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 help).

</LinkableSection>

<LinkableSection id={"v-2-0-1"} title={"v2.0.1 (June 10, 2024)"}>

- Fixed a bug that caused `cell_ids` to be misassigned in `transcripts.csv.gz` and `transcripts.parquet` when importing transcript assignments (e.g. from Baysor) with `import-segmentation`. This bug also resulted in erroneous cell-feature matrix files and erroneous counts in `cells.csv.gz`. Any datasets that were segmented with _transcript-based methods_, such as Baysor or Proseg, and _used Xenium Ranger v2.0_ to import transcript assignments, should re-run the analysis using Xenium Ranger v2.0.1.
- Fixed a bug to ensure interior stain-based expansion extends all the way to the neighboring cell's boundary in `resegment`.

</LinkableSection>

<LinkableSection id={"v-2-0-0"} title={"v2.0.0 (April 25, 2024)"}>

- The expansion-distance parameter default is now 5 &micro;m instead of 15 &micro;m for the `resegment` and `import-segmentation` pipelines.
- Segmentation algorithm updates for the `resegment` pipeline:
 - Reanalyze cell segmentation staining workflow data by adjusting the nuclear expansion distance and/or boundary or interior stain used for multimodal cell segmentation, the cell segmentation algorithm introduced in [XOA v2.0](/support/software/xenium-onboard-analysis/latest/release-notes/release-notes-for-xoa). Suboptimal or unsuitable stains can be excluded from the segmentation algorithm by specifying the `interior-stain` or `boundary-stain` arguments.
 - Updated nucleus segmentation ML model to match update in XOA v2.0.
- Updates for `import-segmentation` pipeline:
 - The `xeniumranger resegment --resegment-nuclei` option is deprecated and will be removed in future releases. `resegment` will always resegment nuclei from the input DAPI image. To use the nucleus segmentation from input data and adjust expansion distance, the preferred method is to run `xeniumranger import-segmentation` with `--expansion-distance` and `--nuclei=cells.zarr.zip`, which will use the nucleus segmentation masks from `cells.zarr.zip` file.
 - The `--nuclei` argument no longer needs to be used with `--cells`.
 - The `--cells` and `--nuclei` arguments support `cells.zarr.zip` format and will use the cell and nucleus masks for transcript assignment.
 - New metrics provided in `metrics_summary.csv`: "Number of cell non-simple polygons", "Number of cell multipolygons", "Number of nucleus non-simple polygons", "Number of nucleus multipolygons", "Segmented cell imported fraction", and "Segmented cell imported count". The "Number of cells from imported segmentation" is also reported in the `analysis_summary.html` Segmentation Methods table.
 - The "Percentage of cells without a nucleus" metric has been removed.
- Interrupted runs can be resumed. Issuing the same `xeniumranger` command will now resume execution of the pipestance from the stage that originally failed. See [troubleshooting](/support/software/xenium-ranger/3.1/resources/troubleshooting#resume) page.
- Fixed a bug where Xenium Ranger `import-segmentation` errored if GeoJSON inputs had the `MultiPolygon` type or `Polygon` type with holes. If Xenium Ranger encounters a polygon with a hole, it will remove the hole and retain only the exterior of the polygons (interior edges/segments are removed.) If type `MultiPolygon` is present, they will be ignored and will not be included in the analysis.

</LinkableSection>

<LinkableSection id={"v-1-7-1"} title={"v1.7.1 (January 23, 2024)"}>

- Fixed a bug to improve the method to import segmentation results generated from large image files (i.e., from IF or H&E images).
- Fixed a bug to enable importing segmentation results for smaller regions of the original image data.

</LinkableSection>

<LinkableSection id={"v-1-7"} title={"v1.7.0 (October 9, 2023)"}>

- Supports reanalysis of Xenium Onboard Analysis data up to latest version (see [version compatibility table](/support/software/xenium-ranger/3.1/getting-started/XR-getting-started-with-xenium-ranger#compatibility)).
- The image-based `import-segmentation --coordinate-transform` [option](/support/software/xenium-ranger/3.1/analysis/running-pipelines/XR-import-segmentation#xr-matrix) is now compatible with segmentation masks (previously limited to polygons).
- Improved memory usage in the `import-segmentation` pipeline (see updated [system requirements page](/support/software/xenium-ranger/3.1/release-notes/XR-system-requirements)).
- Fixed bug where input masks with discontinuous cells or nuclei caused Xenium Ranger to occasionally crash. An analysis summary alert was introduced to flag rare scenarios where discontinuities may lead to splitting of imported cells or nuclei.
- Several minor bug fixes in the analysis summary user interface.
- Improved preflight checks.
- Miscellaneous bug fixes.

</LinkableSection>

<LinkableSection id={"v-1-6"} title={"v1.6.0 (August 17, 2023)"}>

- Initial release.
- Resegment Xenium data with customizable nucleus expansion distance and the latest 10x cell segmentation algorithm.
- Import community-developed nucleus and cell segmentations in multiple popular formats (i.e., Baysor).
- Selected the wrong gene panel when you started the Xenium Analyzer run? Simply fix the mistake by using relabel.
- All pipelines produce the same output bundle as Xenium Onboard Analysis v1.6, so they are compatible with the same downstream visualization and analysis softwares (e.g., Xenium Explorer).
- Backwards compatible with all previous Xenium Onboard Analysis versions.

</LinkableSection>

Release Notes for Xenium Ranger

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.