The import-segmentation
pipeline allows you to specify 2D nuclei and/or cell segmentation results to use for assigning transcripts to cells and recalculate all Xenium Onboard Analysis (XOA) outputs that depend on segmentation. Segmentation results can be generated by community-developed tools or prior Xenium segmentation result.
--transcript-assignment argument
(i.e., Baysor input), the segmentation masks will not be generated in the final output directory. Since the relabel pipeline requires the segmentation mask files, it can NOT be run after import-segmentation with --transcript-assignment
.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.
Below are examples for importing segmentation results from community-developed tools. Make sure to edit the paths to input/output files in the examples below for your own datasets. The examples provide the recommended settings for --localcores
and --localmem
parameter values (see Resource limits for more details).
If you have QC'd the nucleus segmentation in Xenium Explorer and want to adjust the nuclear expansion distance without altering nuclei detection, use the following arguments. Starting in Xenium Ranger v2.0, import-segmentation
with --nuclei=cells.zarr.zip
is the preferred method to import existing nucleus segmentation results, instead of using the resegment
pipeline with --resegment-nuclei=false. This approach is also faster as it skips the nucleus segmentation step.
In this example, say the original dataset was analyzed with 15 µm nuclear expansion distance. Let's adjust it to 5 µm. Since 5 µm is the default value in Xenium Ranger v2.0, --expansion-distance=5
does not need to be specified in this example:
xeniumranger import-segmentation --id=demo \
--xenium-bundle=/path/to/xenium/files \
--nuclei=/path/to/cells.zarr.zip \
--localcores=32 \
--localmem=128
Viewing the original output in Xenium Explorer with a post-Xenium H&E image, the cell and nuclei outlines look like this at 15 µm expansion distance (default in XOA v1.0 - 1.9) for segmentation of cells in the lumen of the human colon:
![](https://cdn.10xgenomics.com/image/upload/v1692226502/software-support/Xenium-Ranger/resegment_15umdist.png)
The same area of the resegment
analysis output with 5 µm expansion distance is shown below. The cell boundaries now better match the biology of the sample indicated in the H&E image:
![](https://cdn.10xgenomics.com/image/upload/v1692226501/software-support/Xenium-Ranger/resegment_5umdist.png)
To import XOA segmentation results and create a nucleus-only count matrix, set the expansion distance to 0 µm:
xeniumranger import-segmentation --id=demo \
--xenium-bundle=/path/to/xenium/files \
--nuclei=/path/to/cells.zarr.zip \
--expansion-distance=0 \
--localcores=32 \
--localmem=128
Generate polygon segmentation results in GeoJSON format (i.e., from QuPath) and then import. QuPath input file specifications are described here.
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 notcell
will be ignored (i.e.,annotations
).
Example to import nucleus and cell segmentation using a single GeoJSON that contains both:
xeniumranger import-segmentation --id=polygon-demo \
--xenium-bundle=/path/to/xenium/files \
--nuclei=polygon.geojson \
--cells=polygon.geojson \
--units=pixels \
--localcores=32 \
--localmem=128
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:
![](https://cdn.10xgenomics.com/image/upload/v1692292511/software-support/Xenium-Ranger/import-segmentation-qupath-zoom-out.png)
![](https://cdn.10xgenomics.com/image/upload/v1692292511/software-support/Xenium-Ranger/import-segmentation-qupath-cell-nuclei-outline.png)
Example to only import nucleus segmentation below. If unspecified, Xenium Ranger will use the default nuclear expansion distance (5 µm):
xeniumranger import-segmentation --id=polygon-demo-nuclei \
--xenium-bundle=/path/to/xenium/files \
--nuclei=polygon.geojson \
--units=pixels \
--localcores=32 \
--localmem=128
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
ornuclei.npy
containing nucleus segmentation resultscells.tif
orcells.npy
containing cell segmentation results
Example to import nucleus and cell segmentation:
xeniumranger import-segmentation --id=mask-demo-nuclei \
--xenium-bundle=/path/to/xenium/files \
--nuclei=nuclei.tif \
--cells=cells.npy \
--localcores=32 \
--localmem=128
Example to only import nucleus segmentation below. If unspecified, Xenium Ranger will use the default nuclear expansion distance (5 µm):
xeniumranger import-segmentation --id=mask-demo-cells \
--xenium-bundle=/path/to/xenium/files \
--nuclei=nuclei.tif \
--localcores=32 \
--localmem=128
Transcript-based segmentation methods like Baysor and Proseg are alternatives to image-based segmentation. They convert in situ RNA data into single cell data when cell stain images are insufficient for capturing the morphology of cells in tissue. They use the gene identity and location of transcripts to assign them to cells and draw cell boundaries.
Generate segmentation results using ≥ Q20 transcripts (e.g., Baysor v0.6) and then import. Baysor input file specifications are described here.
segmentation.csv
containing segmentation and transcript assignment resultssegmentation_polygons.json
containing GeoJSON polygons
xeniumranger import-segmentation --id=baysor-demo \
--xenium-bundle=/path/to/xenium/files \
--transcript-assignment=segmentation.csv \
--viz-polygons=segmentation_polygons.json \
--units=microns \
--localcores=32 \
--localmem=128
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). Mapping between transcript-based method and XOA cell IDs is described on the algorithms page.
View the output in Xenium Explorer
Here is an example showing the cell clusters for a mouse brain sample with cell segmentation results generated by Baysor:
![](https://cdn.10xgenomics.com/image/upload/v1692224756/software-support/Xenium-Ranger/import-segmentation-baysor.png)
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
:
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 \
--localcores=32 \
--localmem=128
In Xenium Ranger v1.7 and later, 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
andmetrics_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.
Import-segmentation metrics | Description |
---|---|
Percentage of pixels found to be ambiguous when importing nucleus segmentation polygons | The percentage of pixels found to be ambiguous when converting polygons into a mask. Ambiguities occur when polygons overlap one another. (Only calculated when polygon GeoJSON boundaries imported with --nucleus and --cell ) |
Percentage of pixels found to be ambiguous when importing cell segmentation polygons | The percentage of pixels found to be ambiguous when converting polygons into a mask. Ambiguities occur when polygons overlap one another. (Only calculated when polygon GeoJSON boundaries imported with --nucleus and --cell ) |
The percentage of imported nucleus polygons that were removed | The percentage of nuclei that were removed when importing polygons for nucleus segmentation. Nuclei are removed when they cannot be made consistent with the 2D nucleus mask. This can happen if there are nuclei completely contained within another or when a nucleus has a large portion of its area overlapping another nucleus. (Only calculated when polygon GeoJSON boundaries imported with --nucleus and --cell ) |
The percentage of imported cell polygons that were removed | The percentage of cells that were removed when importing polygons for cell segmentation. Cells are removed when they cannot be made consistent with the 2D cell mask. This can happen if there are cells completely contained within another or when a cell has a large portion of its area overlapping another cell. (Only calculated when polygon GeoJSON boundaries imported with --nucleus and --cell ) |
Percentage of nuclei without a cell | The percentage of nuclei that are not contained within a cell. This can happen when an imported community-developed cell or nucleus segmentation is not in agreement with the 10x-generated or the community-developed cell segmentation. |
Number of cell non-simple polygons | Number of non-simple polygon cells in GeoJSON (e.g., polygons with holes) that were modified to keep only the first array of vertices during import-segmentation . |
Number of cell multipolygons | Number of multipolygon cells in GeoJSON (e.g., multiple disconnected polygons) that were removed during import-segmentation . |
Number of nucleus non-simple polygons | Number of non-simple polygon nuclei in GeoJSON that were modified to keep only the first array of vertices during import-segmentation . |
Number of nucleus multipolygons | Number of multipolygon nuclei in GeoJSON that were removed during import-segmentation . |
Segmented cell imported fraction | Fraction of cells that were imported by import-segmentation . The remaining cells, if any, are generated by expansion of imported nuclei. |
Segmented cell imported count | Number of cells that were imported by import-segmentation . |