[r] Add iterator classes

apis/r/NAMESPACE

@@ -4,13 +4,15 @@ S3method("[",matrixZeroBasedView)
 S3method("[<-",matrixZeroBasedView)
 S3method("[[",MappingBase)
 S3method("[[<-",MappingBase)
+S3method(Ops,matrixZeroBasedView)
 S3method(as.list,MappingBase)
 S3method(as.one.based,matrixZeroBasedView)
 S3method(dim,matrixZeroBasedView)
 S3method(length,MappingBase)
 S3method(names,MappingBase)
 S3method(pad_matrix,default)
 S3method(pad_matrix,matrix)
+S3method(print,matrixZeroBasedView)
 S3method(write_soma,Assay)
 S3method(write_soma,DimReduc)
 S3method(write_soma,Graph)
@@ -20,6 +22,7 @@ S3method(write_soma,TsparseMatrix)
 S3method(write_soma,data.frame)
 S3method(write_soma,matrix)
 export(ConfigList)
+export(DenseReadIter)
 export(EphemeralCollection)
 export(EphemeralExperiment)
 export(EphemeralMeasurement)
@@ -50,6 +53,8 @@ export(SOMASparseNDArrayCreate)
 export(SOMASparseNDArrayOpen)
 export(SOMATileDBContext)
 export(ScalarMap)
+export(SparseReadIter)
+export(TableReadIter)
 export(TileDBArray)
 export(TileDBGroup)
 export(TileDBObject)

apis/r/R/ReadIter.R

@@ -0,0 +1,84 @@
+#' SOMA Read Iterator Base class
+#'
+#' Class that allows for read iteration of SOMA reads.
+
+ReadIter <- R6::R6Class(
+  classname = "ReadIter",
+
+  public = list(
+
+    #' @description Create (lifecycle: experimental)
+    #' @param uri Character value with URI path to a SOMADataFrame or SOMASparseNDArray
+    #' @param config character vector containing TileDB config.
+    #' @param colnames Optional vector of character value with the name of the columns to retrieve
+    #' @param qc Optional external Pointer object to TileDB Query Condition, defaults to \sQuote{NULL} i.e.
+    #' no query condition
+    #' @param dim_points Optional named list with vector of data points to select on the given
+    #' dimension(s). Each dimension can be one entry in the list.
+    #' @param loglevel Character value with the desired logging level, defaults to \sQuote{auto}
+    #' which lets prior setting prevail, any other value is set as new logging level.
+    initialize = function(uri, 
+                          config, 
+                          colnames = NULL, 
+                          qc = NULL, 
+                          dim_points = NULL, 
+                          loglevel = "auto") {
+
+        # Instantiate soma_reader_pointer with a soma_array_reader object
+          private$soma_reader_pointer <- sr_setup(
+            uri = uri,
+            config = config,
+            colnames = colnames,
+            qc = qc,
+            dim_points = dim_points,
+            loglevel = loglevel
+          )
+    },
+
+    #' @description Check if iterated read is complete or not. (lifecycle: experimental)
+    #' @return logical
+    read_complete = function() {
+      if (is.null(private$soma_reader_pointer)) {
+          TRUE
+      } else {
+          sr_complete(private$soma_reader_pointer)
+      }
+    },
+
+    #' @description Read the next chunk of an iterated read. (lifecycle: experimental).
+    #' If read is complete, retunrs `NULL` and raises warning.
+    #' @return \code{NULL} or one of arrow::\link[arrow]{Table}, \link{matrixZeroBasedView}
+    read_next = function() {
+      if (is.null(private$soma_reader_pointer)) {
+          NULL
+      } else {
+          if (self$read_complete()) {
+              warning("Iteration complete, returning NULL")
+              NULL
+          } else {
+              rl <- sr_next(private$soma_reader_pointer)
+              return(private$soma_reader_transform(rl))
+          }
+      }
+    },
+
+    #' @description  Concatenate remainder of iterator
+    # to be refined in derived classes
+    concat = function() {
+      .NotYetImplemented()
+    }
+
+  ),
+
+  private = list(
+
+    # Internal 'external pointer' object used for iterated reads
+    soma_reader_pointer = NULL,
+
+    # to be refined in derived classes
+    soma_reader_transform = function(x) {
+      .NotYetImplemented()
+    }
+
+  )
+)

apis/r/R/SOMAArrayBase.R

@@ -17,33 +17,6 @@ SOMAArrayBase <- R6::R6Class(
     }
   ),
 
-  public = list(
-
-    #' @description Check if iterated read is complete or not. (lifecycle: experimental)
-    read_complete = function() {
-      if (is.null(private$soma_reader_pointer)) {
-          TRUE
-      } else {
-          sr_complete(private$soma_reader_pointer)
-      }
-    },
-
-    #' @description Read the next chunk of an iterated read. (lifecycle: experimental)
-    read_next = function() {
-      if (is.null(private$soma_reader_pointer)) {
-          NULL
-      } else {
-          if (sr_complete(private$soma_reader_pointer)) {
-              invisible(NULL)
-          } else {
-              rl <- sr_next(private$soma_reader_pointer)
-              private$soma_reader_transform(rl)
-          }
-      }
-    }
-
-  ),
-
   private = list(
 
     # Cache object's SOMA_OBJECT_TYPE_METADATA_KEY
@@ -58,23 +31,6 @@ SOMAArrayBase <- R6::R6Class(
       meta[[SOMA_OBJECT_TYPE_METADATA_KEY]] <- self$class()
       meta[[SOMA_ENCODING_VERSION_METADATA_KEY]] <- SOMA_ENCODING_VERSION
       self$set_metadata(meta)
-    },
-
-    # Internal 'external pointer' object used for iterated reads
-    soma_reader_pointer = NULL,
-
-    # Instantiate soma_reader_pointer with a soma_array_reader object
-    soma_reader_setup = function() {
-      private$soma_reader_pointer <- sr_setup(
-        self$uri,
-        config=as.character(tiledb::config(self$tiledbsoma_ctx$context()))
-      )
-    },
-
-    ## to be refined in derived classes
-    soma_reader_transform = function(x) {
-      x
     }
-
   )
 )

apis/r/R/SOMADataFrame.R

@@ -170,7 +170,7 @@ SOMADataFrame <- R6::R6Class(
     #' @param iterated Option boolean indicated whether data is read in call (when
     #' `FALSE`, the default value) or in several iterated steps.
     #' @param log_level Optional logging level with default value of `"warn"`.
-    #' @return An [`arrow::Table`].
+    #' @return arrow::\link[arrow]{Table} or \link{TableReadIter}
     read = function(coords = NULL,
                     column_names = NULL,
                     value_filter = NULL,
@@ -181,7 +181,7 @@ SOMADataFrame <- R6::R6Class(
       result_order <- match_query_layout(result_order)
       uri <- self$uri
       arr <- self$object                 # need array (schema) to properly parse query condition
-
+      
       ## if unnamed set names
       if (!is.null(coords)) {
           if (!is.list(coords))
@@ -205,29 +205,26 @@ SOMADataFrame <- R6::R6Class(
           value_filter <- parsed@ptr
       }
 
+      cfg <- as.character(tiledb::config(self$tiledbsoma_ctx$context()))
       if (isFALSE(iterated)) {
-          cfg <- as.character(tiledb::config(self$tiledbsoma_ctx$context()))
-          rl <- soma_array_reader(uri = uri,
-                                  colnames = column_names,   # NULL dealt with by soma_array_reader()
-                                  qc = value_filter,         # idem
-                                  dim_points = coords,       # idem
-                                  loglevel = log_level,      # idem
-                                  config = cfg)
-          private$soma_reader_transform(rl)
+        rl <- soma_array_reader(uri = self$uri,
+                                config = cfg,
+                                colnames = column_names,   # NULL dealt with by sr_setup()
+                                qc = value_filter,         # idem
+                                dim_points = coords,
+                                loglevel = log_level
+                               )
+
+        soma_array_to_arrow_table(rl)
       } else {
-          ## should we error if this isn't null?
-          if (!is.null(private$soma_reader_pointer)) {
-              warning("Reader pointer not null, skipping")
-              rl <- NULL
-          } else {
-              private$soma_reader_setup()
-              rl <- list()
-              while (!self$read_complete()) {
-                  ## soma_reader_transform() applied inside read_next()
-                  rl <- c(rl, self$read_next())
-              }
-          }
-          invisible(rl)
+         read_iter <- TableReadIter$new(uri = self$uri,
+                           config = cfg,
+                           colnames = column_names,   # NULL dealt with by sr_setup()
+                           qc = value_filter,         # idem
+                           dim_points = coords,       # idem
+                           loglevel = log_level      # idem
+                           )
+        return(read_iter)
       }
     }
 
@@ -265,12 +262,7 @@ SOMADataFrame <- R6::R6Class(
       }
 
       schema
-    },
-
-    ## refined from base class
-    soma_reader_transform = function(x) {
-      arrow::as_arrow_table(arrow::RecordBatch$import_from_c(x[[1]], x[[2]]))
     }
-
+    
   )
 )