Read a single-cell file into an in-memory R object
Description
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(). |
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.
Value
A SingleCellExperiment, Seurat, or named list.
Examples
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