Xenium Ranger can be run in _cluster mode_ using Slurm to run the stages on _multiple_ nodes via batch scheduling. This allows highly parallelizable stages to utilize hundreds or thousands of cores concurrently, dramatically reducing time to solution.

<DocumentCallout> 
 <Text as={"span"}> 
 {"10x Genomics does not officially support Torque/PBS, SGE, or LSF. They are unsupported and may require trial and error to use. "}
 </Text> 
</DocumentCallout>

<Image src={"https://cdn.10xgenomics.com/image/upload/v1679522871/software-support/Spatial-GEX/Sustaining/cluster_mode.png"} /> 
Running pipelines in _cluster mode_ requires the following:
1. Xenium Ranger is installed in the same location on all nodes of the cluster. For example, `/opt/xeniumranger-xenium1.6` or `/net/apps/xeniumranger-xenium1.6`
2. Xenium Ranger pipelines are run on a shared file system accessible to all nodes of the cluster. NFS-mounted directories are the most common solution for this requirement.
3. The cluster accepts both single-core and multi-threaded (shared-memory) jobs.

Overview

Installing the Xenium Ranger software on a cluster is identical to installation on a local server. After confirming that the `xeniumranger` commands can run in _single server_ mode, configure the _job submission template_ that Xenium Ranger uses to submit jobs to the cluster. Assuming Xenium Ranger is installed to `/opt/xeniumranger-xenium1.6`, the process is as follows.

__Step 1.__ Navigate to the Martian runtime's `jobmanagers` directory which contains example jobmanager templates.

 ```
 cd /opt/xeniumranger-xenium1.6/external/martian/jobmanagers

 ls 
 
 # output: 
 # bsub.template.example config.json slurm.template.example
 ```


__Step 2.__ Make a copy of the cluster's example template to `.template` in the `jobmanagers/` directory.

 ```
 cp -v slurm.template.example slurm.template

 # output:
 # slurm.template.example -> slurm.template

 ls 
 
 # output:
 # bsub.template.example config.json slurm.template slurm.template.example
 ```

The job submission templates contain a number of special variables that are substituted by the Martian runtime when each stage is submitted. Specifically, the following variables are expanded when a pipeline is submitting jobs to the cluster.


 | **Variable** | **Must be present?** | **Description** |
 |--------------|----------------------|------------------|
 |`__MRO_JOB_NAME__` | Yes | Job names composed of the sample ID and stage being executed |
 |`__MRO_THREADS__` | No | Number of threads required by the stage |
 | `__MRO_MEM_GB__` `__MRO_MEM_MB__` | No | Amount of memory (in GB or MB) required by the stage |
 | `__MRO_MEM_GB_Per_THREAD__` `__MRO_MEM_MB_Per_THREAD__`| No | Amount of memory (in GB or MB) rquired per thread in multi-threaded stages |
 | `__MRO_STDOUT__` `__MRO_STDERR__` | Yes | Paths to the `_stdout` and `_stderr` metadata files for the stage |
 | `__MRO_CMD__` | Yes | Bourne shell command to run the stage code |


**It is critical that the special variables listed as required are present in the final template you create.** For more information on how the template should appear for a cluster, consult your cluster administrator or help desk.

Configuring cluster template

Considerations for the different job schedulers are listed below.

**SGE template:**

For SGE cluster, you MUST replace `<pe_name>` within the example template to reflect the name of the cluster's multi-threaded parallel environment. To view a list of the cluster's parallel environments, use the `qconf -spl` command.

The most common modifications to the job submission template include adding additional lines to specify:
1. The research group's queue. For example, `#$ -q smith.q`
2. The account to which jobs will charge. For example, `#$ -A smith_lab`

**LSF template:**

The most common modifications to the job submission template include adding additional lines to specify:
1. Your research group's queue. For example, `#BSUB -q smith_queue`
2. The account to which your jobs will charge. For example, `#BSUB -P smith_lab`

Additional template considerations

To run a Xenium Ranger pipeline in cluster mode, add the `--jobmode=slurm` command line option when using the `xeniumranger` commands. It is also possible to use `--jobmode=<PATH>`, where `<PATH>` is the full path to the cluster template file.

Validating template configuration

There are two subtle variants of running `Xenium Ranger` pipelines in cluster mode, each with their own pitfalls. Check with your cluster administrator to see which approach is compatible with your institution's setup.
1. **Run `Xenium Ranger` with `--jobmode=slurm` on the head node**. Cluster mode was originally designed for this use case. However, this approach leaves `mrp` and `mrjob` running on the head node for the duration of the pipeline, and some clusters impose time limits to prevent long running processes.
2. **Use a job script to submit a `Xenium Ranger` command with `--jobmode=slurm`**. With this approach, `mrp` and `mrjob` run on a cluster mode. However, the cluster must allow jobs to be submitted from a compute node to make this viable.

When `Xenium Ranger` is run in cluster mode, a single library analysis is partitioned into *hundreds* and potentially *thousands* of smaller jobs. The underlying Martian pipeline framework launches each stage job using the `sbatch` command when running on Slurm cluster. As stage jobs are queued, launched, and completed, the pipeline framework tracks their status using the metadata files that each stage maintains in the pipeline output directory.

Like _single server_ pipelines, cluster-mode pipelines can be restarted after failure. They maintain the same order of execution for dependent stages of the pipeline. All executed stage code is identical to _single server_ mode, and the quantitative results are identical to the limit of each stage's reproducibility. 

<DocumentCallout> <Text as={"span"}> {"Cluster-mode pipelines that are stopped (either by you or due to a stage failure) do "}{"not"}{" delete pending stages that have already been submitted to the cluster queue. As a result, some pipeline stages may continue to execute after the Xenium Ranger commands have exited. "} </Text> </DocumentCallout>

In addition, the Xenium Ranger UI can still be used with cluster mode. Because the Martian pipeline framework runs on the node from which the command was issued, the UI will also run from that node.

Cluster mode mechanics

Stages in the Xenium Ranger pipelines each request a specific number of cores and memory to aid with resource management. These values are used to prevent oversubscription of the computing system when running pipelines in single server mode.
The way CPU and memory requests are handled in cluster mode is defined by the following:

 * How the `__MRO_THREADS__` and `__MRO_MEM_GB__` variables are used within the job template.
 * How your specific cluster's job manager schedules resources.


For clusters whose job managers do not support memory requests, it is possible to request memory in the form of cores via the `--mempercore` command-line option. This option scales up the number of threads requested via the `__MRO_THREADS__` variable according to how much memory a stage requires.

For example, given a cluster with nodes that have 16 cores and 128 GB of memory (8 GB per core), the following pipeline invocation command:

 ```
 xeniumranger relabel --id=demo \
 --xenium-bundle=xenium-bundle \
 --jobmode=slurm \
 --mempercore=8
 ```

will issue the following resource requests:
* A stage that requires 1 thread and less than 8 GB of memory will pass `__MRO_THREADS__` of `1` to the job template.
* A stage that requires 1 thread and 12 GB of memory will pass `__MRO_THREADS__` of `2` to the job template because (12 GB) / (8 GB/core) = 2 cores.
* A stage that requires 2 threads and less than 16 GB of memory will pass `__MRO_THREADS__` of `2` to the job template.
* A stage that requires 2 threads and 40 GB of memory will pass `__MRO_THREADS__` of `5` to the job template because (40 GB) / (8 GB/core) = 5 cores.

As the final bullet point illustrates, this mode can result in wasted CPU cycles and is only provided for clusters that cannot allocate memory as an independent resource.

Every cluster configuration is different. If you are unsure of how your cluster resource management is configured, contact your cluster administrator or help desk.

**SGE memory:**

SGE supports requesting memory via the `mem_free` resource natively, although your cluster may have another mechanism for requesting memory. To pass each stage's memory request through to SGE, add an additional line to your `sge.template` that requests `mem_free`, `h_vmem`, `h_rss`, or the custom memory resource defined by your cluster.

 ``` bash highlightedLines={[4]}
 cat sge.template

 ## Expected output
 #$ -N __MRO_JOB_NAME__
 #$ -V
 #$ -pe threads __MRO_THREADS__
 #$ -l mem_free=__MRO_MEM_GB__G 
 #$ -cwd
 #$ -o __MRO_STDOUT__
 #$ -e __MRO_STDERR__ 

 __MRO_CMD__
 ```


<DocumentCallout> <Text as={"span"}> {" In the above example, the trailing G in the highlighted __MRO_MEM_GB__G is required by SGE to denote that mem_free is being expressed in GB units. "} </Text> </DocumentCallout>

Note that the `h_vmem` (virtual memory) and `mem_free/h_rss`(physical memory) represent two different quantities, and that Xenium Ranger stages `__MRO_MEM_GB__` requests are expressed as physical memory. Using `h_vmem` in your job template may cause certain stages to be unduly killed if their virtual memory consumption is substantially larger than their physical memory consumption. It follows that we do not recommend using `h_vmem`.

If you do use `h_vmem` in a template, it is recommended that you use the `__MRO_MEM_GB_PER_THREAD__` or `__MRO_MEM_MB_PER_THREAD__` variables instead of `__MRO_MEM_GB__` and `__MRO_MEM_MB__`. To determine memory limits for a multicore job, SGE will multiply the number of threads by the value in `h_vmem`. The `__MRO_MEM_GB__` and `__MRO_MEM_MB__` variables already reflect the sum amount of memory across all threads needed to run the job. Using those variables as `h_vmem` will inflate the memory required for multi-threaded jobs.

**LSF memory:**

LSF supports job memory requests through the `-M` and `-R [mem=...]` options, but these requests generally must be expressed in MB, not GB. As such, your LSF job template should use the `__MRO_MEM_MB__` variable rather than `__MRO_MEM_GB__`. For example,


 ``` bash highlightedLines={[4]} 
 cat bsub.template

 ## Expected output
 #BSUB -J __MRO_JOB_NAME__
 #BSUB -n __MRO_THREADS__
 #BSUB -o __MRO_STDOUT__
 #BSUB -e __MRO_STDERR__
 #BSUB -R "rusage[mem=__MRO_MEM_MB__]"
 #BSUB -R span[hosts=1] 

 __MRO_CMD__
 ```

Memory requests and consumption

Some Xenium Ranger pipeline stages are divided into hundreds of jobs. By default, the rate at which these jobs are submitted to the cluster is throttled to at most 64 at a time and at least 100 ms between each submission to avoid running into limits on clusters which impose quotas on the total number of pending jobs a user can submit.

If your cluster does not have these limits or is not shared with other users, you can control how the Martian pipeline runner sends job submissions to the cluster by using the `--maxjobs` and `--jobinterval` parameters.
To increase the cap on the number of concurrent jobs to 200, use the `--maxjobs` parameter:

 ```
 xeniumranger resegment --id=sample ... --jobmode=slurm --maxjobs=200
 ```

You can also change the rate limit on how often the Martian pipeline runner sends submissions to the cluster.  To add a five-second pause between job submissions, use the `--jobinterval` parameter:

 ```
 xeniumranger resegment --id=sample ... --jobmode=slurm --jobinterval=5000
 ```

The job interval parameter is in milliseconds. The minimum allowable value is 1.

Controlling rate of job submissions

Use Slurm to run stages on multiple nodes via batch scheduling

Cluster Mode

Usage: 

 ```
 xeniumranger relabel --help
 
 # Argument option names and values can be separated by a space or =
 xeniumranger relabel [OPTIONS] --id=<ID> --xenium-bundle=<XENIUM_BUNDLE> \
 --panel=<PANEL>
 ```


 Argument | Description
 --- | ---
 `--xenium-bundle` | *Required.* File path to directory containing all required Xenium Onboard Analysis output files.
 `--id` | *Required.* Unique string to specify the name of the `relabel` output folder. May only include ASCII characters (alphanumeric, underscore, dash, period) and must not use whitespace, slash, quote, or comma characters. 
 `--panel` | *Required.* New gene panel JSON file to use for relabeling transcripts with the correct gene.

relabel

Usage: 

 ```
 xeniumranger resegment --help

 # Argument option names and values can be separated by a space or =
 xeniumranger resegment [OPTIONS] --id=<ID> --xenium-bundle=<XENIUM_BUNDLE>
 ```

 Argument | Description
 --- | ---
 `--xenium-bundle` | *Required.* File path to directory containing all required Xenium Onboard Analysis output files.
 `--id` | *Required.* Unique string to specify the name of the `resegment` output folder. May only include ASCII characters (alphanumeric, underscore, dash, period) and must not use whitespace, slash, quote, or comma characters.
 `--expansion-distance` | Nuclei boundary expansion distance in &micro;m. Default: 15 (accepted range: 0 - 100).
 `--dapi-filter` | Minimum intensity in photoelectrons (pe) to filter nuclei. Error if `--resegment-nuclei=false`. Default: 100 (appropriate range of values is 0 to 99th percentile of image stack or 1000, whichever is larger).
 `--resegment-nuclei` | Boolean to specify whether to rerun the latest Xenium Onboard Analysis nucleus segmentation algorithm (true) or to use existing nucleus segmentation masks in the `cells.zarr` file (false). Default: true.

resegment

Usage: 

 ```
 xeniumranger import-segmentation --help
 
 # Argument option names and values can be separated by a space or =
 xeniumranger import-segmentation [OPTIONS] --id=<ID> --xenium-bundle=<XENIUM_BUNDLE>
 ```

import-segmentation

These `import-segmentation` arguments are specific to image-based segmentation inputs (i.e., polygons, masks).

 Argument | Description
 --- | ---
 `--xenium-bundle` | *Required.* File path to directory containing all required Xenium Onboard Analysis output files.
 `--id` | *Required.* Unique string to specify the name of the `import-segmentation` output folder. May only include ASCII characters (alphanumeric, underscore, dash, period) and must not use whitespace, slash, quote, or comma characters.
 `--expansion-distance` | Nuclei boundary expansion distance in µm. Only for use when nucleus segmentation provided as input; error if cell segmentation is also included as an input. Default: 15 (accepted range: 0 - 100). 
 `--nuclei` | Label mask (TIFF or NPY) or polygons of nucleus segmentations (GeoJSON `FeatureCollection`). `--nuclei` will use `nucleusGeometry` polygon if it exists in the GeoJSON, or `geometry` if it does not (i.e., for QuPath-like GeoJSON files). Error if `--transcript-assignment` argument is used.
 `--cells` | Label mask (TIFF or NPY) or polygons of nucleus segmentations (GeoJSON `FeatureCollection`). Features with a non-cell `objectType` will be ignored. Error if `--transcript-assignment` argument is used. Error if run without `--nuclei`.
 `--coordinate-transform` | Image alignment file containing similarity transform matrix (e.g., the `_imagealignment.csv` file exported from Xenium Explorer; read about the algorithm [here](/support/software/xenium-explorer/tutorials/xe-image-alignment#alignment-algo)). Works with segmentation results in polygon (GeoJSON) or mask (TIFF) format.
 `--units` | Indicates whether segmentation results are in physical space ("microns") or pixel space ("pixel"). Default: "pixel". Must be set as "microns" if `--coordinate-transform` is used.
 `--max-cell-area-um2` | Maximum allowed cell area in square microns. Cells with a larger area are removed. Default: 2000 &micro;m2.
 `--min-cell-area-um2` | Minimum allowed cell area in square microns. Cells with a smaller area are removed. Default: 0 &micro;m2.
 `--max-nucleus-area-um2` | Maximum allowed nucleus area in square microns. Nuclei with a larger area are removed. Default: 2000 &micro;m2.
 `--min-nucleus-area-um2` | Minimum allowed nucleus area in square microns. Nuclei with a smaller area are removed. Default: 0 &micro;m2.

Image-based segmentation

These `import-segmentation` arguments are specific to transcript-based segmentation inputs. For example, Xenium Ranger supports a transcript CSV with cell assignments as input formatted like the `segmentation.csv` output from Baysor v0.6.

 Argument | Description
 --- | ---
 `--xenium-bundle` | *Required.* File path to directory containing all required Xenium Onboard Analysis output files.
 `--id` | *Required.* Unique string to specify the name of the `import-segmentation` output folder. May only include ASCII characters (alphanumeric, underscore, dash, period) and must not use whitespace, slash, quote, or comma characters.
 `--viz-polygons` | Cell boundary polygons (GeoJSON) for visualization from Baysor. Required if `--transcript-assignment` argument used. Error if `--cells` or `--nuclei` arguments used.
 `--transcript-assignment` | Transcript CSV with cell assignment from Baysor. Error if `--cells` or `--nuclei` arguments are used.
 `--units` | Indicates whether segmentation results are in physical space ("microns") or pixel space ("pixel"). Default: "pixel". Must be set as "microns" for Baysor inputs.
 `--max-cell-area-um2` | Maximum allowed cell area in square microns. Cells with a larger area are removed. Default: 2000 &micro;m2.
 `--min-cell-area-um2` | Minimum allowed cell area in square microns. Cells with a smaller area are removed. Default: 0 &micro;m2.

Transcript-based segmentation

The Martian runtime options are available for Xenium Ranger `relabel`, `resegment`, and `import-segmentation` subcommands.

The Martian commands work the same as for other 10x Genomics pipelines (i.e., Cell Ranger, Space Ranger). For more information about certain parameters, please see these pages for [job submission mode](/support/software/xenium-ranger/advanced/XR-job-submission-mode), [cluster mode](/support/software/xenium-ranger/advanced/XR-cluster-mode), and [pipeline monitoring UI](/support/software/xenium-ranger/advanced/XR-pipeline-monitoring-ui) guidance.

Usage example with `relabel`: 

 ```
 xeniumranger relabel --id=example --xenium-bundle=/path/to/outputs \
 --panel=/path/to/panel --jobmode=local \
 --localcores=8 --localmem=32
 ```


 Argument | Description
 --- | ---
 `--jobmode` | Job manager to use. Valid options: local (default), a cluster job mode (i.e., sge, lsf, slurm), or the path to a `<jobmode>.template` file.
 `--localcores` | Set max cores the pipeline may request at one time. Only applies to local jobs. 
 `--localmem` | Set max GB the pipeline may request at one time. Only applies to local jobs. 
 `--localvmem` | Set max virtual address space in GB for the pipeline. Only applies to local jobs. 
 `--mempercore` | Reserve enough threads for each job to ensure enough memory will be available, assuming each core on your cluster has at least this much memory available. Only applies to cluster jobmodes. 
 `--maxjobs` | Set max jobs submitted to the cluster at one time. Only applies in cluster jobmodes. 
 `--jobinterval` | Set delay between submitting jobs to cluster, in ms. Only applies in cluster jobmodes. 
 `--overrides` | The path to a JSON file that specifies stage-level overrides for cores and memory. Finer-grained than `--localcores`, `--mempercore` and `--localmem`. Contact support for an example override file. 
 `--uiport` | The port to serve web UI at: http://localhost:PORT 
 `--disable-ui` | Boolean to determine whether to serve the web UI (true, false). 
 `--noexit` | Boolean to keep web UI running after pipestance completes or fails (true, false). 
 `--nopreflight` | Specify the preflight check(s) to skip.



 Flag | Description 
 --- | ---
 `--dry` | Do not execute the pipeline. Generate a pipeline invocation (`.mro`) file and stop.

Runtime options

Check your system’s compatibility with Xenium Ranger [system requirements](/support/software/xenium-ranger/downloads/XR-system-requirements).

Usage: `xeniumranger sitecheck > sitecheck.txt`


 Option | Description
 --- | ---
 `-h`, `--help` | Show help message.
 `--version` | Show version.

sitecheck

To use `tarmri` to generate a `.mri.tgz` file for a failed run, call `tarmri` and give it the path to the failed pipestance (run name specified by `--id`).

The `.mri.tgz` file contains a number of logs (including error messages, status reports, and information about the system) that are useful for troubleshooting failures. The `.mri.tgz` file does not contain sample data or analysis outputs. 

Usage:

 ```
 # Generate mri.tgz file for example analysis --id run1
 xeniumranger-xenium1.6/external/cellranger/bin/tenkit/tarmri <path to>/run1

 # Share mri.tgz file with 10x Support
 xeniumranger upload <your email> <path to log.mri.tgz>
 ```

tarmri

Upload a file to the 10x Genomics support team.

Usage: `xeniumranger upload <your email> <file>`

upload

Xenium Ranger Commands

Xenium Ranger Command Line Arguments

Select a job scheduler below to see a sample job script.

<DocumentCallout> <Text as={"span"}> {"10x Genomics does not officially support Torque/PBS, SGE, or LSF. Sample job scripts are shown below."} </Text> </DocumentCallout>

Step 1. Select job scheduler

```bash highlight={true}
#!/usr/bin/env bash

# ==================================
# Job Script
# ==================================

#SBATCH -J {JOB_NAME}
#SBATCH --export=ALL
#SBATCH --nodes=1 --ntasks-per-node={NUM_THREADS}
#SBATCH --signal=2
#SBATCH --no-requeue
### Alternatively: --ntasks=1 --cpus-per-task={NUM_THREADS}
#  ==================================
# Consult with your cluster administrators to find the combination that
# works best for single-node, multi-threaded applications on your system.
# ==================================
#SBATCH --mem={MEM_GB}G
#SBATCH -o {STDOUT_LOG}
#SBATCH -e {STDERR_LOG}

{PIPELINE_CMD}
```

Slurm scheduler

```bash highlight={true}
#!/usr/bin/env bash

#!!! This is not officially supported by 10x


# ==================================
# Setup Instructions
# ==================================
# # 1. Substitute {PE_NAME} below with name of your cluster's
# shared-memory parallel environment. If your cluster does not
# have a parallel environment,
# delete this line. However, the job will run with only 1 thread.

# ==================================
# Job Script
# ==================================

#$ -N {JOB_NAME}
#$ -V
#$ -pe {PE_NAME} {NUM_THREADS}
#$ -cwd
#$ -l mem_free={MEM_GB}G
#$ -o {STDOUT_LOG}
#$ -e {STDERR_LOG}
#$ -S "/usr/bin/env bash"

{PIPELINE_CMD} 
```

SGE scheduler

```bash highlight={true}
#!/usr/bin/env bash

#!!! This is not officially supported by 10x

      
# ==================================
# Job Script
# ==================================

#BSUB -J {JOB_NAME}
#BSUB -n {NUM_THREADS}
#BSUB -o {STDOUT_LOG}
#BSUB -e {STDERR_LOG}
#BSUB -R "rusage[mem={MEM_MB}]"
#BSUB -R span[hosts=1]

{PIPELINE_CMD} 
```

LSF scheduler

```bash highlight={true}
#!/usr/bin/env bash

#!!! This is not officially supported by 10x

# ==================================
# Job Script
# ==================================

#PBS -N {JOB_NAME}
#PBS -V
#PBS -l nodes=1:ppn={NUM_THREADS}
#PBS -l mem={MEM_GB}gb
#PBS -o {STDOUT_LOG}
#PBS -e {STDERR_LOG}

{PIPELINE_CMD}
```

Torque/PBS scheduler

Copy the sample job script to a text editor, and replace all the variables enclosed within braces (for example, `{JOB_NAME}`or `{STDOUT_LOG}`) with literal names, paths, and values. 

The last line, `{PIPELINE_CMD}` , is replaced by a Xenium Ranger command, specifying `--jobmode=local`, `--localcores={NUM_THREADS}` and `--localmem=0.9*{MEM_GB}` to restrict CPU and memory use that is consistent with the directives in the job script. 

For example, if the job script requests 8 cores and 64 GB of memory from the cluster, then the Xenium Ranger command should include `--jobmode=local --localcores=8 --localmem=57`.

<DocumentCallout> 
 <Text as={"span"}> 
 {"Since cluster setup and policy vary greatly from one institution to another, the sample job scripts provided below should be treated as a starting point. Consult with your local cluster administrator to see if additional directives are required. "} 
 </Text> 
</DocumentCallout>

Step 2. Update sample job script

If the sample job script is saved as `runJob.bash`, then following commands submits the job to the cluster for each of the  corresponding job scheduler.

Step 3. Run sample job script

```bash highlight={true}
sbatch runJob.bash
```

Run Slurm

```bash highlight={true}
qsub runJob.bash
```           


Run SGE

```bash highlight={true}
bsub runJob.bash
```

Run LSF

```bash highlight={true}
qsub runJob.bash
```

Run Torque/PBS

Treat a single node from the cluster like a local server

Job Submission Mode

When the pipeline runs, it will display the URL for the UI.

```
xeniumranger relabel --id=sample345 \
 --xenium-bundle=xenium-bundle \
 --panel=panel.json \


 
Martian Runtime - 4.0.10
Serving UI at http://host.example.com:5603/?auth=mcV3MKANWfNTERRGASgYV8aXskx-rSH7hxynAdsTieA
 
Running preflight checks (please wait)...
```

The UI becomes unavailable once the pipeline completes, unless the `--noexit=true` flag is used.

While a pipeline is running, you can open the url (i.e., `http://host.example.com:5603/?auth=mcV3MKANWfNTERRGASgYV8aXskx-rSH7hxynAdsTieA` in the example above) in your web browser to view the pipeline process graph. <Image src={'https://cdn.10xgenomics.com/image/upload/v1691530192/software-support/Xenium-Ranger/xr1.6_relabel_graph.png'}/>

Clicking on any of the graph's nodes will reveal more information about that stage in the right pane. This info pane is broken into several sections, and the topmost shows high-level details about the stage's execution.

This includes the state of the stage (running, failed, or complete), the fully-qualified stage name (`FQName`), the directory in which the stage is running (`Path`), the stagecode that is being run (the location of the Python package being run), and any information about parameter sweeping that may apply to this stage.

Clicking the arrow next to the stage name (i.e., `← XR_SETUP_INPUTS`) will return to the pipeline-level metadata view. <Image src={'https://cdn.10xgenomics.com/image/upload/v1691530192/software-support/Xenium-Ranger/xr1.6_stages.png'}/>

The **Sweeping** section allows you to view the MRO call used to invoke this stage (`invocation`) and information about the split and join components of the stage if it was parallelized. <Image src={'https://cdn.10xgenomics.com/image/upload/v1691530192/software-support/Xenium-Ranger/xr1.6_sweep.png'}/>


<SupportCallout level={"info"}> 
 <Anchor href={"https://martian-lang.org/"}> 
 {"Martian "} 
 </Anchor> 
 <Text as={"span"}> 
 {"is the pipeline framework used by Xenium Ranger. It supports parameter sweeping for pipelines. The Forks and Permute fields in the Sweeping section display information about different parameters being swept, but no Xenium Ranger pipeline currently performs parameter sweeping. These fields will always contain only trivial information as a result."} 
 </Text> 
</SupportCallout> 

The **Argument Bindings** and **Return Bindings** sections display the inputs and outputs of the stage. <Image src={'https://cdn.10xgenomics.com/image/upload/v1691530192/software-support/Xenium-Ranger/xr1.6_bindings.png'}/>

In general, only top-level pipeline stages (those represented by rectangular nodes in the process graph) contain return bindings.

The **Chunking** section displays information about the parallel execution of the stage. Many stages are automatically parallelized and process different pieces (chunks) of the same input dataset in parallel. For example, an input dataset could be split into multiple chunks for a given stage. This section would show when chunks had completed, are in flight, and are waiting for CPU and/or memory to become available before running. <Image src={'https://cdn.10xgenomics.com/image/upload/v1691530192/software-support/Xenium-Ranger/xr1.6_chunks.png'}/>

Clicking on an individual chunk exposes additional options for viewing metadata about that chunk's execution, including any errors, standard output, and in cluster mode the job script used to queue the job to the cluster. The `jobinfo` includes information about how a chunk was executed, selected environment variables, and for completed chunks various perfomance statistics such as peak memory usage and CPU time used. As with the **Sweeping** section, additional metadata associated with the chunk execution can also be viewed.

Understanding the UI

You can also examine pipestances that have already completed using the Xenium Ranger UI. Assuming your pipestance output directory was `/home/jdoe/runs/sample345`, simply rerun the `xeniumranger` command with the `--noexit` option to re-attach the UI:

```
xeniumranger relabel --id=sample345 \
                     --xenium-bundle=xenium-bundle \
                     --panel=panel.json \
                     --noexit=true


 
Martian Runtime - 4.0.10
Serving UI at http://host.example.com:3600
 
Running preflight checks (please wait)...
 
Pipestance completed successfully, staying alive because --noexit given.
```

Launching the UI for existing pipelines

If you run pipelines on a server that blocks access to all ports except SSH, you can still access the Xenium Ranger UI using SSH forwarding. Assuming you have a `xeniumranger` pipeline running on port `3600` on `cluster.university.edu`, you can type the following from your laptop:

```
ssh -NT -L 9000:cluster.university.edu:3600 jdoe@cluster.university.edu
jdoe@cluster.university.edu's password:
```

Upon entering a password (assuming you are `jdoe@cluster.university.edu`), the command appears to hang. However, in the background it has mapped port 9000 on your laptop to port 3600 on `cluster.university.edu` through the ssh connection for which you just entered your password.

This allows you to go to http://localhost:9000/ in your web browser and access the UI running on `cluster.university.edu:3600`. Once you are done examining the UI, use `Ctrl+C` in your `ssh -NT -L ...` terminal window to terminate this SSH forwarder.

A full explanation of SSH forwarding is beyond the scope of this guide, see [SSH/OpenSSH/PortForwarding](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding).

Accessing the UI through a Firewall

User interface (UI) for monitoring progress through a web browser

Pipeline Monitoring UI

Getting Started

Download Center

Analysis

Algorithms

Advanced

Release Notes

Xenium Onboard Analysis

Xenium Explorer

Datasets

Analysis Guides

Xenium Ranger

Learn more about input files required for Xenium Ranger

Inputs

Learn how to run Xenium Ranger subcommands.

Running Pipelines

Guidance for choosing a Xenium Ranger pipeline.

Choosing a Pipeline

Relabel

Modify the Xenium Onboard Analysis cell segmentation results.

Resegment

Import segmentation results from community-developed tools.

Import-segmentation

Learn more about output files generated by Xenium Ranger

Outputs

The Xenium In Situ software suite is a set of software applications for analyzing and visualizing in situ gene expression data produced by the Xenium Analyzer. Xenium Ranger provides flexible off-instrument reanalysis of Xenium In Situ data. Relabel transcripts, resegment cells with the latest 10x segmentation algorithms, or import your own segmentation data to assign transcripts to cells.

What is Xenium Ranger?

Learn about Xenium Ranger, software compatibility, and analysis workflows.

Getting Started with Xenium Ranger

New to Xenium Ranger?

We provide resources from protocols, user guides, and free-to-use analysis tools.

View the latest updates to Xenium Ranger algorithms.

View the latest updates to Xenium Ranger.

Learn more about Xenium In Situ instrument analysis software.

Visualize data from Xenium In Situ solutions.

Browse Q&As from the 10x Genomics support team.

Access free, publicly available data generated with Xenium In Situ solutions.

A collection of introductions, tutorials, and blogs for data analysis beyond 10x Genomics software.