Support homeXenium Ranger
Xenium Ranger Command Line Arguments

Xenium Ranger Command Line Arguments

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

The Martian runtime options are available for Xenium Ranger relabel, rename, 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.

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 rename --help # Argument option names and values can be separated by a space or = xeniumranger rename [OPTIONS] --id=<ID> --xenium-bundle=<XENIUM_BUNDLE> \ --region_name=<NAME> --cassette_name=<NAME>
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.
--region_nameNew region name. Limit of 64 characters, upper or lowercase letters, numbers, underscores, and hyphens.
--cassette_nameNew cassette name. Limit of 32 characters, upper or lowercase letters, numbers, underscores, and hyphens.

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.
--boundary-stainSpecify the name of the boundary stain to use or disable. Supported for cell segmentation staining workflow output bundles. Possible options are: "ATP1A1/CD45/E-Cadherin" (default) or "disable".
--interior-stainSpecify the name of the interior stain to use or disable. Supported for cell segmentation staining workflow output bundles. Possible options are: "18S" (default) or "disable".
--expansion-distanceNuclei boundary expansion distance in µm. Default: 5 (Min: 0, Max: 15 if either --boundary-stain or --interior-stain are enabled and 100 if nucleus-expansion only).
--dapi-filterMinimum intensity in photoelectrons (pe) to filter nuclei. 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. This parameter is deprecated and will be removed in a future release, see import-segmentation example for preferred method.

See compatible segmentation input formats for file specifications.

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. Default: 5 (accepted range: 0 - 100).
--nucleiLabel mask (TIFF or NPY), polygons of nucleus segmentations (GeoJSON FeatureCollection), or Xenium Onboard Analysis cells.zarr.zip (the nucleus masks as input). --nuclei will use nucleusGeometry polygon if it exists in the GeoJSON (i.e., for QuPath-like GeoJSON files), or geometry if it does not. Error if --transcript-assignment argument is used.
--cellsLabel mask (TIFF or NPY), polygons of cell segmentations (GeoJSON FeatureCollection), or Xenium Onboard Analysis cells.zarr.zip (the cell masks as input). Features with a non-cell objectType will be ignored. Error if --transcript-assignment argument is used. In Xenium Ranger v2.0, --nuclei no longer needs to be used with --cells.
--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 or label mask 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.

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 (see format specifications).

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 v0.6 (see format specifications). Required if --transcript-assignment argument used. Error if --cells or --nuclei arguments used.
--transcript-assignmentTranscript CSV with cell assignment from Baysor v0.6 (see format specifications). 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 v0.6 inputs.

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

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).
--nopreflightBoolean to skip all preflight checks.
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

FlagDescription
-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. Learn more on the troubleshooting page.

Usage: xeniumranger upload <your email> <file>