The relabel
pipeline allows you to change the gene labels applied to decoded transcripts.
For example, if the wrong gene_panel.json
file was selected on the Xenium Analyzer (example analysis_summary.html
alert shown below), you can use this pipeline to correct the gene labels after the instrument run completes. The instrument run itself does not need to be restarted.
![](https://cdn.10xgenomics.com/image/upload/v1690862139/software-support/Xenium-Ranger/wrong_panel_alert.png)
The pipeline will use the provided panel file to update gene labels for each decoded spot in the dataset and regenerate the Xenium output bundle files.
The input files for relabel
are:
- The Xenium output bundle generated by the Xenium Onboard Analysis pipeline (see Input overview).
- The gene panel JSON file to use for relabeling decoded transcripts.
The JSON files for Xenium pre-designed panels are available in the Xenium Ranger tarball (xeniumranger-x.y.z/lib/json/definitions/panel_designer/panels/
- replace x.y.z
with the version you are using). If you are inputting a custom panel (add-on or standalone custom), the JSON panel should be sent via email (see the Xenium Panel Designer finalize design support page).
The xeniumranger relabel
command line arguments are described on the Xenium Ranger command line arguments page.
Make sure to edit the paths to input/output files in the example below.
# Example relabeling a dataset with the pre-designed human brain panel
# For this example, the xeniumranger tarball is installed in a directory called /opt.
xeniumranger relabel --id=relabel-demo \
--xenium-bundle=/path/to/xenium/files \
--panel=/opt/xeniumranger-xenium1.6/lib/json/definitions/panel_designer/panels/xenium_human_brain_gene_expression_panel.json
Here are two examples for running commands sequentially with relabel
. These scenarios assume that you want to change the initial gene labeling:
-
Scenario 1: First, run
relabel
to correct gene names.xeniumranger relabel --id=relabel-demo \ --xenium-bundle=original-xenium-outputs \ --panel=/opt/xeniumranger-xenium1.6/lib/json/definitions/panel_designer/panels/ xenium_human_brain_gene_expression_panel.json
Second, run resegment on the output bundle generated by
relabel
to adjust segmentation parameters from the Xenium Onboard Analysis pipeline algorithm.xeniumranger resegment --id=resegment-demo --xenium-bundle=relabel-demo/outs \ --expansion-distance=5
-
Scenario 2: First, run
relabel
to correct gene names.xeniumranger relabel --id=relabel-demo2 \ --xenium-bundle=original-xenium-outputs \ --panel=/opt/xeniumranger-xenium1.6/lib/json/definitions/panel_designer/panels/ xenium_human_brain_gene_expression_panel.json
Second, run import-segmentation on the output bundle generated by
relabel
to generate a new output bundle based on segmentation results from a community-developed tool.xeniumranger import-segmentation --id=import-demo \ --xenium-bundle=relabel-demo2/outs \ --transcript-assignment=segmentation.csv \ --viz-polygons=segmentation_polygons.json \ --units=microns
After the pipeline completes, check the output outs/
directory (see Output overview). For example, look at these files:
- Cell-feature matrix: should have relabeled gene names
- Analysis summary: check alerts (i.e., incorrect panel alert should no longer be displayed), check metrics and plots on the Decoding and Analysis tabs