implement backend for MatrixH5 class

DESCRIPTION

@@ -44,6 +44,7 @@ Collate:
     'Class-BindMatrix.R'
     'Class-Convert.R'
     'Class-Dir.R'
+    'Class-HDF5.R'
     'Class-Mask.R'
     'Class-Mem.R'
     'Class-RankTransform.R'

NAMESPACE

@@ -15,14 +15,18 @@ export(pmin_by_row)
 export(pmin_scalar)
 export(pow_slow)
 export(rank_transform)
-export(readDirMatrix)
+export(readBPCellsDirMatrix)
+export(readBPCellsHDF5Matrix)
 export(set_threads)
 export(transpose_storage)
 export(writeBPCellsDirArray)
+export(writeBPCellsHDF5Array)
 export(writeBPCellsMemArray)
 exportClasses(BPCellsArray)
 exportClasses(BPCellsDirArray)
 exportClasses(BPCellsDirMatrix)
+exportClasses(BPCellsHDF5Array)
+exportClasses(BPCellsHDF5Matrix)
 exportClasses(BPCellsMatrix)
 exportClasses(BPCellsMemArray)
 exportClasses(BPCellsMemMatrix)
@@ -88,6 +92,7 @@ exportMethods(t)
 exportMethods(transpose_storage)
 exportMethods(type)
 exportMethods(writeBPCellsDirArray)
+exportMethods(writeBPCellsHDF5Array)
 exportMethods(writeBPCellsMemArray)
 importClassesFrom(BiocSingular,BiocSingularParam)
 importClassesFrom(DelayedArray,DelayedArray)

R/Class-HDF5.R

@@ -0,0 +1,129 @@
+# For every new class
+# - add method of subset: Method-subset.R
+# - add method of showtree: showtree.R
+methods::setClass("BPCellsHDF5Seed",
+    contains = c("BPCellsSeed", get_class("MatrixH5"))
+)
+
+BPCellsHDF5Seed <- function(x) methods::as(x, "BPCellsHDF5Seed")
+
+#' @export
+#' @rdname BPCellsSeed
+methods::setMethod("BPCellsSeed", "MatrixH5", function(x) {
+    BPCellsHDF5Seed(x = x)
+})
+
+#' @importClassesFrom DelayedArray DelayedArray
+#' @export
+#' @rdname BPCellsSeed
+#' @include Class-BPCellsMatrix.R
+methods::setClass("BPCellsHDF5Array",
+    contains = "BPCellsArray",
+    slots = c(seed = "BPCellsHDF5Seed")
+)
+
+#' @importFrom DelayedArray DelayedArray
+#' @importFrom DelayedArray new_DelayedArray
+#' @export
+#' @rdname BPCellsMatrix-class
+methods::setMethod(
+    "DelayedArray", "BPCellsHDF5Seed",
+    function(seed) new_DelayedArray(seed, Class = "BPCellsHDF5Array")
+)
+
+#' @export
+#' @rdname BPCellsMatrix-class
+methods::setClass("BPCellsHDF5Matrix",
+    contains = c("BPCellsMatrix"),
+    slots = c(seed = "BPCellsHDF5Seed")
+)
+
+#' @importFrom DelayedArray matrixClass
+#' @export
+#' @rdname BPCellsMatrix-class
+methods::setMethod("matrixClass", "BPCellsHDF5Array", function(x) {
+    "BPCellsHDF5Matrix"
+})
+
+#' Read/write sparse matrices from (or into) HDF5 file
+#'
+#' @description
+#' - `readBPCellsHDF5Matrix`: read a sparce matrices from a HDF5 file on disk
+#' - `writeBPCellsHDF5Array`: Write a sparce matrices into a HDF5 file on disk
+#' @param path A string path of the `HDF5` file to read or save data into.
+#' @export
+#' @name BPCellsHDF5-IO
+readBPCellsHDF5Matrix <- function(path, group, buffer_size = 8192L) {
+    assert_string(path, empty_ok = FALSE)
+    obj <- BPCells::open_matrix_hdf5(
+        path = path, group = group,
+        buffer_size = as.integer(buffer_size)
+    )
+    DelayedArray(BPCellsHDF5Seed(obj))
+}
+
+#' @inherit BPCells::write_matrix_hdf5 details
+#' @inheritParams writeBPCellsDirArray
+#' @inheritParams BPCells::open_matrix_hdf5
+#' @param gzip Gzip compression level. Default is 0 (no gzip compression). This
+#' is recommended when both compression and compatibility with outside programs
+#' is required. Using `compress=TRUE` is recommended as it is >10x faster with
+#' often similar compression levels. So `gzip` will always be zero when
+#' `compress` is `TRUE`.
+#' @return A [BPCellsMatrix][BPCellsMatrix-class] object.
+#' @export
+#' @aliases writeBPCellsHDF5Array
+#' @rdname BPCellsHDF5-IO
+methods::setGeneric(
+    "writeBPCellsHDF5Array",
+    function(x, ...) standardGeneric("writeBPCellsHDF5Array")
+)
+
+.writeBPCellsHDF5Array <- function(x, path, group, bitpacking = TRUE, buffer_size = 8192L, chunk_size = 1024L, overwrite = FALSE, gzip = 0L) {
+    assert_bool(bitpacking)
+    assert_bool(overwrite)
+    if (bitpacking) {
+        gzip <- 0L
+    } else {
+        gzip <- as.integer(gzip)
+    }
+    obj <- BPCells::write_matrix_hdf5(
+        mat = x, path = path, group = group,
+        compress = bitpacking,
+        buffer_size = as.integer(buffer_size),
+        chunk_size = as.integer(chunk_size),
+        overwrite = overwrite, gzip_level = gzip
+    )
+    DelayedArray(BPCellsHDF5Seed(obj))
+}
+
+#' @export
+#' @rdname BPCellsHDF5-IO
+methods::setMethod(
+    "writeBPCellsHDF5Array", "IterableMatrix", .writeBPCellsHDF5Array
+)
+
+#' @export
+#' @rdname BPCellsHDF5-IO
+methods::setMethod(
+    "writeBPCellsHDF5Array", "BPCellsSeed",
+    .writeBPCellsHDF5Array
+)
+
+#' @export
+#' @rdname BPCellsHDF5-IO
+methods::setMethod("writeBPCellsHDF5Array", "BPCellsMatrix", function(x, ...) {
+    .writeBPCellsHDF5Array(x = x@seed, ...)
+})
+
+#' @export
+#' @rdname BPCellsHDF5-IO
+methods::setMethod("writeBPCellsHDF5Array", "dgCMatrix", .writeBPCellsHDF5Array)
+
+#' @export
+#' @rdname BPCellsHDF5-IO
+methods::setMethod("writeBPCellsHDF5Array", "ANY", function(x, ...) {
+    .writeBPCellsHDF5Array(x = coerce_dgCMatrix(x), ...)
+})
+
+.as_BPCellsHDF5Array <- function(from) writeBPCellsHDF5Array(from)

R/Method-subset.R

@@ -28,26 +28,34 @@ BPCellsSubset_internal <- function(x, i, j, ..., drop = FALSE) {
 #' @param i,j Row and Column index.
 #' @param drop Ignored, always be `FALSE`.
 #' @importMethodsFrom BPCells [
-#' @export
 #' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsColBindMatrixSeed", BPCellsSubset_internal)
+methods::setMethod("[", "BPCellsdgCMatrixSeed", BPCellsSubset_internal)
 
 #' @importMethodsFrom BPCells [
-#' @export
 #' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsRowBindMatrixSeed", BPCellsSubset_internal)
+methods::setMethod("[", "BPCellsDirSeed", BPCellsSubset_internal)
 
 #' @importMethodsFrom BPCells [
 #' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsConvertSeed", BPCellsSubset_internal)
+methods::setMethod("[", "BPCellsHDF5Seed", BPCellsSubset_internal)
 
 #' @importMethodsFrom BPCells [
 #' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsdgCMatrixSeed", BPCellsSubset_internal)
+methods::setMethod("[", "BPCellsMemSeed", BPCellsSubset_internal)
 
 #' @importMethodsFrom BPCells [
+#' @export
 #' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsDirSeed", BPCellsSubset_internal)
+methods::setMethod("[", "BPCellsColBindMatrixSeed", BPCellsSubset_internal)
+
+#' @importMethodsFrom BPCells [
+#' @export
+#' @rdname BPCellsSeed-methods
+methods::setMethod("[", "BPCellsRowBindMatrixSeed", BPCellsSubset_internal)
+
+#' @importMethodsFrom BPCells [
+#' @rdname BPCellsSeed-methods
+methods::setMethod("[", "BPCellsConvertSeed", BPCellsSubset_internal)
 
 #' @importMethodsFrom BPCells [
 #' @rdname BPCellsSeed-methods
@@ -75,7 +83,3 @@ methods::setMethod("[", "BPCellsSubsetSeed", BPCellsSubset_internal)
 #' @importMethodsFrom BPCells [
 #' @rdname BPCellsSeed-methods
 methods::setMethod("[", "BPCellsTransformedSeed", BPCellsSubset_internal)
-
-#' @importMethodsFrom BPCells [
-#' @rdname BPCellsSeed-methods
-methods::setMethod("[", "BPCellsMemSeed", BPCellsSubset_internal)

R/showtree.R

@@ -117,7 +117,7 @@ methods::setReplaceMethod("path", "BPCellsMatrix", function(object, value) {
 # different with what DelayedArray dose, this is because that seedApply()
 # function is not a generic function, we cannot define methods for it.
 
-# Three basic seeds ------------------------------------------
+# Four basic seeds ------------------------------------------
 ###########################################################
 #' @importFrom DelayedArray path
 #' @export
@@ -138,6 +138,10 @@ methods::setMethod("path", "BPCellsdgCMatrixSeed", function(object, ...) {
 #' @rdname showtree
 methods::setMethod("path", "BPCellsDirSeed", function(object, ...) object@dir)
 
+#' @export
+#' @rdname showtree
+methods::setMethod("path", "BPCellsHDF5Seed", function(object, ...) object@path)
+
 #' @export
 #' @rdname showtree
 methods::setMethod("seed", "BPCellsSeed", function(x) x)