[r] Docs and NAMESPACE cleanup (#1566)

* Mark transformer functions as internal * Add noRd to transformer functions * Mark base R6 classes as internal * Mark low-level package version functions internal * Unexport low-level sr_* functions * Unexport shape and nnz These are both available as methods on the appropriate R6 classes * Document which package versions are retrieved * Add noRd to internal version retrieval functions * Refine stats docs * README typo * Stop exporting soma_array_reader() * Stop exporting pad_matrix() * Bump version and update docs
single-cell-data · Aug 2, 2023 · 3d4a5ad · 3d4a5ad
1 parent 5729480
commit 3d4a5ad
Show file tree

Hide file tree

Showing 47 changed files with 150 additions and 449 deletions.
diff --git a/apis/r/DESCRIPTION b/apis/r/DESCRIPTION
@@ -4,7 +4,7 @@ Title: TileDB SOMA
 Description: Interface for working with 'TileDB'-based Stack of Matrices,
     Annotated ('SOMA'): an open data model for representing annotated matrices,
     like those commonly used for single cell data analysis.
-Version: 0.99.2
+Version: 0.99.3
 Authors@R: c(
     person(given = "Aaron",
            family = "Wolen",

diff --git a/apis/r/NAMESPACE b/apis/r/NAMESPACE
@@ -5,8 +5,6 @@ S3method("[[<-",MappingBase)
 S3method(as.list,MappingBase)
 S3method(length,MappingBase)
 S3method(names,MappingBase)
-S3method(pad_matrix,default)
-S3method(pad_matrix,matrix)
 S3method(write_soma,Assay)
 S3method(write_soma,DimReduc)
 S3method(write_soma,Graph)
@@ -17,13 +15,17 @@ S3method(write_soma,data.frame)
 S3method(write_soma,matrix)
 export(ConfigList)
 export(EphemeralCollection)
+export(EphemeralCollectionBase)
 export(EphemeralExperiment)
 export(EphemeralMeasurement)
 export(MappingBase)
 export(PlatformConfig)
+export(ReadIter)
+export(SOMAAxisIndexer)
 export(SOMAAxisQuery)
 export(SOMAAxisQueryResult)
 export(SOMACollection)
+export(SOMACollectionBase)
 export(SOMACollectionCreate)
 export(SOMACollectionOpen)
 export(SOMAContextBase)
@@ -58,14 +60,7 @@ export(extract_dataset)
 export(list_datasets)
 export(load_dataset)
 export(matrixZeroBasedView)
-export(nnz)
-export(pad_matrix)
-export(shape)
 export(show_package_versions)
-export(soma_array_reader)
-export(sr_complete)
-export(sr_next)
-export(sr_setup)
 export(tiledbsoma_stats_disable)
 export(tiledbsoma_stats_dump)
 export(tiledbsoma_stats_enable)

diff --git a/apis/r/R/MappingBase.R b/apis/r/R/MappingBase.R
@@ -5,11 +5,8 @@
 #' getting (\code{self$get()}) and setting (\code{self$set()}) items in the map
 #'
 #' @keywords internal
-#'
 #' @export
-#'
-#' @noMd
-#'
+
 MappingBase <- R6::R6Class(
   classname = 'MappingBase',
   lock_class = TRUE,

diff --git a/apis/r/R/RcppExports.R b/apis/r/R/RcppExports.R
@@ -16,8 +16,6 @@ get_column_types <- function(uri, colnames) {
     .Call(`_tiledbsoma_get_column_types`, uri, colnames)
 }
 
-#' @rdname soma_array_reader
-#' @export
 nnz <- function(uri, config = NULL) {
     .Call(`_tiledbsoma_nnz`, uri, config)
 }
@@ -32,8 +30,6 @@ check_arrow_array_tag <- function(xp) {
     .Call(`_tiledbsoma_check_arrow_array_tag`, xp)
 }
 
-#' @rdname soma_array_reader
-#' @export
 shape <- function(uri, config = NULL) {
     .Call(`_tiledbsoma_shape`, uri, config)
 }
@@ -82,63 +78,65 @@ shape <- function(uri, config = NULL) {
 #' }
 #' summary(rl)
 #' }
-#' @export
+#' @noRd
 sr_setup <- function(uri, config, colnames = NULL, qc = NULL, dim_points = NULL, dim_ranges = NULL, batch_size = "auto", result_order = "auto", timestamp_end = NULL, loglevel = "auto") {
     .Call(`_tiledbsoma_sr_setup`, uri, config, colnames, qc, dim_points, dim_ranges, batch_size, result_order, timestamp_end, loglevel)
 }
 
-#' @rdname sr_setup
-#' @export
 sr_complete <- function(sr) {
     .Call(`_tiledbsoma_sr_complete`, sr)
 }
 
-#' @rdname sr_setup
-#' @export
 sr_next <- function(sr) {
     .Call(`_tiledbsoma_sr_next`, sr)
 }
 
-#' TileDB Statistics interface
+#' TileDB SOMA statistics
+#'
+#' These functions expose the TileDB Core functionality for performance measurements
+#' and statistics.
 #'
-#' The functions `tiledbsoma_stats_enable`, `tiledbsoma_stats_disable`, `tiledbsoma_stats_reset`
-#' and `tiledbsoma_stats_dump` expose the TileDB Core functionality for performance measurements
-#' and statistics.  The first three just turn on, off or reset, the fourth returns a JSON string.
-#' For convenience the function `tiledbsoma_stats_show` displays the information on the console.
+#' - `tiledbsoma_stats_enable()`/`tiledbsoma_stats_disable()`: Enable and disable TileDB's internal statistics.
+#' - `tiledbsoma_stats_reset()`: Reset all statistics to 0.
+#' - `tiledbsoma_stats_dump()`: Dump all statistics to a JSON string.
+#' - `tiledbsoma_stats_show()`: Print all statistics to the console.
 #'
+#' @name tiledbsoma_stats
 #' @export
 tiledbsoma_stats_enable <- function() {
     invisible(.Call(`_tiledbsoma_tiledbsoma_stats_enable`))
 }
 
-#' @rdname tiledbsoma_stats_enable
+#' @rdname tiledbsoma_stats
 #' @export
 tiledbsoma_stats_disable <- function() {
     invisible(.Call(`_tiledbsoma_tiledbsoma_stats_disable`))
 }
 
-#' @rdname tiledbsoma_stats_enable
+#' @rdname tiledbsoma_stats
 #' @export
 tiledbsoma_stats_reset <- function() {
     invisible(.Call(`_tiledbsoma_tiledbsoma_stats_reset`))
 }
 
-#' @rdname tiledbsoma_stats_enable
+#' @rdname tiledbsoma_stats
 #' @export
 tiledbsoma_stats_dump <- function() {
     .Call(`_tiledbsoma_tiledbsoma_stats_dump`)
 }
 
-#' libtiledbsoma version information
+#' libtiledbsoma version
 #'
 #' Returns a string with version information for libtiledbsoma and the linked TileDB Embedded library.
+#' @noRd
 libtiledbsoma_version <- function() {
     .Call(`_tiledbsoma_libtiledbsoma_version`)
 }
 
-#' TileDB Embedded Version interface
+#' TileDB embedded version
 #'
-#' This gets the version of the TileDB Embedded library that is currently in use.
+#' Gets the version of the TileDB Embedded library that is currently in use.
+#' @noRd
 tiledb_embedded_version <- function() {
     .Call(`_tiledbsoma_tiledb_embedded_version`)
 }

diff --git a/apis/r/R/ReadIter.R b/apis/r/R/ReadIter.R
@@ -1,12 +1,14 @@
 #' SOMA Read Iterator Base class
 #'
 #' Class that allows for read iteration of SOMA reads.
+#' @keywords internal
+#' @export
 
 ReadIter <- R6::R6Class(
   classname = "ReadIter",
 
   public = list(
-                
+
     #' @description Create (lifecycle: experimental)
     #' @param sr soma read pointer
     initialize = function(sr) {
@@ -39,7 +41,7 @@ ReadIter <- R6::R6Class(
           }
       }
     },
-    
+
     #' @description  Concatenate remainder of iterator
     # to be refined in derived classes
     concat = function() {

diff --git a/apis/r/R/SOMAArrayBase.R b/apis/r/R/SOMAArrayBase.R
@@ -1,6 +1,8 @@
 #' SOMA Array Base Class
 #'
-#' Adds SOMA-specific functionality to the [`TileDBArray`] class.  (lifecycle: experimental)
+#' Adds SOMA-specific functionality to the [`TileDBArray`] class.  (lifecycle:
+#' experimental)
+#' @keywords internal
 
 SOMAArrayBase <- R6::R6Class(
   classname = "SOMAArrayBase",

diff --git a/apis/r/R/SOMAAxisIndexer.R b/apis/r/R/SOMAAxisIndexer.R
@@ -5,6 +5,7 @@
 #' result. Coordinates outside of the query result will return
 #' [`arrow::null()`].
 #' @keywords internal
+#' @export
 SOMAAxisIndexer <- R6::R6Class("SOMAAxisIndexer",
   public = list(
 

diff --git a/apis/r/R/SOMACollectionBase.R b/apis/r/R/SOMACollectionBase.R
@@ -2,6 +2,9 @@
 #'
 #' @description Base class for objects containing persistent collection of SOMA
 #' objects, mapping string keys to any SOMA object.  (lifecycle: experimental)
+#' @keywords internal
+#' @export
+
 SOMACollectionBase <- R6::R6Class(
   classname = "SOMACollectionBase",
   inherit = TileDBGroup,

diff --git a/apis/r/R/SOMAContextBase.R b/apis/r/R/SOMAContextBase.R
@@ -5,11 +5,8 @@
 #' context options
 #'
 #' @keywords internal
-#'
 #' @export
-#'
-#' @noMd
-#'
+
 SOMAContextBase <- R6::R6Class(
   classname = 'SOMAContextBase',
   inherit = ScalarMap,

diff --git a/apis/r/R/SOMANDArrayBase.R b/apis/r/R/SOMANDArrayBase.R
@@ -4,6 +4,7 @@
 #' Adds NDArray-specific functionality to the [`SOMAArrayBase`] class.
 #' (lifecycle: experimental)
 #'
+#' @keywords internal
 #' @export
 #' @importFrom bit64 as.integer64
 

diff --git a/apis/r/R/SOMASparseNDArrayRead.R b/apis/r/R/SOMASparseNDArrayRead.R
@@ -2,6 +2,7 @@
 #'
 #' @description
 #' Intermediate type to choose result format when reading a sparse array
+#' @keywords internal
 #' @export
 
 SOMASparseNDArrayRead <- R6::R6Class(

diff --git a/apis/r/R/SOMATileDBContext.R b/apis/r/R/SOMATileDBContext.R
@@ -3,9 +3,7 @@
 #' Context map for TileDB-backed SOMA objects
 #'
 #' @export
-#'
-#' @noMd
-#'
+
 SOMATileDBContext <- R6::R6Class(
   classname = 'SOMATileDBContext',
   inherit = SOMAContextBase,

diff --git a/apis/r/R/ScalarMap.R b/apis/r/R/ScalarMap.R
@@ -2,12 +2,11 @@
 #'
 #' An R6 mapping type that is limited to scalar atomic vector types only; can
 #' optionally be limited further to a specific atomic vector type
-#' (eg. \dQuote{\code{logical}})
+#' (eg. \dQuote{\code{logical}}).
 #'
+#' @keywords internal
 #' @export
-#'
-#' @noMd
-#'
+
 ScalarMap <- R6::R6Class(
   classname = 'ScalarMap',
   inherit = MappingBase,

diff --git a/apis/r/R/TileDBArray.R b/apis/r/R/TileDBArray.R
@@ -3,6 +3,7 @@
 #' @description Base class for representing an individual TileDB array.
 #' (lifecycle: experimental)
 #'
+#' @keywords internal
 #' @export
 TileDBArray <- R6::R6Class(
   classname = "TileDBArray",

diff --git a/apis/r/R/TileDBGroup.R b/apis/r/R/TileDBGroup.R
@@ -3,6 +3,7 @@
 #' @description
 #' Base class for interacting with TileDB groups (lifecycle: experimental)
 #' @importFrom spdl info debug
+#' @keywords internal
 #' @export
 TileDBGroup <- R6::R6Class(
   classname = "TileDBGroup",

diff --git a/apis/r/R/ephemeral.R b/apis/r/R/ephemeral.R
@@ -3,8 +3,9 @@
 #' @description \Sexpr[results=rd]{tiledbsoma:::rd_ephemeral_cls("collection", TRUE)}
 #'
 #' @keywords internal
+#' @export
 #' @importFrom data.table address
-#'
+
 EphemeralCollectionBase <- R6::R6Class(
   classname = 'EphemeralCollectionBase',
   inherit = SOMACollectionBase,

diff --git a/apis/r/R/pad_matrix.R b/apis/r/R/pad_matrix.R
@@ -8,10 +8,7 @@
 #'
 #' @return A matrix containing the data of \code{x} padded out to \code{shape}
 #'
-#' @keywords internal
-#'
-#' @export
-#'
+#' @noRd
 pad_matrix <- function(x, ...) {
   UseMethod(generic = 'pad_matrix', object = x)
 }
@@ -25,12 +22,8 @@ pad_matrix <- function(x, ...) {
 #' row/column names
 #'
 #' @importFrom Matrix sparseMatrix
-#'
-#' @noRd
-#'
 #' @method pad_matrix default
-#' @export
-#'
+#' @noRd
 pad_matrix.default <- function(x, rownames = NULL, colnames = NULL, ...) {
   stopifnot(
     inherits(x, "Matrix"),
@@ -75,10 +68,9 @@ pad_matrix.default <- function(x, rownames = NULL, colnames = NULL, ...) {
 
 #' @param sparse Return a \link[Matrix:TsparseMatrix-class]{sparse matrix}
 #' @rdname pad_matrix
-#'
 #' @method pad_matrix matrix
-#' @export
-#'
+#' @noRd
+
 pad_matrix.matrix <- function(x, rowidx, colidx, shape, sparse = FALSE, ...) {
   stopifnot(
     rlang::is_integerish(shape, n = 2L, finite = TRUE) && all(shape > 0L),

diff --git a/apis/r/R/soma_array_reader.R b/apis/r/R/soma_array_reader.R
@@ -25,7 +25,7 @@
 #' z <- soma_array_reader(uri)
 #' arrow::RecordBatch$import_from_c(z$array_data, z$schema)
 #' }
-#' @export
+#' @noRd
 soma_array_reader <- function(uri, colnames = NULL, qc = NULL, dim_points = NULL, dim_ranges = NULL,
                               batch_size = "auto", result_order = "auto", loglevel = "auto",
                               config = NULL) {