Skip to contents

Load an AnnData H5AD file as a Seurat object

Source: R/LoadH5AD.R
readH5AD.Rd

Direct conversion from H5AD format to Seurat object without intermediate h5Seurat. Supports optional BPCells on-disk matrix loading for large datasets that exceed available memory. When compiled C routines are available, uses a fast native reader (typically 2-3x faster than the pure-R path).

Usage

readH5AD(
  file,
  assay.name = "RNA",
  use.bpcells = NULL,
  components = NULL,
  use.c = TRUE,
  verbose = TRUE,
  reductions = NULL
)

Arguments

file

Path to H5AD file

assay.name

Name for the primary assay (default: "RNA")

use.bpcells

If not NULL, a directory path where BPCells will store the expression matrix on disk. Requires the BPCells package. The resulting Seurat object will reference the on-disk matrix instead of loading it into memory, enabling analysis of datasets larger than available RAM.

components

Character vector of h5ad components to load. Default loads everything. Use c("X") for matrix-only (fastest), or any subset of c("X", "obs", "var", "obsm", "obsp", "varp", "layers", "uns"). The file path is stored in misc[[".__h5ad_path__"]] for deferred loading via scLoadMeta.

use.c

Use compiled C reader when available (default: TRUE). Set to FALSE to force the pure-R hdf5r path.

verbose

Show progress messages

reductions

Which obsm entries to load as dimensional reductions. NULL (default) loads all of them under cleaned names (leading X_ stripped). Pass a character vector of obsm keys to load a subset, optionally named to control the Seurat reduction names: reductions = c(scvi = "X_scVI", umap = "X_umap") loads only those two keys as reductions scvi and umap. Name collisions (e.g. X_pca and pca both present) are resolved by keeping the raw obsm key for later claimants, with a warning, instead of the previous silent overwrite.

Value

A Seurat object. If use.bpcells is set, the count matrix is stored on disk in BPCells format and the object uses minimal memory.

Post-read verification

Before returning, the loaded object is verified against the file: dims must match the file's obs/var counts (orientation check), cell names must equal the obs index in order, feature names must equal the var index modulo Seurat's documented underscore-to-dash replacement, and no duplicate barcodes/features may survive. Violations raise scConvert_data_error. Duplicate names in the file are made unique with a scConvert_names_warning; a counts layer left holding non-integer values raises a scConvert_counts_warning. What the reader did (which slot became the counts layer, where X went, the scConvert version) is recorded in misc$scConvert_read.