[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]>

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

@@ -3,6 +3,8 @@
 ## Added
 
 - Use a global memory budget for read operations instead of a per column memory budget. The global memory budget allocates splits the budget per column depending on the type and characteristics of each column. Global memory budget is disabled by default under a feature flag and can be enabled by setting `soma.read.use_memory_pool`. ([#4299](https://github.com/single-cell-data/TileDB-SOMA/pull/4299))
+- 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))
 
 ## Changed
 

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}.