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).
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 aDelayedMatrix. 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.h5adis wrapped withHDF5Array::H5SparseMatrixwhen that package is installed; everything else (AnnData Zarr, 10x, H5Seurat, ...) withPicklerickMatrix(), a seed that reads selected cells through scx. Only whenas = "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 ofunsintometadata()(SingleCellExperiment) or@misc(Seurat). The defaultFALSEstores only the source path there, anduns()reads keys on demand.- constructor
How to build the Seurat object when
as = "Seurat"."standard"(default) callsSeuratObject::CreateSeuratObject()."fast"is an unofficial, experimental constructor: it assembles the Seurat v5Assay5directly from its slots, so the counts layer is the matrix just read rather than the two subset copiesCreateSeuratObject()makes, andnCount/nFeaturecome 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 (theAssay5slot layout,LogMap, theSeurat.object.assay.calcnoption) and may drift with a SeuratObject release. It is only used on SeuratObject 5.x and on input that needs none ofCreateSeuratObject()'s sanitising (no_, empty or duplicate names; noorig.ident/nCount_RNA/nFeature_RNAcolumns inobs); 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.
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
} # }