Read and Load 10x Genomics Xenium in-situ data

Usage

LoadXenium(
  data.dir,
  fov = "fov",
  assay = "Xenium",
  mols.qv.threshold = 20,
  cell.centroids = TRUE,
  molecule.coordinates = TRUE,
  segmentations = NULL,
  flip.xy = FALSE,
  genes = NULL,
  region = NULL
)

ReadXenium(
  data.dir,
  outs = c("segmentation_method", "matrix", "microns"),
  type = "centroids",
  mols.qv.threshold = 20,
  flip.xy = F,
  genes = NULL,
  region = NULL,
  cells = NULL
)

Arguments

data.dir

Directory containing all Xenium output files with default filenames

fov

FOV name

assay

Assay name

mols.qv.threshold

Remove transcript molecules with a QV less than this threshold. QV >= 20 is the standard threshold used to construct the cell x gene count matrix.

cell.centroids

Whether or not to load cell centroids

molecule.coordinates

Whether or not to load molecule coordinates immediately. For Xenium, FALSE skips transcript reads.

segmentations

One of "cell", "nucleus" or NULL (to load either cell segmentations, nucleus segmentations or neither)

flip.xy

Swap x and y in the loaded coordinates. Deprecated for LoadXenium, where flip.xy = TRUE requires SeuratObject >= 5.3.0. To change only the plot, use flip_xy = TRUE in ImageDimPlot or ImageFeaturePlot.

genes

Optional gene names to restrict molecule coordinates to. Counts are unaffected. NULL loads all genes when molecules are requested. LoadXenium accepts source or assay feature names; ReadXenium requires source names.

region

Optional list with x and y elements, each an increasing length-two micron range. Restricts molecule coordinates using the returned coordinate system, including any flip.xy transformation. Counts, centroids, and boundaries are unaffected.

outs

Types of molecular outputs to read; choose one or more of:

“matrix”: the counts matrix
“microns”: molecule coordinates
“segmentation_method”: cell segmentation method (for runs which use multi-modal segmentation)

type

Type of cell spatial coordinate matrices to read; choose one or more of:

“centroids”: cell centroids in micron coordinate space
“segmentations”: cell segmentations in micron coordinate space
“nucleus_segmentations”: nucleus segmentations in micron coordinate space

cells

Optional cell IDs to restrict segmentation boundaries to. Counts and centroids are unaffected.

Value

LoadXenium: A Seurat object

ReadXenium: A list with some combination of the following values:

“matrix”: a named list of expression matrices, one per feature type. Matrices are sparse in memory; cells are columns and features are rows
“centroids”: a data frame with cell centroid coordinates in three columns: “x”, “y”, and “cell”
“microns”: a data frame with molecule coordinates in three columns: “x”, “y”, and “gene”

Details

By default, LoadXenium keeps the original coordinates. ImageDimPlot and ImageFeaturePlot display x horizontally and y increasing downward, including for older objects. Use flip_xy = TRUE in either plotting function to reproduce the old plot layout without changing stored coordinates.

The deprecated LoadXenium(flip.xy = TRUE) requires SeuratObject >= 5.3.0 to record the axis orientation. With that version or later, it swaps stored coordinates and retains its previous plotting behavior. To crop using stored x/y ranges, use Crop(..., coords = "tissue").

Molecule tables are read into memory before gene, region, and QV filters are applied. Parquet files use Arrow, falling back to CSV on failure. CSV files use data.table when available. Legacy transcript tables without a qv column retain their molecules without QV filtering. The selected molecule coordinates are stored in memory.

Use molecule.coordinates = FALSE to load counts and centroids without reading transcript coordinates. LoadXenium retains its default of immediately loading molecules. Cell metadata is read once per call for segmentation methods and centroids.

LoadXenium labels molecules with assay feature names, e.g. Under_score becomes Under-score. ReadXenium keeps source names.

Examples

if (FALSE) { # \dontrun{
xenium <- LoadXenium("xenium_outs", molecule.coordinates = FALSE)
# Select molecules immediately, using micron ranges in the returned axes.
selected <- LoadXenium("xenium_outs", genes = "EPCAM",
  region = list(x = c(100, 500), y = c(200, 600)))
} # }