[r] Add functions for setting/getting global context (#4364)

* Add functions to set/get global default context

* Update NEWS, docs, and version number

* Add export to function

* Update NEWS

* Fix typo in check

* Update get_context_default and docs

* Fix typo

* Add `replace` option to context and format file

* Update docs and comment out deprecation test

* Apply suggested documentation improvements

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

* Update documentation

* Apply suggestions from code review

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

* Update documentation

---------

Co-authored-by: Aaron Wolen <[email protected]>
(cherry picked from commit 671a49f)

Author: jp-dark

apis/r/NAMESPACE

@@ -88,9 +88,11 @@ export(SparseReadIter)
 export(TableReadIter)
 export(TileDBCreateOptions)
 export(extract_dataset)
+export(get_default_context)
 export(list_datasets)
 export(load_dataset)
 export(matrixZeroBasedView)
+export(set_default_context)
 export(set_log_level)
 export(show_package_versions)
 export(soma_context)

apis/r/NEWS.md

@@ -1,5 +1,10 @@
 # tiledbsoma 2.3.0
 
+## Added
+
+- A new `SOMAContext` method was added that replaces `SOMATileDBContext`. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
+- New methods `set_default_context` and `get_default_context` for setting and getting the `SOMAContext`. ([#4364](https://github.com/single-cell-data/TileDB-SOMA/pull/4364))
+
 ## Deprecated
 
 - The function `soma_context` is deprecated. Use class `SOMAContext` instead. ([#4355](https://github.com/single-cell-data/TileDB-SOMA/pull/4355))
@@ -8,7 +13,6 @@
 
 ## 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

apis/r/R/Factory.R

@@ -30,7 +30,10 @@
 #' @param platform_config Optional platform configuration.
 #' @param tiledbsoma_ctx Optional (DEPRECATED) SOMATileDBContext.
 #' @param tiledb_timestamp Optional Datetime (POSIXct) for TileDB timestamp.
-#' @param context Optional TileDB SOMA context.
+#' @param context Optional \code{SOMAContext} object used for TileDB operations.
+#' If a context is not provided, then the default context will be used. Call
+#' \code{set_default_context} once before other SOMA operations to configure
+#' the default context.
 #'
 #' @return A new \link[tiledbsoma:SOMADataFrame]{SOMA data frame} stored at
 #' \code{uri} opened for writing.

apis/r/R/SOMAContext.R

@@ -33,7 +33,6 @@ SOMAContext <- R6::R6Class(
     get_data_protocol = function(uri) {
       return(get_data_protocol_from_soma_context(private$.handle, uri))
     }
-
   ),
   active = list(
     #' @field handle External pointer to the C++ interface
@@ -44,11 +43,73 @@ SOMAContext <- R6::R6Class(
       }
       return(private$.handle)
     }
-
   ),
   private = list(
     # @field Internal 'external pointer' for C++ interface ...
     #
     .handle = NULL
   )
 )
+
+#' Set the Default Global Context
+#'
+#' Configure a default \code{\link{SOMAContext}} to be used by all TileDB-SOMA
+#' operations when no explicit context is provided.
+#'
+#' This function should be called once at the beginning of your session before
+#' opening any SOMA objects if you want to customize the TileDB context
+#' parameters that will apply to all subsequent operations. Otherwise, a default
+#' context will be created automatically with standard parameters when you first
+#' open a SOMA object.
+#'
+#' If the global context was already set, an error will be raised unless
+#' \code{replace=True}. Setting a new default context will not change the
+#' context for TileDB-SOMA objects that were already created.
+#'
+#' @template param-config
+#' @param replace Allow replacing the existing default context with new
+#' configuration parameters.
+#'
+#' @return Invisibly, the default default context object.
+#'
+#' @export
+#'
+set_default_context <- function(config = NULL, replace = FALSE) {
+  if (!replace && !is.null(.pkgenv[["somactx"]])) {
+    stop(
+      "A default context was already created. To replace the default context for new objects call again with `replace=True`.",
+      call. = FALSE
+    )
+  }
+  context <- SOMAContext$new(config)
+  .pkgenv[["somactx"]] <- context
+  invisible(context)
+}
+
+#' Get the Default SOMA Context
+#' 
+#' Retrieve the current default \code{\link{SOMAContext}} used by TileDB-SOMA
+#' operations.
+#'
+#' This function returns the context that was either:
+#' \itemize{
+#'   \item Explicitly set via \code{\link{set_default_context}}, or
+#'   \item Automatically created when a SOMA object was first created
+#' }
+#'
+#' An error is raised if no default context is set.
+#'
+#' @return The context that will be used for TileDB-SOMA API when no context is provided by the user.
+#'
+#' @export
+#'
+get_default_context <- function() {
+  context <- .pkgenv[["somactx"]]
+  if (is.null(context)) {
+    stop(
+      "No default context is set. Call `set_default_context()` to initialize the context.",
+      call. = FALSE
+    )
+  }
+  return(context)
+}

apis/r/R/SOMAObject.R

@@ -22,8 +22,10 @@ SOMAObject <- R6::R6Class(
     #' @param tiledbsoma_ctx Optional (DEPRECATED) TileDB SOMA context
     #' @param tiledb_timestamp Optional timestamp (\code{\link[base]{POSIXct}})
     #' to open the object at
-    #' @param context A \code{SOMAContext} object. Required internally but
-    #' automatically provided by factory functions.
+    #' @param context Optional \code{SOMAContext} object used for TileDB operations.
+    #' If a context is not provided, then the default context will be used. Call
+    #' \code{set_default_context} once before other SOMA operations to configure
+    #' the default context.
     initialize = function(
       uri,
       ...,

apis/r/R/datasets.R

@@ -74,7 +74,10 @@ extract_dataset <- function(name, dir = tempdir()) {
 #'
 #' @param tiledbsoma_ctx Optional (DEPRECATED) TileDB \dQuote{Context} object
 #' that defaults to \code{NULL}.
-#' @param context Optional SOMA context object that defaults to \code{NULL}.
+#' @param context Optional \code{SOMAContext} object used for TileDB operations.
+#' If a context is not provided, then the default context will be used. Call
+#' \code{set_default_context} once before other SOMA operations to configure
+#' the default context.
 #'
 #' @return \code{load_dataset()}: returns a SOMA object.
 #'

apis/r/R/soma_array_reader.R

@@ -17,7 +17,10 @@
 #' @param result_order Character value with the desired result order, defaults to \sQuote{auto}
 #' @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.
-#' @param context Optional instance of a SOMA Context object
+#' @param context Optional \code{SOMAContext} object used for TileDB operations.
+#' If a context is not provided, then the default context will be used. Call
+#' \code{set_default_context} once before other SOMA operations to configure
+#' the default context.
 #' @return A List object with two pointers to Arrow array data and schema is returned
 #' @examples
 #' \dontrun{

apis/r/R/utils.R

@@ -72,10 +72,9 @@ get_soma_context <- function(context, tiledbsoma_ctx, what = NULL) {
     if (is.null(tiledbsoma_ctx)) {
         context <- .pkgenv[["somactx"]]
         if (is.null(context)) {
-            return(SOMAContext$new())
-        } else {
-            return(context)
+          return(set_default_context())
         }
+        return(context)
     }
     if (!inherits(x = tiledbsoma_ctx, what = 'SOMATileDBContext')) {
       stop(

apis/r/R/write_soma.R

@@ -10,7 +10,10 @@
 #' @param platform_config Optional \link[tiledbsoma:PlatformConfig]{platform
 #' configuration}.
 #' @param tiledbsoma_ctx Optional (DEPRECATED) \code{\link{SOMATileDBContext}}.
-#' @param context Optional \code{\link{SOMAContext}}.
+#' @param context Optional \code{SOMAContext} object used for TileDB operations.
+#' If a context is not provided, then the default context will be used. Call
+#' \code{set_default_context} once before other SOMA operations to configure
+#' the default context.
 #'
 #' @return The URI to the resulting \code{\link{SOMAExperiment}} generated from
 #' the data contained in \code{x}.