The input files for import-segmentation are:

• The Xenium output bundle generated by the Xenium Onboard Analysis pipeline (see Input overview).
• Segmentation file(s) from community-developed tools (see compatible formats for examples). Xenium Ranger supports importing 2D segmentation results.

The xeniumranger import-segmentation command line arguments are listed on the Xenium Ranger command line arguments page. There are separate command line arguments for Baysor inputs due to differences in how it generates segmentation results.

Here are examples for importing segmentation results from community-developed tools. Make sure to edit the paths to input/output files in the examples below.

Generate polygon segmentation results in GeoJSON format (i.e., from QuPath) and then import:

• polygon.geojson containing GeoJSON polygons
• Note: we recommend including nucleus segmentation when running cell detection so both nucleus and cell segmentations are in one GeoJSON file (default export format for QuPath), with nucleus segmentations named nucleusGeometry.
• Features where object_type is not cell will be ignored (i.e.,annotations).

Example to import nucleus and cell segmentation using a single GeoJSON that contains both:

Copy
# Note: the --cells argument must be run with the --nuclei argument

xeniumranger import-segmentation --id=polygon-demo \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --nuclei=polygon.geojson \
                                 --cells=polygon.geojson \
                                 --units=pixels

You can view the output in Xenium Explorer. For example, here are the cell clusters with nuclei outlines for a mouse pup sample with cell segmentation results generated by QuPath:

Example to only import nucleus segmentation:

Copy
xeniumranger import-segmentation --id=polygon-demo-nuclei \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --nuclei=polygon.geojson \
                                 --units=pixels

Generate 2D mask segmentation results (i.e., 2D from Cellpose) and then import. The nucleus and cell segmentation files can be in either TIFF or NPY format. For example:

• nuclei.tif or nuclei.npy containing nucleus segmentation results
• cells.tif or cells.npy containing cell segmentation results

Example to import nucleus and cell segmentation:

Copy
# Note: the --cells argument must be run with the --nuclei argument

xeniumranger import-segmentation --id=mask-demo-nuclei \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --nuclei=nuclei.tif \
                                 --cells=cells.npy

Example to only import nucleus segmentation:

Copy
xeniumranger import-segmentation --id=mask-demo-cells \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --nuclei=nuclei.tif

Generate segmentation results using transcripts (e.g., Baysor; example analysis) and then import:

• segmentation.csv containing segmentation and transcript assignment results
• segmentation_polygons.json containing GeoJSON polygons

Copy
xeniumranger import-segmentation --id=baysor-demo \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --transcript-assignment=segmentation.csv \
                                 --viz-polygons=segmentation_polygons.json \
                                 --units=microns

For this use case, some nuclei and cell import-segmentation metrics are not computed because a single segmentation_polygons GeoJSON file is imported (compared to the polygon input usage).

You can view the output in Xenium Explorer. For example, here are the cell clusters for a mouse brain sample with cell segmentation results generated by Baysor:

This option enables you to inform your Xenium analysis with cell segmentation based on post-Xenium imaging. You can use Xenium Explorer or community-developed tools to align a post-Xenium H&E or IF image and generate an image alignment transformation matrix for input to Xenium Ranger’s import-segmentation pipeline.

The image alignment file format should be a 3x3 transformation matrix, where the last row is [0,0,1]. It captures the translation, scaling, rotation, and reflection applied to the imported image (see Xenium Explorer's alignment algorithm section). Some image alignment CSV files are available on the Xenium Human Colon Preview dataset page (for Non-diseased, pre-designed panel and Cancer, pre-designed + add-on panel samples).

In this example, the cells and nuclei are segmented on a post-Xenium H&E image using QuPath. The image is then aligned in Xenium Explorer, where the image alignment CSV transformation matrix is downloaded.

To visualize the QuPath cell/nucleus segmentation polygons on the H&E image in Xenium Explorer, we need to import the QuPath results into the Xenium output bundle.

The QuPath GeoJSON segmentation results and the Xenium Explorer matrix CSV are the inputs for Xenium Ranger import-segmentation:

Copy
xeniumranger import-segmentation --id=image-transform-demo \
                                 --xenium-bundle=/path/to/xenium/files \
                                 --coordinate-transform=demo_imagealignment.csv \
                                 --nuclei=qupath.geojson \
                                 --cells=qupath.geojson \
                                 --units=pixels

In Xenium Ranger v1.7, the segmentation results can be in either polygon or mask format.

After running this command, the dataset can be opened in Xenium Explorer to visualize segmentation and transcript results overlaid on the H&E image (select option to upload the image alignment matrix to open the already aligned H&E image).

After the pipeline completes, check the output outs/ directory (see Output overview). For example, look at these files:

• Analysis summary: check metrics and plots on the Cell Segmentation tab. There are new metrics (described below) for imported segmentation results (present in analysis_summary.html and metrics_summary.csv).
• All secondary analysis files
• All cell, nuclei, and transcript files

Morphology images are unchanged. The updated segmentation results can be visualized in Xenium Explorer.

The additional metrics are described below and are generated for scenarios described in the import-segmentation algorithms section.