Write an H5AD file
Arguments
- object
The object to write, either a
SingleCellExperiment::SingleCellExperimentor aSeuratObject::Seuratobject- path
Path of the file to write to
- compression
The compression algorithm to use when writing the HDF5 file. Can be one of
"none","gzip"or"lzf". Defaults to"none".- chunk_size
The target chunk size in bytes to use when writing HDF5 datasets. When
"auto"(default), the chunk size is determined automatically using an algorithm that mimics h5py's auto-chunking behaviour. Set toNULLto disable chunking (contiguous storage, the rhdf5 default), or a number to use a specific target size in bytes. This only affects array-like datasets; scalar values are unaffected.- mode
The mode to open the HDF5 file. When
groupis not"/", these apply to the groupgrouprather than the whole file:acreates a new file or opens an existing one for read/write. The group atgroupis created if it doesn't exist yet.ropens an existing file for reading, the groupgroupmust already exist.r+opens an existing file for read/write, the groupgroupmust already exist.wcreates a file, truncating any existing ones. Whengroup != "/", the file is created if missing but otherwise left untouched, and only the groupgroupis deleted and recreated. HDF5 doesn't free the space used by the deleted group, see the "File size" section below.w-/xare synonyms, creating a file and failing if it already exists. Whengroup != "/", they instead fail if the groupgroupalready exists.
- group
The path to the group within the HDF5 file that the
AnnDatais written to. Defaults to"/", the file root. Can be used to write anAnnDatato a group inside a file that also contains other content, e.g. a modality inside a.h5mufile.- ...
Additional arguments passed to
as_AnnData()
Details
Compression
Compression is currently not supported for Boolean arrays, they will be written uncompressed.
File size
Deleting or replacing an element in an HDF5 file only unlinks it, the space
it used is not freed. This happens when writing with mode = "w" to a
group that already exists, or when replacing a slot of an HDF5AnnData
opened with mode "r+" or "a". Repeated rewrites will grow the file. To
reclaim the space, copy the file with the h5repack command-line tool that
comes with HDF5, e.g. h5repack old.h5ad new.h5ad.
NULL values
For compatibility with changes in Python anndata 0.12.0, NULL values
in uns are written to H5AD files as a NULL dataset (instead of not being
written at all). To disable this behaviour, set
option(anndataR.write_null = FALSE). This may be required to allow the file
to be read by older versions of Python anndata.
Examples
adata <- AnnData(
X = matrix(1:5, 3L, 5L),
layers = list(
A = matrix(5:1, 3L, 5L),
B = matrix(letters[1:5], 3L, 5L)
),
obs = data.frame(row.names = LETTERS[1:3], cell = 1:3),
var = data.frame(row.names = letters[1:5], gene = 1:5)
)
h5ad_file <- tempfile(fileext = ".h5ad")
adata$write_h5ad(h5ad_file)
# Write a SingleCellExperiment as an H5AD
if (requireNamespace("SingleCellExperiment", quietly = TRUE)) {
ncells <- 100
counts <- matrix(rpois(20000, 5), ncol = ncells)
logcounts <- log2(counts + 1)
pca <- matrix(runif(ncells * 5), ncells)
tsne <- matrix(rnorm(ncells * 2), ncells)
sce <- SingleCellExperiment::SingleCellExperiment(
assays = list(counts = counts, logcounts = logcounts),
reducedDims = list(PCA = pca, tSNE = tsne)
)
adata <- as_AnnData(sce)
h5ad_file <- tempfile(fileext = ".h5ad")
adata$write_h5ad(h5ad_file)
}
# Write a Seurat as a H5AD
if (requireNamespace("Seurat", quietly = TRUE)) {
library(Seurat)
counts <- matrix(1:15, 5L, 3L)
dimnames(counts) <- list(
LETTERS[1:5],
letters[1:3]
)
cell.metadata <- data.frame(
row.names = letters[1:3],
cell = 1:3
)
obj <- CreateSeuratObject(counts, meta.data = cell.metadata)
gene.metadata <- data.frame(
row.names = LETTERS[1:5],
gene = 1:5
)
obj[["RNA"]] <- AddMetaData(GetAssay(obj), gene.metadata)
adata <- as_AnnData(obj)
h5ad_file <- tempfile(fileext = ".h5ad")
adata$write_h5ad(h5ad_file)
}
#> Warning: Data is of class matrix. Coercing to dgCMatrix.