quality of life improvements

R/AbstractAnnData.R

@@ -188,6 +188,33 @@ AbstractAnnData <- R6::R6Class("AbstractAnnData", # nolint
         compression = compression,
         mode = mode
       )
+    },
+    #' @description Write the AnnData object to an H5AD file.
+    #' @param path The path to the H5AD file
+    #' @param compression The compression algorithm to use when writing the
+    #' HDF5 file. Can be one of `"none"`, `"gzip"` or `"lzf"`. Defaults to
+    #' `"none"`.
+    #' @param mode The mode to open the HDF5 file.
+    #' * `a` creates a new file or opens an existing one for read/write.
+    #' * `r+` opens an existing file for read/write.
+    #' * `w` creates a file, truncating any existing ones
+    #' * `w-`/`x` are synonyms creating a file and failing if it already exists.
+    #' @return `path` invisibly
+    #' @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_h5ad = function(path, compression = "gzip", mode = "w") {
+      self$to_HDF5AnnData(path, compression = compression, mode = mode)
+      path
     }
   ),
   private = list(

R/write_h5ad.R

@@ -29,7 +29,7 @@
 #'   var = data.frame(row.names = letters[1:5], gene = 1:5)
 #' )
 #' h5ad_file <- tempfile(fileext = ".h5ad")
-#' write_h5ad(adata, h5ad_file)
+#' adata$write_h5ad(h5ad_file)
 #'
 #' # Write a SingleCellExperiment as an H5AD
 #' if (requireNamespace("SingleCellExperiment", quietly = TRUE)) {
@@ -45,31 +45,34 @@
 #'     reducedDims = list(PCA = pca, tSNE = tsne)
 #'   )
 #'
+#'   adata <- from_SingleCellExperiment(sce)
 #'   h5ad_file <- tempfile(fileext = ".h5ad")
-#'   write_h5ad(sce, h5ad_file)
+#'   adata$write_h5ad(h5ad_file)
 #' }
 #'
 #' # Write a Seurat as a H5AD
-#' if (requireNamespace("SeuratObject", quietly = TRUE)) {
-#'   # TODO: uncomment this code when the seurat converter is fixed
-#'   # counts <- matrix(1:15, 3L, 5L)
-#'   # dimnames(counts) <- list(
-#'   #   letters[1:3],
-#'   #   LETTERS[1:5]
-#'   # )
-#'   # gene.metadata <- data.frame(
-#'   #   row.names = LETTERS[1:5],
-#'   #   gene = 1:5
-#'   # )
-#'   # obj <- SeuratObject::CreateSeuratObject(counts, meta.data = gene.metadata)
-#'   # cell.metadata <- data.frame(
-#'   #   row.names = letters[1:3],
-#'   #   cell = 1:3
-#'   # )
-#'   # obj <- SeuratObject::AddMetaData(obj, cell.metadata)
-#'   #
-#'   # h5ad_file <- tempfile(fileext = ".h5ad")
-#'   # write_h5ad(obj, h5ad_file)
+#' 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 <- from_Seurat(obj)
+#'   h5ad_file <- tempfile(fileext = ".h5ad")
+#'   adata$write_h5ad(h5ad_file)
 #' }
 write_h5ad <- function(
     object,