Access uns metadata from a read_h5ad() result on demand

Description

When read_h5ad() is called with the default parse_uns = FALSE, the uns slot is not eagerly materialised — the source file path is stashed in metadata(sce)$.uns_path (for SCE) or obj@misc$.uns_path (for Seurat). Use uns() to read keys on demand via rhdf5, which is both faster and ~10–20× cheaper in memory than the eager JSON path (HDF5 stores uns as native typed arrays; the eager parse goes through JSON which inflates every integer into REALSXP).

Usage

uns(x, key = NULL, sub_key = NULL)

Arguments

x A SingleCellExperiment, Seurat, or named list returned by read_h5ad(), OR a path string to an .h5ad file directly.
key Top-level uns key. If NULL, returns the list of available keys (cheap; uses HDF5 group listing).
sub_key Optional sub-key for nested uns (e.g. one condition under a per-condition dict). If supplied, only that leaf is read.

Value

If key is NULL: character vector of top-level uns keys. Otherwise the value at that path (a vector, list, or scalar depending on the on-disk layout).

Examples

sce <- read_h5ad("norman.h5ad")           # parse_uns = FALSE
uns(sce)                                  # list top-level keys
x <- uns(sce, "top_non_zero_de_20")       # read one whole key
x <- uns(sce, "top_non_zero_de_20", "A549_AHR+FEV_1+1")  # one leaf