Skip to contents

Reads any format picklerick supports (AnnData .h5ad files and Zarr stores, H5Seurat, 10x HDF5 and MatrixMarket, BPCells; detected from the content, not the extension) and returns a SingleCellExperiment (default), a Seurat object, or the raw named list of pieces (as = "list") for callers that want to assemble something else.

read_zarr() reads an AnnData Zarr store (a .zarr directory, Zarr v2 or v3, including the sharded v3 arrays anndata >= 0.13 writes by default). It is read_h5ad() under another name: the format is detected from the content, so read_h5ad() reads Zarr stores too. With lazy = TRUE the matrix is a PicklerickMatrix(). For Zarr stores uns is only available through parse_uns = TRUE (the on-demand uns() accessor reads HDF5).

Usage

read_h5ad(
  path,
  as = c("SingleCellExperiment", "Seurat", "AnnData", "list"),
  chunk_size = 5000L,
  lazy = FALSE,
  parse_uns = FALSE,
  constructor = c("standard", "fast")
)

read_zarr(path, ...)

Arguments

path

Path to the file.

as

Target class: "SingleCellExperiment" (default), "AnnData" for a light handle that defers building R objects until a component is touched (see AnnDataLight; building a SingleCellExperiment costs a constant ~3.3s of S4 warm-up whatever the dataset size), "Seurat", or "list".

chunk_size

Cells per internal streaming chunk. Default 5000L.

lazy

When TRUE, leave the X matrix on disk and wrap it in a DelayedMatrix. The Rust side only reads metadata (obs / var / obsm / varm / uns), so peak memory is bounded by metadata size rather than the count matrix. An .h5ad is wrapped with HDF5Array::H5SparseMatrix when that package is installed; everything else (AnnData Zarr, 10x, H5Seurat, ...) with PicklerickMatrix(), a seed that reads selected cells through scx. Only when as = "SingleCellExperiment" (Seurat does not consume DelayedArray natively). Layers are wrapped the same way, so the assays match the eager read; obsp is not attached in lazy mode.

parse_uns

When TRUE, read all of uns into metadata() (SingleCellExperiment) or @misc (Seurat). The default FALSE stores only the source path there, and uns() reads keys on demand.

constructor

How to build the Seurat object when as = "Seurat". "standard" (default) calls SeuratObject::CreateSeuratObject(). "fast" is an unofficial, experimental constructor: it assembles the Seurat v5 Assay5 directly from its slots, so the counts layer is the matrix just read rather than the two subset copies CreateSeuratObject() makes, and nCount/nFeature come from the sparse structure. On 10x 10k cells that is +0 MB instead of +535 MB over the matrix, and 0.14 s instead of 1.0 s, for an object identical in every checked respect. It relies on SeuratObject internals (the Assay5 slot layout, LogMap, the Seurat.object.assay.calcn option) and may drift with a SeuratObject release. It is only used on SeuratObject 5.x and on input that needs none of CreateSeuratObject()'s sanitising (no _, empty or duplicate names; no orig.ident/nCount_RNA/nFeature_RNA columns in obs); otherwise it falls back to "standard" with a message.

...

Passed on to read_h5ad().

Value

A SingleCellExperiment, Seurat, or named list.

Details

In a SingleCellExperiment, X becomes the counts assay and each layer an assay of its own name. When a layer is itself called counts, X is named X instead, so the two never share a name.

Memory: this v1 materializes the X matrix in both Rust and R (~2× peak). For very large datasets prefer convert() (streaming, file-to-file).

Integer X is cast to double to match Seurat conventions and avoid integer-overflow in downstream normalization.

Layers whose shape doesn't match (n_obs, n_vars) are dropped with a warning. obsp is currently only attached to SingleCellExperiment (via colPair); it is dropped with a warning for Seurat output.

Examples

if (FALSE) { # \dontrun{
sce <- read_h5ad("pbmc3k.h5ad")
obj <- read_h5ad("pbmc3k.h5ad", as = "Seurat")
raw <- read_h5ad("pbmc3k.h5ad", as = "list")  # advanced

# Lazy mode — X stays on disk, no full materialization.
sce <- read_h5ad("huge.h5ad", lazy = TRUE)
counts(sce)            # DelayedMatrix
counts(sce)[1:10, ]    # only these rows hit disk
} # }