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.

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

Relabel Decoded Transcripts

Input

Run relabel

Output