dimension name setters (#170)

Author: dblodgett-usgs

R/creation.R

@@ -27,7 +27,8 @@ init_array_metadata <- function(
     filters=NA,
     object_codec=NA,
     dimension_separator=NA,
-    zarr_format=2L
+    zarr_format=2L,
+    dimension_names=NULL
 ) {
     # Reference: https://github.com/zarr-developers/zarr-python/blob/5dd4a0e6cdc04c6413e14f57f61d389972ea937c/zarr/storage.py#L358
     if(is_na(compressor)) {
@@ -59,7 +60,11 @@ init_array_metadata <- function(
     # dtype = dtype.base
 
     shape <- normalize_shape(shape)
-    
+
+    if (!is.null(dimension_names) && length(dimension_names) != length(shape)) {
+        stop("DimensionNamesLengthError(length must match length(shape))")
+    }
+
     dtype_itemsize <- dtype$num_bytes
     chunks <- normalize_chunks(chunks, shape, dtype_itemsize)
     order <- normalize_order(order)
@@ -117,13 +122,17 @@ init_array_metadata <- function(
             compressor = compressor,
             fill_value = fill_value,
             order = order,
-            filters = filters
+            filters = filters,
+            dimension_names = dimension_names
         )
         key <- paste0(path_to_prefix(path), ZARR_JSON)
         meta3 <- Metadata3$new()
         encoded_meta <- meta3$encode_array_metadata(v3_meta)
         store$set_item(key, encoded_meta)
     } else {
+        if (!is.null(dimension_names)) {
+            stop("DimensionNamesV2Error(dimension_names is only supported for zarr_format = 3L)")
+        }
         zarray_meta <- create_zarray_meta(
             shape=shape,
             chunks=chunks,
@@ -250,7 +259,8 @@ init_array <- function(
     filters=NA,
     object_codec=NA,
     dimension_separator=NA,
-    zarr_format=2L
+    zarr_format=2L,
+    dimension_names=NULL
 ) {
     if(is_na(compressor)) {
         compressor <- "default"
@@ -279,7 +289,8 @@ init_array <- function(
         filters=filters,
         object_codec=object_codec,
         dimension_separator=dimension_separator,
-        zarr_format=zarr_format
+        zarr_format=zarr_format,
+        dimension_names=dimension_names
     )
 
 }
@@ -342,6 +353,10 @@ init_group <- function(
 #' @param zarr_format : int, optional
 #'     Zarr format version. Use \code{2L} (default) for Zarr V2 or \code{3L}
 #'     for Zarr V3.
+#' @param dimension_names : character vector, optional
+#'     Named dimensions for V3 arrays. Length must equal \code{length(shape)}.
+#'     V3 only -- passing a non-NULL value with \code{zarr_format = 2L} is an
+#'     error. Default \code{NULL}.
 #' @returns ZarrArray
 #' @export
 zarr_create <- function(
@@ -363,7 +378,8 @@ zarr_create <- function(
     object_codec=NA,
     dimension_separator=NA,
     write_empty_chunks=TRUE,
-    zarr_format=2L
+    zarr_format=2L,
+    dimension_names=NULL
 ) {
     # Reference: https://github.com/zarr-developers/zarr-python/blob/5dd4a0e6cdc04c6413e14f57f61d389972ea937c/zarr/creation.py#L18
     if(is_na(compressor)) {
@@ -383,7 +399,8 @@ zarr_create <- function(
     init_array(store, shape=shape, chunks=chunks, dtype=dtype, compressor=compressor,
                fill_value=fill_value, order=order, overwrite=overwrite, path=path,
                chunk_store=chunk_store, filters=filters, object_codec=object_codec,
-               dimension_separator=dimension_separator, zarr_format=zarr_format)
+               dimension_separator=dimension_separator, zarr_format=zarr_format,
+               dimension_names=dimension_names)
 
 
     # instantiate array

R/zarr-array.R

@@ -246,7 +246,14 @@ ZarrArray <- R6::R6Class("ZarrArray",
       # V3 encodes NaN/Infinity/-Infinity as JSON strings; decode back to numeric.
       private$fill_value <- decode_fill_value_v3(meta$fill_value)
 
-      private$dimension_names <- meta$dimension_names  # NULL if absent
+      # JSON arrays of strings come back as lists under simplifyVector=FALSE;
+      # coerce to a character vector so the public getter returns the type
+      # users expect. NULL stays NULL when the field is absent from zarr.json.
+      if (is.null(meta$dimension_names)) {
+        private$dimension_names <- NULL
+      } else {
+        private$dimension_names <- as.character(unlist(meta$dimension_names))
+      }
     },
     # method_description
     # Load or reload metadata from store.
@@ -1172,6 +1179,21 @@ ZarrArray <- R6::R6Class("ZarrArray",
       private$flush_metadata_nosync()
     },
     #' @description
+    #' Set dimension names of the array (V3 only).
+    #' @param names Character vector of length equal to the number of array
+    #'   dimensions, or `NULL` to clear.
+    #' @return `NULL` (called for side effects).
+    set_dimension_names = function(names) {
+      if (is.null(private$zarr_format) || private$zarr_format != 3L) {
+        stop("DimensionNamesV2Error(set_dimension_names is only supported for V3 arrays)")
+      }
+      if (!is.null(names) && length(names) != length(private$shape)) {
+        stop("DimensionNamesLengthError(length must match length(shape))")
+      }
+      private$dimension_names <- names
+      private$flush_metadata_nosync()
+    },
+    #' @description
     #' get the storage order metadata of an array.
     #' @return `character(1)`, `"C"` or `"F"`.
     get_order = function() {

man/ZarrArray.Rd

@@ -841,3 +841,66 @@ test_that("V3 vlen-utf8 string array loads correctly via load_metadata_v3_nosync
     skip("fixture not found")
   }
 })
+
+# --- dimension_names threading (PR 0B) ---
+
+test_that("V3 zarr_create with dimension_names round-trips on reopen", {
+  store <- MemoryStore$new()
+  z <- zarr_create(shape = c(2L, 3L), dtype = "<f8", zarr_format = 3L,
+                   compressor = NA, store = store,
+                   dimension_names = c("x", "y"))
+  expect_equal(z$get_dimension_names(), c("x", "y"))
+
+  # Re-open from store and confirm dimension_names persisted in zarr.json.
+  z2 <- ZarrArray$new(store)
+  expect_equal(z2$get_dimension_names(), c("x", "y"))
+})
+
+test_that("V3 set_dimension_names attaches names post-creation and round-trips", {
+  store <- MemoryStore$new()
+  z <- zarr_create(shape = c(2L, 3L), dtype = "<f8", zarr_format = 3L,
+                   compressor = NA, store = store)
+  expect_null(z$get_dimension_names())
+
+  z$set_dimension_names(c("a", "b"))
+  expect_equal(z$get_dimension_names(), c("a", "b"))
+
+  z2 <- ZarrArray$new(store)
+  expect_equal(z2$get_dimension_names(), c("a", "b"))
+})
+
+test_that("set_dimension_names errors on V2 arrays", {
+  store <- MemoryStore$new()
+  z <- zarr_create(shape = c(2L, 3L), dtype = "<f8", zarr_format = 2L,
+                   compressor = NA, store = store)
+  expect_error(z$set_dimension_names(c("x", "y")), "DimensionNamesV2Error")
+})
+
+test_that("zarr_create errors when dimension_names length != length(shape)", {
+  store <- MemoryStore$new()
+  expect_error(
+    zarr_create(shape = c(4L, 5L), dtype = "<f8", zarr_format = 3L,
+                compressor = NA, store = store,
+                dimension_names = c("x")),
+    "DimensionNamesLengthError"
+  )
+})
+
+test_that("zarr_create errors when dimension_names is passed with zarr_format = 2L", {
+  store <- MemoryStore$new()
+  expect_error(
+    zarr_create(shape = c(4L, 5L), dtype = "<f8", zarr_format = 2L,
+                compressor = NA, store = store,
+                dimension_names = c("x", "y")),
+    "DimensionNamesV2Error"
+  )
+})
+
+test_that("V3 group create_dataset threads dimension_names through ...", {
+  store <- MemoryStore$new()
+  g <- zarr_create_group(store = store, zarr_format = 3L)
+  a <- g$create_dataset("data", shape = c(2L, 3L, 4L), dtype = "<f8",
+                        compressor = NA,
+                        dimension_names = c("x", "y", "t"))
+  expect_equal(a$get_dimension_names(), c("x", "y", "t"))
+})