The CSV file has three columns:

• Imported cell ID: Lists the cell IDs from the imported file (e.g., transcript assignment CSV, GeoJSON, TIFF, cells.zarr.zip, etc.)
• Xenium Ranger new cell ID: Lists the cell IDs generated by the Xenium Ranger run and used in the cell-feature matrix. Note these are not the original XOA cell IDs, as Xenium Ranger reassigns cell IDs if any cell segmentation results change.
• Xenium Ranger new cell label: Lists the cell labels generated by the Xenium Ranger run. These labels match the pixel values from the segmentation mask (cell_index).

Example with imported cell IDs from a GeoJSON produced by QuPath:

Copy
Imported cell ID,Xenium Ranger new cell ID,Xenium Ranger new cell label
34b02596-eaf4-4a44-b2fe-91b5ddaec48d,aaaadepm-1,1
9e804b84-5674-4a3c-86d1-76b6ff6c82da,aaaeegeg-1,2
5b2358bc-d8d8-448a-b1e8-0af06adc4bc9,aaaejmkb-1,3
[...]

Example with imported cell IDs from a TIFF mask image produced by Cellpose:

Copy
Imported cell ID,Xenium Ranger new cell ID,Xenium Ranger new cell label
1,aaabdkik-1,1
2,aaabfocj-1,2
3,aaabognf-1,3
[...]

The imported cell ID column will contain the nucleus label mask values (instead of a cell ID) if only nuclei are imported (do not specify --cells and specify nuclei IDs with --nuclei). For a XOA output, these nucleus label mask values are stored in the cells.zarr.zip file as cell_index and the cell_summary.csv file as label_id.

Copy
Imported cell ID,Xenium Ranger new cell ID,Xenium Ranger new cell label
108,aaaadepm-1,1
[...]

In the following sections, we provide some examples for how you might use the cell ID CSV file in your analysis workflow.

In this scenario, you have used a community-developed tool such as QuPath or Visiopharm Phenoplex to perform cell segmentation and annotate cells from Xenium image data (e.g., protein images). Now, you would like to combine the cell phenotype annotations with the Xenium cell-feature matrix using cell IDs, but Xenium Ranger import-segmentation creates new cell IDs. Here is an example of the high-level steps for an analysis workflow using QuPath, Xenium Ranger, and either Seurat or Scanpy:

1. In QuPath, generate cell segmentation using plugins (e.g., Cellpose).
2. Classify cells to annotate them as positive or negative for a given protein signal (e.g., CD4+).
3. Export the cell segmentation and annotation measurements as a GeoJSON format file.
4. Use Xenium Ranger import-segmentation to import the GeoJSON file. Xenium Ranger will generate a new XOA output bundle with the QuPath cell segmentation results, as well as a CSV file that links QuPath’s cell IDs to Xenium Ranger's cell IDs.
5. Input the cell-feature matrix into tools like Seurat or Scanpy for downstream analysis (e.g., differential gene expression). Note that Xenium Ranger does not read the annotation "properties" field from QuPath. To join the annotation information with the Xenium data, use the cell ID CSV to map between Xenium Ranger and imported QuPath cell IDs.
6. Annotate cells (observations) using classifications and/or measurements from the QuPath GeoJSON file.

In this scenario, you have used community-developed tools to resegment and reassign transcripts to cells (e.g., using transcript-based cell segmentation methods), followed by single cell types of analysis. Now, you would like to import the cell segmentations to visualize in Xenium Explorer. Here is an example of the high-level steps for an analysis workflow using Baysor, either Seurat or Scanpy, and Xenium Ranger:

1. Run Baysor to generate new cell segmentation results.
2. Create a single cell count matrix to conform with the redefined cell boundaries (e.g., as shown in this Analysis Guide).
3. Input the cell-feature matrix to tools like Seurat or Scanpy for downstream analysis (e.g., differential gene expression).
4. Use Xenium Ranger import-segmentation to import the GeoJSON and segmentation CSV files. Xenium Ranger will generate a new XOA output bundle with the Baysor cell segmentation results, as well as the cell ID CSV file. You can use the cell ID CSV to map cells between the Xenium Ranger outputs and the single cell analysis.

Alternatively, if you import the Baysor results to Xenium Ranger first and then perform single cell analyses, you will not need to map cell IDs between methods as all downstream analysis will use the new Xenium Ranger cell IDs.

In some cases, the cell_id_map.csv.gz file will have blank entries, which represent cells that Xenium Ranger either removed or created during the import process.

• Row 1 below: If imported cells overlap with each other, Xenium Ranger may delete one of the cells. In this case, the Xenium Ranger new cell ID and new cell label columns will have blank entries.
• Row 2 below: There may be cases where the imported cell ID is blank because an imported nucleus did not overlap with any cell. In this case, Xenium Ranger uses nuclear expansion to create a new cell.

Copy
Imported cell ID,Xenium Ranger new cell ID,Xenium Ranger new cell label
CR63559489d-75370,,
,oiidmaip-1,146757

In this scenario, you did a sweep of expansion distances starting from the same nucleus segmentation and want to compare cells. With the cell ID CSV file, you can link all cells to the original nucleus label ID. Here is an example of the high-level steps for an analysis workflow Xenium Ranger:

1. Run Xenium Ranger as shown in this example.
2. Use the Imported cell ID column to map Xenium Ranger cells from various expansion distances to the same input nucleus.