[r] Add and use new SOMAContext object (#4355) (#4358)

* Remove unused private tiledb_ctx member

* Remove tests for functions that do not act standalone

* Rename createSOMAContext and move to soma_context.cpp

* Create and use new SOMAContext R6 class

* Add methods to SOMAContext

* Update block_size to use new context

* More clean-up

* Update documentation

* Testing and fixes

- Fix setting default parameter in contexts
- Add tests for SOMAContext using both new and deprecated API

* Add soma_context to more places and update tests

* Update news

* Update docs

* Deprecate SOMATileDBContext and check in tests

* Update apis/r/R/SOMAObject.R



* Apply suggestions from code review



* Update apis/r/R/Factory.R



* Update apis/r/R/Factory.R



---------


(cherry picked from commit e7629a2)

Co-authored-by: Aaron Wolen <[email protected]>

Author: jp-dark

apis/r/NAMESPACE

@@ -58,6 +58,7 @@ export(SOMACollection)
 export(SOMACollectionBase)
 export(SOMACollectionCreate)
 export(SOMACollectionOpen)
+export(SOMAContext)
 export(SOMAContextBase)
 export(SOMADataFrame)
 export(SOMADataFrameCreate)

apis/r/NEWS.md

@@ -1,3 +1,16 @@
+# tiledbsoma 2.3.0
+
+## Deprecated
+
+- The function `soma_context` is deprecated. Use class `SOMAContext` instead. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+- The parameter `tiledbsoma_ctx` is deprecated in all functions/methods that use it. Use the parameter `soma_context` instead. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+- `SOMATileDBContext` is deprecated. Use class `SOMAContext` instead. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+
+## Fixed
+
+- The SOMA Context is only cached as an environment variable when the function `soma_context` is called directly. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+- `SOMATileDBContext` no longer replaces `sm.mem.reader.sparse_global_order.ratio_array_data` when set in the input config. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+
 # tiledbsoma 2.2.0
 
 ## Changed

apis/r/R/Factory.R

@@ -28,10 +28,9 @@
 #'   if it already exists, simply open it for writing.
 #' }
 #' @param platform_config Optional platform configuration.
-#' @param tiledbsoma_ctx Optional SOMATileDBContext.
+#' @param tiledbsoma_ctx Optional (DEPRECATED) SOMATileDBContext.
 #' @param tiledb_timestamp Optional Datetime (POSIXct) for TileDB timestamp.
-#' @param soma_context A SOMA context as created by
-#' \code{\link{soma_context}()}.
+#' @param soma_context Optional TileDB SOMA context.
 #'
 #' @return A new \link[tiledbsoma:SOMADataFrame]{SOMA data frame} stored at
 #' \code{uri} opened for writing.
@@ -68,10 +67,12 @@ SOMADataFrameCreate <- function(
   soma_context = NULL
 ) {
   ingest_mode <- match.arg(ingest_mode)
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMADataFrameCreate(tiledbsoma_ctx)")
   sdf <- SOMADataFrame$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
+    soma_context = soma_context,
     tiledb_timestamp = tiledb_timestamp
   )
   ingest_mode <- switch(
@@ -123,10 +124,12 @@ SOMADataFrameOpen <- function(
     uri,
     tiledb_timestamp %||% "now"
   ))
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMADataFrameOpen(tiledbsoma_ctx)")
   sdf <- SOMADataFrame$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
+    soma_context = soma_context,
     tiledb_timestamp = tiledb_timestamp
   )
   sdf$open(mode)
@@ -172,13 +175,16 @@ SOMASparseNDArrayCreate <- function(
   ingest_mode = c("write", "resume"),
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
   ingest_mode <- match.arg(ingest_mode)
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMASparseNDArrayCreate(tiledbsoma_ctx)")
   snda <- SOMASparseNDArray$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
+    soma_context = soma_context,
     tiledb_timestamp = tiledb_timestamp
   )
   ingest_mode <- switch(
@@ -214,13 +220,16 @@ SOMASparseNDArrayOpen <- function(
   mode = "READ",
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMASparseNDArrayOpen(tiledbsoma_ctx)")
   snda <- SOMASparseNDArray$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   snda$open(mode)
   return(snda)
@@ -260,17 +269,20 @@ SOMADenseNDArrayCreate <- function(
   shape,
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
   soma_debug(sprintf(
     "[SOMADenseNDArrayCreate] tstamp (%s)",
     tiledb_timestamp %||% "now"
   ))
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMADenseNDArrayCreate(tiledbsoma_ctx)")
   dnda <- SOMADenseNDArray$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   dnda$create(type, shape, platform_config = platform_config)
   return(dnda)
@@ -296,13 +308,16 @@ SOMADenseNDArrayOpen <- function(
   mode = "READ",
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMADenseNDArrayOpen(tiledbsoma_ctx)")
   dnda <- SOMADenseNDArray$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   dnda$open(mode)
   return(dnda)
@@ -340,14 +355,17 @@ SOMACollectionCreate <- function(
   ingest_mode = c("write", "resume"),
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
   ingest_mode <- match.arg(ingest_mode)
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMACollectionCreate(tiledbsoma_ctx)")
   coll <- SOMACollection$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   ingest_mode <- switch(
     EXPR = ingest_mode,
@@ -384,13 +402,16 @@ SOMACollectionOpen <- function(
   mode = "READ",
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMACollectionOpen(tiledbsoma_ctx)")
   coll <- SOMACollection$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   coll$open(mode)
   return(coll)
@@ -440,14 +461,17 @@ SOMAMeasurementCreate <- function(
   ingest_mode = c("write", "resume"),
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
   ingest_mode <- match.arg(ingest_mode)
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMAMeasurementCreate(tiledbsoma_ctx)")
   meas <- SOMAMeasurement$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   ingest_mode <- switch(
     EXPR = ingest_mode,
@@ -482,13 +506,16 @@ SOMAMeasurementOpen <- function(
   mode = "READ",
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMAMeasurementOpen(tiledbsoma_ctx)")
   meas <- SOMAMeasurement$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   meas$open(mode)
   return(meas)
@@ -538,14 +565,17 @@ SOMAExperimentCreate <- function(
   ingest_mode = c("write", "resume"),
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
   ingest_mode <- match.arg(ingest_mode)
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMAExperimentCreate(tiledbsoma_ctx)")
   exp <- SOMAExperiment$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   ingest_mode <- switch(
     EXPR = ingest_mode,
@@ -579,13 +609,16 @@ SOMAExperimentOpen <- function(
   mode = "READ",
   platform_config = NULL,
   tiledbsoma_ctx = NULL,
-  tiledb_timestamp = NULL
+  tiledb_timestamp = NULL,
+  soma_context = NULL
 ) {
+  soma_context <- get_soma_context(soma_context, tiledbsoma_ctx, what="SOMAExperimentOpen(tiledbsoma_ctx)")
   exp <- SOMAExperiment$new(
     uri,
     platform_config = platform_config,
     tiledbsoma_ctx = tiledbsoma_ctx,
-    tiledb_timestamp = tiledb_timestamp
+    tiledb_timestamp = tiledb_timestamp,
+    soma_context = soma_context
   )
   exp$open(mode)
   return(exp)

apis/r/R/RcppExports.R

@@ -1,10 +1,6 @@
 # Generated by using Rcpp::compileAttributes() -> do not edit by hand
 # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 
-createSOMAContext <- function(config = NULL) {
-    .Call(`_tiledbsoma_createSOMAContext`, config)
-}
-
 createSchemaFromArrow <- function(uri, nasp, nadimap, nadimsp, sparse, datatype, pclst, ctxxp, tsvec = NULL) {
     invisible(.Call(`_tiledbsoma_createSchemaFromArrow`, uri, nasp, nadimap, nadimsp, sparse, datatype, pclst, ctxxp, tsvec))
 }
@@ -386,3 +382,15 @@ get_tiledb_object_type <- function(uri, ctxxp) {
     .Call(`_tiledbsoma_get_tiledb_object_type`, uri, ctxxp)
 }
 
+create_soma_context <- function(config = NULL) {
+    .Call(`_tiledbsoma_create_soma_context`, config)
+}
+
+get_config_from_soma_context <- function(soma_context) {
+    .Call(`_tiledbsoma_get_config_from_soma_context`, soma_context)
+}
+
+get_data_protocol_from_soma_context <- function(soma_context, uri) {
+    .Call(`_tiledbsoma_get_data_protocol_from_soma_context`, soma_context, uri)
+}
+

apis/r/R/SOMAArrayBase.R

@@ -95,21 +95,21 @@ SOMAArrayBase <- R6::R6Class(
     #' @return \code{TRUE} if the underlying TileDB array allows duplicates;
     #' otherwise \code{FALSE}.
     #'
-    allows_duplicates = \() c_allows_dups(self$uri, private$.soma_context),
+    allows_duplicates = \() c_allows_dups(self$uri, private$.soma_context$handle),
 
     #' @description Is an array sparse?
     #'
     #' @return \code{TRUE} if the underlying TileDB array is sparse;
     #' otherwise \code{FALSE}.
     #'
-    is_sparse = \() c_is_sparse(self$uri, private$.soma_context),
+    is_sparse = \() c_is_sparse(self$uri, private$.soma_context$handle),
 
     #' @description Retrieve the array schema as an Arrow schema
     #' (lifecycle: maturing).
     #'
     #' @return An Arrow \code{\link[arrow:Schema]{Schema}} object.
     #'
-    schema = \() arrow::as_schema(c_schema(self$uri, private$.soma_context)),
+    schema = \() arrow::as_schema(c_schema(self$uri, private$.soma_context$handle)),
 
     #' @description Retrieve the array attributes.
     #'
@@ -133,13 +133,13 @@ SOMAArrayBase <- R6::R6Class(
     #'   }
     #' }
     #'
-    attributes = \() c_attributes(self$uri, private$.soma_context),
+    attributes = \() c_attributes(self$uri, private$.soma_context$handle),
 
     #' @description Retrieve attribute names (lifecycle: maturing).
     #'
     #' @return A character vector with the array's attribute names.
     #'
-    attrnames = \() c_attrnames(self$uri, private$.soma_context),
+    attrnames = \() c_attrnames(self$uri, private$.soma_context$handle),
 
     #' @description Retrieve the array dimensions (lifecycle: maturing)
     #'
@@ -164,13 +164,13 @@ SOMAArrayBase <- R6::R6Class(
     #'   }
     #' }
     #'
-    dimensions = \() c_domain(self$uri, private$.soma_context),
+    dimensions = \() c_domain(self$uri, private$.soma_context$handle),
 
     #' @description Retrieve dimension names (lifecycle: maturing).
     #'
     #' @return A character vector with the array's dimension names.
     #'
-    dimnames = \() c_dimnames(self$uri, private$.soma_context),
+    dimnames = \() c_dimnames(self$uri, private$.soma_context$handle),
 
     #' @description Retrieve the names of all columns, including dimensions and
     #' attributes (lifecycle: maturing).
@@ -195,7 +195,7 @@ SOMAArrayBase <- R6::R6Class(
     #' @return A named vector of dimension length and of the same type as
     #' the dimension.
     #'
-    shape = \() bit64::as.integer64(shape(self$uri, private$.soma_context)),
+    shape = \() bit64::as.integer64(shape(self$uri, private$.soma_context$handle)),
 
     #' @description Retrieve the hard limit up to which the array may be resized
     #' using the \code{$resize()} method (lifecycle: maturing).
@@ -204,7 +204,7 @@ SOMAArrayBase <- R6::R6Class(
     #' the dimension.
     #'
     maxshape = \() {
-      bit64::as.integer64(maxshape(self$uri, private$.soma_context))
+      bit64::as.integer64(maxshape(self$uri, private$.soma_context$handle))
     },
 
     #' @description Returns a named list of minimum/maximum pairs, one per index
@@ -222,7 +222,7 @@ SOMAArrayBase <- R6::R6Class(
       retval <- as.list(
         arrow::as_record_batch(
           arrow::as_arrow_table(
-            non_empty_domain(self$uri, private$.soma_context)
+            non_empty_domain(self$uri, private$.soma_context$handle)
           )
         )
       )
@@ -240,7 +240,7 @@ SOMAArrayBase <- R6::R6Class(
     #'
     #' @return A scalar with the number of dimensions.
     #'
-    ndim = \() ndim(self$uri, private$.soma_context),
+    ndim = \() ndim(self$uri, private$.soma_context$handle),
 
     #' @description Print-friendly representation of the object.
     #'