Relabel Decoded Transcripts

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.

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. Xenium Ranger v2.0 will generate files in Xenium Onboard Analysis v2.0 output file formats.

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.

For Xenium pre-designed panels, the JSON files 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 Getting Started with Xenium Panel Design 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 examples below for your own datasets. The examples provide the recommended settings for --localcores and --localmem parameter values (see Resource limits for more details).


# 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-xenium2.0/lib/json/definitions/panel_designer/panels/xenium_human_brain_gene_expression_panel.json \
                     --localcores=32 \
                     --localmem=128

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-xenium2.0/lib/json/definitions/panel_designer/panels/ xenium_human_brain_gene_expression_panel.json \
                     --localcores=32 \
                     --localmem=128

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 \
                       --localcores=32 \
                       --localmem=128

Scenario 2: First, run relabel to correct gene names.


xeniumranger relabel --id=relabel-demo2 \
                     --xenium-bundle=original-xenium-outputs \
                     --panel=/opt/xeniumranger-xenium2.0/lib/json/definitions/panel_designer/panels/ xenium_human_brain_gene_expression_panel.json \
                     --localcores=32 \
                     --localmem=128

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 \
                                 --localcores=32 \
                                 --localmem=128

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

Input

Run relabel

Output