Skip to contents

Load Atera spatial data

Source: R/preprocessing.R
ReadAtera.Rd

Read the output of 10x Genomics Atera, a next-generation in situ sequencing platform. All Atera outputs (aside from images) are stored in AnnData zarr (storage format v2) files, zipped with Stored (uncompressed) zip entries; reading them requires the blosc and jsonlite packages. Zarr chunks are read directly out of the zip archive by byte-range seeks with no disk extraction.

Usage

ReadAtera(
  data.dir,
  outs = c("matrix", "centroids"),
  mols.qv.threshold = 20,
  genes = NULL,
  feature.types = NULL,
  bpcells.dir = NULL,
  morphology.channel = "dapi",
  morphology.resolution = NULL,
  morphology.region = NULL
)

LoadAtera(
  data.dir,
  fov = "fov",
  assay = "Atera",
  mols.qv.threshold = 20,
  cell.centroids = TRUE,
  molecule.coordinates = FALSE,
  segmentations = NULL,
  cell.annotations = TRUE,
  genes = NULL,
  feature.types = NULL,
  bpcells.dir = NULL,
  morphology.image = FALSE,
  morphology.channel = "dapi",
  morphology.resolution = NULL,
  morphology.region = NULL
)

Arguments

data.dir

Path to folder containing Atera outputs

outs

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

  • “matrix”: the counts matrix

  • “centroids”: cell centroids in micron coordinate space

  • “segmentations”: cell segmentation boundary polygons in micron coordinate space

  • “nucleus_segmentations”: nucleus segmentation boundary polygons in micron coordinate space. Cells may have zero, one, or more than one nucleus polygon

  • “annotations”: per-cell Azimuth cell type annotations (the azimuth_* columns of cell_feature_matrix.zarr.zip), if available

  • “microns”: transcript molecule coordinates. This is optional as transcripts files can be very large.

  • “morphology”: a single channel plane of a “morphology_2d” image (eg the DAPI stain), by default at the lowest-resolution pyramid level, for use as a background/overview image. Requires the RBioFormats package, since these images are pyramidal, JPEG2000-compressed OME-TIFFs that the base tiff package cannot reliably decode.

mols.qv.threshold

Remove transcript molecules with a calibrated Q-score less than this threshold

genes

Optional character vector of gene names to restrict the initial molecule.coordinates load to. When molecule.coordinates = TRUE, a lazy, on-disk handle onto the transcript table is always kept on the returned object (regardless of whether genes is set), so additional genes can be fetched later with LoadAteraMolecules without re-reading genes already fetched. See ReadAtera

feature.types

Optional character vector of feature types to restrict the counts matrix to (eg “Gene Expression”); NULL (the default) loads all feature types, matching current behavior. “Gene Expression” is always included, since it backs the object's primary assay. See ReadAtera

bpcells.dir

Path to a directory used to cache the counts matrix on disk via BPCells. NULL (the default) auto-selects a session-scoped cache directory so the returned object is BPCells-backed and lazy by default (even for small bundles) whenever BPCells is installed; pass FALSE to always get plain in-memory matrices instead. See ReadAtera

morphology.channel

Channel to load when morphology.image = TRUE: either a channel name (matched case-insensitively as a substring, eg “dapi”) or a 0-based integer channel index. See ReadAtera

morphology.resolution

Pyramid resolution level to load when morphology.image = TRUE, where 1 is full resolution. Defaults to NULL, which loads the lowest-resolution (smallest, fastest) level available. See ReadAtera

morphology.region

Optional list with x/y elements (each a length-2 micron range) to crop the loaded morphology image to a rectangular window instead of reading the whole plane; recommended when using morphology.resolution = 1 (full resolution) on real-world datasets, since these whole-slide images can be tens of thousands of pixels per side. Defaults to NULL, which reads the whole plane. See ReadAtera

fov

FOV name

assay

Assay name

cell.centroids

Whether or not to load cell centroids

molecule.coordinates

Whether or not to load transcript molecule coordinates

segmentations

Which segmentation boundary polygons to load, one of “cell” or “nucleus”, or NULL to load none

cell.annotations

Whether or not to add Azimuth cell type annotations (azimuth_*) to the object's metadata; silently skipped when the annotations are not available in data.dir

morphology.image

Whether to load a single channel plane of a “morphology_2d” image (eg the DAPI stain), by default at the lowest-resolution pyramid level, for use as a background/overview image in plots. Requires the RBioFormats package. Defaults to FALSE since it is an optional dependency and not needed for downstream analysis. See ReadAtera

Value

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

  • “matrix”: a named list of sparse matrices with expression data, one per feature type (eg “Gene Expression”); cells are columns and features are rows

  • “centroids”: a data frame with cell centroid coordinates in three columns: “x”, “y”, and “cell”

  • “segmentations”/“nucleus_segmentations”: a data frame with one row per polygon vertex, in three columns: “cell”, “x”, and “y”

  • “annotations”: a data frame of Azimuth annotations with cell ids as row names, or NULL if none are available

  • “microns”: a data frame with transcript coordinates in three columns: “x”, “y”, and “gene”

  • “morphology”: a list with elements image (a numeric matrix, indexed [x, y], in the same top-left-origin pixel convention as “centroids”/“microns”' micron coordinates – no axis flip is needed), channel, resolution, n.resolutions, pixel.size (microns per pixel of image), and origin (the micron coordinates, c(x=, y=), of image's [1, 1] pixel – c(x=0, y=0) unless morphology.region crops out the top-left corner of the full plane); see morphology.channel/morphology.resolution/morphology.region

LoadAtera: A Seurat object

Details

Parallel processing uses the active future::plan(). Molecule and codeword reads parallelize across tiles; numeric array reads parallelize chunk decoding. Array reads inside tile workers stay sequential to avoid nested parallelism. Configure the strategy and worker count with future::plan(future::multisession, workers = 4), or use future::plan(future::sequential) for sequential processing. This setting is independent of setThreads().

Newly loaded Atera FOVs display x horizontally and y increasing downward in ImageDimPlot and ImageFeaturePlot, keeping stored coordinates unchanged.