Mark three return preference arguments to tiledb_array as deprecated (#…

…567)

* Mark three return preference arguments to tiledb_array as deprecated

* Convert four uses of as.data.frame to return_as="data.frame"

* Update tests accordingly

* Update vignettes accordingly

* Update examples accordingly

* Update notebook accordingly

* Update NEWS [ci skip]

NEWS.md

@@ -35,6 +35,10 @@
 
 * Compilation on Linux systems as old as Ubuntu 18.04 without a `filesystem` header is now possible (#556)
 
+## Deprecations
+
+* The boolean arguments `as.data.frame`, `as.matrix` and `as.array` to the `tiledb_array()` accessor are deprecated in favor of the more general `return_as="..."` form. (#567)
+
 ## Removals
 
 * The `timestamp` argument to `tiledb_array`, deprecated in favor of `timestamp_end` (and `timestamp_start`) in July 2021, has been removed (#566).

R/DataFrame.R

@@ -76,7 +76,7 @@
 ##' ## turn factor into character
 ##' irisdf <- within(iris, Species <- as.character(Species))
 ##' fromDataFrame(irisdf, uri)
-##' arr <- tiledb_array(uri, as.data.frame=TRUE, sparse=FALSE)
+##' arr <- tiledb_array(uri, return_as="data.frame", sparse=FALSE)
 ##' newdf <- arr[]
 ##' all.equal(iris, newdf)
 ##' }
@@ -265,7 +265,7 @@ fromDataFrame <- function(obj, uri, col_index=NULL, sparse=TRUE, allows_dups=spa
   if (dir.exists(uri)) unlink(uri, recursive=TRUE)
   fromDataFrame(obj, uri)
 
-  df <- tiledb_array(uri, as.data.frame=TRUE)
+  df <- tiledb_array(uri, return_as="data.frame")
   df[]
 }
 
@@ -292,7 +292,7 @@ fromDataFrame <- function(obj, uri, col_index=NULL, sparse=TRUE, allows_dups=spa
   }
   fromDataFrame(bkdf, uri)
 
-  arr <- tiledb_array(uri, as.data.frame = TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   newdf <- arr[]
   invisible(newdf)
 }
@@ -305,7 +305,7 @@ fromDataFrame <- function(obj, uri, col_index=NULL, sparse=TRUE, allows_dups=spa
   fromDataFrame(df, uri)
   cat("Data written\n")
 
-  arr <- tiledb_array(uri, as.data.frame = TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   newdf <- arr[]
   invisible(newdf)
 }

R/SparseMatrix.R

@@ -112,7 +112,7 @@ fromSparseMatrix <- function(obj,
 toSparseMatrix <- function(uri) {
     stopifnot(`Argument 'uri' must be character` = is.character(uri))
 
-    arr <- tiledb_array(uri, as.data.frame=TRUE, query_layout="UNORDERED")
+    arr <- tiledb_array(uri, return_as="data.frame", query_layout="UNORDERED")
     obj <- arr[]
 
     dimnm <- list(NULL, NULL)        # by default no dimnames

R/TileDBArray.R

@@ -182,6 +182,11 @@ tiledb_array <- function(uri,
     array_xptr <- libtiledb_array_open(ctx@ptr, uri, query_type)
   }
 
+  ## Deprecated July 2023, to removed by July 2024 or later
+  if (as.data.frame) .Deprecated(old="as.data.frame", new=r"(return_as="data.frame")")
+  if (as.matrix) .Deprecated(old="as.matrix", new=r"(return_as="matrix")")
+  if (as.array) .Deprecated(old="as.array", new=r"(return_as="array")")
+
   if (length(timestamp_start) > 0) {
       libtiledb_array_set_open_timestamp_start(array_xptr, timestamp_start)
   }

inst/examples/deletes.R

@@ -78,7 +78,7 @@ delete_rows <- function(uri) {
 
 read_array <- function(uri) {
     # Open the array and read as a data.frame from it.
-    A <- tiledb_array(uri, as.data.frame=TRUE)
+    A <- tiledb_array(uri, return_as="data.frame")
     # Slice rows 1 and 2, and cols 2, 3 and 4
     # A[1:2, 2:4]
     A[]

inst/examples/deprecating/ex_1.R

@@ -47,7 +47,7 @@ read_array <- function(uri) {
 }
 
 read_as_df <- function(uri) {
-  A <- tiledb_dense(uri = uri, as.data.frame = TRUE)
+  A <- tiledb_dense(uri = uri, return_as = "data.frame")
   data <- A[3:7, 2:4]
   show(data)
 }
@@ -77,7 +77,7 @@ open_read_change_read <- function(uri) {
 }
 
 simple_ex <- function(uri) {
-  arr <- tiledb_dense(uri, as.data.frame = TRUE)
+  arr <- tiledb_dense(uri, return_as = "data.frame")
   show(arr[7:9, 2:3])
 }
 

inst/examples/deprecating/quickstart_sparse.R

@@ -69,7 +69,7 @@ write_array <- function(array_name) {
 
 read_array <- function(array_name) {
     # Open the array and read as a data.frame from it.
-    A <- tiledb_sparse(uri = array_name, as.data.frame=TRUE)
+    A <- tiledb_sparse(uri = array_name, return_as="data.frame")
     # Slice rows 1 and 2, and cols 2, 3 and 4
     A[1:2, 2:4]
 }

inst/examples/ex_1.R

@@ -47,7 +47,7 @@ read_array <- function(uri) {
 }
 
 read_as_df <- function(uri) {
-  A <- tiledb_array(uri = uri, as.data.frame = TRUE)
+  A <- tiledb_array(uri = uri, return_as = "data.frame")
   data <- A[3:7, 2:4]
   show(data)
 }
@@ -77,7 +77,7 @@ open_read_change_read <- function(uri) {
 }
 
 simple_ex <- function(uri) {
-  arr <- tiledb_array(uri, as.data.frame = TRUE)
+  arr <- tiledb_array(uri, return_as = "data.frame")
   show(arr[7:9, 2:3])
 }
 

inst/examples/ex_2.R

@@ -53,7 +53,7 @@ read_array <- function(uri) {
 }
 
 read_as_df <- function(uri) {
-  A <- tiledb_array(uri = uri, as.data.frame = TRUE)
+  A <- tiledb_array(uri = uri, return_as = "data.frame")
   selected_ranges(A) <- list(cbind(ISOdatetime(2020,1,1,0,0,4),
                                    ISOdatetime(2020,1,1,0,0,6)),
                              cbind(1L,1L))

inst/examples/ex_3.R

@@ -95,7 +95,7 @@ write_array <- function(uri) {
                    DATETIME_MS = as.POSIXct("2020-01-01 00:00:00") + 0:9 + 0.123,
                    DATETIME_US = as.POSIXct("2020-01-01 00:00:00") + 0:9 + 0.123456)
 
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, as="data.frame")
   arr[] <- data.frame(rows = rows,
                       a1 = a1data,
                       d1 = d1data)
@@ -158,7 +158,7 @@ read_array_query <- function(uri) {
 }
 
 read_array <- function(uri) {
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   ## constraint on 1st dim: value from 4 to 7
   selected_ranges(arr) <- list(cbind(as.integer64(4), as.integer64(7)))
   ## fetch data

inst/examples/ex_TileDB-Cloud.R

@@ -10,5 +10,5 @@ ctx <- tiledb_ctx(config)
 
 array_name <- "tiledb://TileDB-Inc/quickstart_sparse"
 
-arr <- tiledb_array(array_name, query_type="READ", as.data.frame=TRUE)
+arr <- tiledb_array(array_name, return_as="data.frame")
 show(arr[])

inst/examples/ex_aggdatetimes.R

@@ -34,7 +34,7 @@ attrib <- c(tiledb_attr("year",  type = "DATETIME_YEAR"),  # year
 schema <- tiledb_array_schema(domain, attrib, sparse=TRUE)
 res <- tiledb_array_create(uri, schema)
 
-arr <- tiledb_array(uri, as.data.frame=TRUE)
+arr <- tiledb_array(uri, return_as="data.frame")
 
 dvec <- 1:3
 data <- data.frame(row = dvec,
@@ -57,7 +57,7 @@ cat("writing ... ")
 arr[] <- data
 
 cat("reading ... ")
-arr2 <- tiledb_array(uri, as.data.frame=TRUE)
+arr2 <- tiledb_array(uri, return_as="data.frame")
 readdata <- arr2[]
 
 cat("checking ... ")

inst/examples/ex_dimdatetimes.R

@@ -59,7 +59,7 @@ for (dtype in dimtypes) {
     tiledb_array_create(uri, schema)
 
 
-    arr <- tiledb_array(uri, as.data.frame=TRUE)
+    arr <- tiledb_array(uri, as="data.frame")
 
     dvec <- switch(dtype,
                    "DATETIME_YEAR"  = c(as.Date("2020-01-01"), as.Date("2021-01-01"), as.Date("2022-01-01")),
@@ -83,7 +83,7 @@ for (dtype in dimtypes) {
     arr[] <- data
 
     cat("reading ... ")
-    arr2 <- tiledb_array(uri, as.data.frame=TRUE)
+    arr2 <- tiledb_array(uri, return_as="data.frame")
     readdata <- arr2[]
 
     cat("(",format(readdata[1,1]), ",", format(readdata[2,1]), ",", format(readdata[3,1]), ") ", sep="")

inst/examples/ex_dimensions.R

@@ -87,7 +87,7 @@ for (dtype in dimtypes) {
     tiledb_array_create(uri, schema)
 
 
-    arr <- tiledb_array(uri, as.data.frame=TRUE)
+    arr <- tiledb_array(uri, return_as="data.frame")
 
     dvec <- switch(dtype,
                    "ASCII"   = LETTERS[1:3],
@@ -124,7 +124,7 @@ for (dtype in dimtypes) {
     arr[] <- data
 
     cat("reading ... ")
-    arr2 <- tiledb_array(uri, as.data.frame=TRUE)
+    arr2 <- tiledb_array(uri, return_as="data.frame")
     readdata <- arr2[]
     cat("(",format(readdata[1,1]), ",", format(readdata[2,1]), ",", format(readdata[3,1]), ") ", sep="")
 

inst/examples/ex_metadata.R

@@ -12,7 +12,7 @@ if (!dir.exists(uri)) {                 # if that example does not exist, create
   sch <- tiledb_array_schema(dom, c(a1, a2), sparse=TRUE)
   tiledb_array_create(uri, sch)
 
-  arr <- tiledb_array(uri, as.data.frame=FALSE)
+  arr <- tiledb_array(uri, return_as="asis")
 }
 
 ## old initial accessors

inst/examples/ex_metadata_2.R

@@ -17,7 +17,7 @@ setup <- function(tmp, verbose=FALSE) {
   a2  <- tiledb_attr("a2", type = "INT32")
   sch <- tiledb_array_schema(dom, c(a1, a2), sparse=TRUE)
   tiledb_array_create(tmp, sch)
-  arr <- tiledb_array(tmp, as.data.frame=FALSE)
+  arr <- tiledb_array(tmp, return_as="asis")
 
   #arrW <- tiledb:::libtiledb_array_open(arr@ptr, tmp, "WRITE")
   #tiledb:::put_metadata(arrW, "vec", c(1.1, 2.2, 3.3))
@@ -120,7 +120,6 @@ setup <- function(tmp, verbose=FALSE) {
 tmp <- "/tmp/fooarray" #tempfile()
 if (dir.exists(tmp)) unlink(tmp, recursive=TRUE)
 arr <- setup(tmp, TRUE)
-# arr <- tiledb_array(tmp, as.data.frame=FALSE)
 
 arr <- tiledb_array(tmp)
 arr <- .tiledb_array_open(arr, "READ")

inst/examples/filters.R

@@ -52,9 +52,9 @@ write_array <- function(uri) {
 }
 
 read_array <- function(uri) {
-  ## opening in data.frame mode; could also open with as.data.frame=FALSE
+  ## opening in data.frame mode
   ## returning three vectors
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   dat <- arr[]
   print(dat)
 }

inst/examples/quickstart_sparse.R

@@ -69,7 +69,7 @@ write_array <- function(array_name) {
 
 read_array <- function(array_name) {
     # Open the array and read as a data.frame from it.
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE)
+    A <- tiledb_array(uri = array_name, return_as="data.frame")
     # Slice rows 1 and 2, and cols 2, 3 and 4
     A[1:2, 2:4]
 }

inst/examples/quickstart_sparse_async.R

@@ -69,7 +69,7 @@ write_array <- function(array_name) {
 
 read_array <- function(array_name) {
     # Open the array and read as a data.frame from it.
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE)
+    A <- tiledb_array(uri = array_name, return_as="data.frame")
     # Slice rows 1 and 2, and cols 2, 3 and 4
     A[1:2, 2:4]
 }

inst/examples/quickstart_sparse_encrypted.R

@@ -70,7 +70,7 @@ write_array <- function(array_name) {
 
 read_array <- function(array_name) {
     # Open the array and read as a data.frame from it.
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE, encryption_key = encryption_key)
+    A <- tiledb_array(uri = array_name, return_as="data.frame", encryption_key = encryption_key)
     # Slice rows 1 and 2, and cols 2, 3 and 4
     A[1:2, 2:4]
 }

inst/examples/quickstart_sparse_heter.R

@@ -43,9 +43,9 @@ write_array <- function(uri) {
 }
 
 read_array <- function(uri) {
-  ## opening in data.frame mode; could also open with as.data.frame=FALSE
+  ## opening in data.frame mode
   ## returning three vectors
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   dat <- arr[]
   print(dat)
 }

inst/examples/quickstart_sparse_string.R

@@ -44,9 +44,9 @@ write_array <- function(uri) {
 }
 
 read_array <- function(uri) {
-  ## opening in data.frame mode; could also open with as.data.frame=FALSE
+  ## opening in data.frame mode
   ## returning three vectors
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   dat <- arr[]
   print(dat)
 }

inst/examples/quickstart_sparse_timetravel.R

@@ -84,26 +84,26 @@ write_array <- function(array_name) {
 read_array <- function(array_name) {
     cat("\nReading everything:\n")
     # Open the array and read as a data.frame from it.
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE)
+    A <- tiledb_array(uri = array_name, as="data.frame")
     A[]
 }
 
 read_array_at <- function(array_name, tstamps) {
     ## Read before tstamp[1]
     cat("\nOpening / reading 0.5s before first tstamp\n")
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE, timestamp=tstamps[1] - 0.5)
+    A <- tiledb_array(uri = array_name, as="data.frame", timestamp=tstamps[1] - 0.5)
     print(A[])
 
     cat("Opening / reading 0.5s after first tstamp\n")
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE, timestamp=tstamps[1] + 0.5)
+    A <- tiledb_array(uri = array_name, as="data.frame", timestamp=tstamps[1] + 0.5)
     print(A[])
 
     cat("Opening / reading 0.5s before second tstamp\n")
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE, timestamp=tstamps[2] - 0.5)
+    A <- tiledb_array(uri = array_name, as="data.frame", timestamp=tstamps[2] - 0.5)
     print(A[])
 
     cat("Opening / reading 0.5s after second tstamp\n")
-    A <- tiledb_array(uri = array_name, as.data.frame=TRUE, timestamp=tstamps[2] + 0.5)
+    A <- tiledb_array(uri = array_name, return_as="data.frame", timestamp=tstamps[2] + 0.5)
     print(A[])
 
 }

inst/examples/writing_dense_sparse.R

@@ -40,9 +40,9 @@ write_array <- function(uri) {
 }
 
 read_array <- function(uri) {
-  ## opening in data.frame mode; could also open with as.data.frame=FALSE
+  ## opening in data.frame mode
   ## returning three vectors
-  arr <- tiledb_array(uri, as.data.frame=TRUE)
+  arr <- tiledb_array(uri, return_as="data.frame")
   dat <- arr[]
   print(dat)
 }