10x Genomics Support/Xenium Ranger/

Xenium Ranger Command Line Arguments

For a list of subcommands, run xeniumranger --help.

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

Argument option names and values should be separated by either a space or equal sign (i.e., --id=demo or --id demo). Arguments that specify files or paths may use either absolute or relative paths.

If a pipeline analysis is interrupted or throws an error, enter the command with a new --id, or delete the pipestance directory (named after --id) and the invocation .mro file to use the identical command. Interrupted analyses cannot be restarted at this time.

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>
ArgumentDescription
--xenium-bundleRequired. File path to directory containing all required Xenium Onboard Analysis output files.
--idRequired. 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.
--panelRequired. New gene panel JSON file to use for relabeling transcripts with the correct gene.

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>
ArgumentDescription
--xenium-bundleRequired. File path to directory containing all required Xenium Onboard Analysis output files.
--idRequired. 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-distanceNuclei boundary expansion distance in µm. Default: 15 (accepted range: 0 - 100).
--dapi-filterMinimum 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-nucleiBoolean 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.

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>

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

ArgumentDescription
--xenium-bundleRequired. File path to directory containing all required Xenium Onboard Analysis output files.
--idRequired. 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-distanceNuclei 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).
--nucleiLabel 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.
--cellsLabel 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-transformImage alignment file containing similarity transform matrix (e.g., the _imagealignment.csv file exported from Xenium Explorer; read about the algorithm here). Works with segmentation results in polygon (GeoJSON) or mask (TIFF) format.
--unitsIndicates 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-um2Maximum allowed cell area in square microns. Cells with a larger area are removed. Default: 2000 µm2.
--min-cell-area-um2Minimum allowed cell area in square microns. Cells with a smaller area are removed. Default: 0 µm2.
--max-nucleus-area-um2Maximum allowed nucleus area in square microns. Nuclei with a larger area are removed. Default: 2000 µm2.
--min-nucleus-area-um2Minimum allowed nucleus area in square microns. Nuclei with a smaller area are removed. Default: 0 µm2.

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.

ArgumentDescription
--xenium-bundleRequired. File path to directory containing all required Xenium Onboard Analysis output files.
--idRequired. 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-polygonsCell boundary polygons (GeoJSON) for visualization from Baysor. Required if --transcript-assignment argument used. Error if --cells or --nuclei arguments used.
--transcript-assignmentTranscript CSV with cell assignment from Baysor. Error if --cells or --nuclei arguments are used.
--unitsIndicates 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-um2Maximum allowed cell area in square microns. Cells with a larger area are removed. Default: 2000 µm2.
--min-cell-area-um2Minimum allowed cell area in square microns. Cells with a smaller area are removed. Default: 0 µm2.

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, cluster mode, and 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
ArgumentDescription
--jobmodeJob manager to use. Valid options: local (default), a cluster job mode (i.e., sge, lsf, slurm), or the path to a <jobmode>.template file.
--localcoresSet max cores the pipeline may request at one time. Only applies to local jobs.
--localmemSet max GB the pipeline may request at one time. Only applies to local jobs.
--localvmemSet max virtual address space in GB for the pipeline. Only applies to local jobs.
--mempercoreReserve 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.
--maxjobsSet max jobs submitted to the cluster at one time. Only applies in cluster jobmodes.
--jobintervalSet delay between submitting jobs to cluster, in ms. Only applies in cluster jobmodes.
--overridesThe 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.
--uiportThe port to serve web UI at: http://localhost:PORT
--disable-uiBoolean to determine whether to serve the web UI (true, false).
--noexitBoolean to keep web UI running after pipestance completes or fails (true, false).
--nopreflightSpecify the preflight check(s) to skip.
FlagDescription
--dryDo not execute the pipeline. Generate a pipeline invocation (.mro) file and stop.

Check your system’s compatibility with Xenium Ranger system requirements.

Usage: xeniumranger sitecheck > sitecheck.txt

OptionDescription
-h, --helpShow help message.
--versionShow version.

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>

Upload a file to the 10x Genomics support team.

Usage: xeniumranger upload <your email> <file>