Conform spatialMap via a spatial-element registry + bridge

  Bump to 0.99.10. serialize a MultiAssaySpatialExperiment's spatialMap
  losslessly by monomorphizing its polymorphic (element_type, region,
  instance_id) reference through a conformed element-instance registry, so the
  observation-to-element association becomes real, single-target foreign keys
  instead of opaque string data.

  writeParquet (MultiAssaySpatialExperiment method):
  - Emit a `spatial_element_registry` resource enumerating every points/shapes
    instance across all layers, with an integer `__element__` spine and the
    object model's (element_type, region, instance_id) natural key.
  - Each spatial_points / spatial_shapes layer foreign-keys the `__element__`
    spine into the registry (the CTI subtype -> base link).
  - `spatial_map` becomes a monomorphic bridge with two single-target FKs: the
    element side (`__element__` -> spatial_element_registry) and the observation
    side ((assay, colname) -> sample_map, which reuses sample_map as the
    observation registry and encodes the spatialMap validity rule as a real
    composite FK). assay/element_type/region remain degenerate on the bridge.

  readParquet: `__element__` is a serialization-internal spine (excluded from
  .schema_datacols and dropped from the reconstructed spatialMap), so the layers,
  the spatialMap, and the query layer round-trip unchanged.

  Profile: add `spatial_element_registry` to the layout enum (+ its cross-check).

  Bug fix: a coord_array index column's category `label` was emitted as a
  one-element array rather than a string (an errant I() wrap; the value is always
  length 1), so any datapackage carrying an assay with dimnames -- e.g. a
  MultiAssaySpatialExperiment member -- failed validation against the bundled
  Frictionless profile. The label is now a string and such packages conform.

  Adds a drift-guard test asserting the registry/bridge FK contract, full profile
  conformance, and round-trip stripping. Mirrors a scibis read-contract update
  (kept at parity). Full test suite green.

Author: aboyounp-gne

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: BiocDuckDB
-Version: 0.99.9
-Date: 2026-07-27
+Version: 0.99.10
+Date: 2026-07-28
 Title: Bioconductor DuckDB Integration and High-Level I/O
 Description:
     Integration package providing high-level Parquet I/O functions and optimized

NEWS.md

@@ -1,3 +1,28 @@
+# BiocDuckDB 0.99.10
+
+## Enhancements
+
+- `writeParquet()` now serializes a `MultiAssaySpatialExperiment`'s `spatialMap`
+  as a monomorphic bridge over a conformed **element-instance registry**
+  (`spatial_element_registry`), so the observation-to-spatial-element association
+  becomes real, single-target foreign keys instead of an opaque polymorphic
+  reference. A new `spatial_element_registry` resource enumerates every
+  points/shapes instance across all layers with an integer `__element__` spine;
+  each typed spatial layer foreign-keys that spine; and `spatial_map` declares
+  two foreign keys -- the element side (`__element__` to `spatial_element_registry`)
+  and the observation side (`(assay, colname)` to `sample_map`, which encodes
+  the spatialMap validity rule as a real composite FK). The `__element__` spine
+  is a serialization-internal column: `readParquet()` reconstructs the
+  object-model `spatialMap` and the spatial layers without it, so the round-trip
+  is unchanged.
+
+## Bug fixes
+
+- `writeParquet()` emitted a `coord_array` index column's category `label` as a
+  one-element array rather than a string, so a datapackage carrying an assay with
+  dimnames failed validation against the bundled Frictionless profile. The label
+  is now a string, and such packages conform.
+
 # BiocDuckDB 0.99.9
 
 ## Enhancements

R/readParquet.R

@@ -224,6 +224,7 @@ function(path,
     keycol <- .schema_keycols(schema)
     pkey <- schema[["primaryKey"]]
     exclude <- c(keycol,
+                 "__element__",
                  if (!is.null(pkey) && !identical(pkey, keycol)) pkey,
                  .schema_partitions(schema),
                  unlist(schema[["genomicCoords"]]),
@@ -886,6 +887,12 @@ function(path,
         x <- .readParquetDataFrame(fullpath, resource = spatial_map_res,
                                    keycol = index, ...)
         spatial_map <- as.data.frame(x, optional = TRUE)
+        drop_cols <- intersect(c("__index__", "__element__"),
+                               colnames(spatial_map))
+        if (length(drop_cols)) {
+            spatial_map <- spatial_map[,
+                setdiff(colnames(spatial_map), drop_cols), drop = FALSE]
+        }
         spatial_map <- DataFrame(spatial_map, check.names = FALSE)
     }
 

R/writeParquet.R

@@ -587,7 +587,7 @@ function(x,
                                         lapply(seq_along(dimnames_x[[i]]),
                                                function(j) {
                                                    list(value = j,
-                                                        label = I(dimnames_x[[i]][[j]]))
+                                                        label = dimnames_x[[i]][[j]])
                                                }),
                                     categoriesOrdered = TRUE)
                            }
@@ -1834,6 +1834,70 @@ setMethod("writeParquet", "ShapesLayerList", function(x, path, ...)
     invisible(resources)
 })
 
+### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+### Spatial element-instance registry
+###
+
+# Enumerate every points/shapes instance across all layers into one conformed
+# registry, so spatialMap's polymorphic (element_type, region, instance_id)
+# reference monomorphizes to a single-target foreign key.
+#' @importFrom S4Vectors DataFrame
+.spatialElementRegistry <- function(pts, shps) {
+    parts <- list()
+    collect <- function(ll, etype) {
+        for (i in seq_along(ll)) {
+            iid <- ll[[i]][["instance_id"]]
+            if (!is.null(iid) && length(iid)) {
+                parts[[length(parts) + 1L]] <<- DataFrame(
+                    element_type = etype,
+                    region = names(ll)[i],
+                    instance_id = as.character(iid))
+            }
+        }
+    }
+    collect(pts, "points")
+    collect(shps, "shapes")
+    if (!length(parts))
+        return(NULL)
+    do.call(rbind, parts)
+}
+
+.spatialElementKey <- function(reg) {
+    keys <- paste(reg[["element_type"]], reg[["region"]],
+                  as.character(reg[["instance_id"]]), sep = "\r")
+    stats::setNames(seq_len(nrow(reg)), keys)
+}
+
+.elementRegistryRef <- function() {
+    list(list(fields = "__element__",
+              reference = list(fields = "__element__",
+                               resource = "spatial_element_registry")))
+}
+
+.writeSpatialLayersWithRegistry <-
+function(ll, etype, path, elem_key, ...)
+{
+    layout <- sprintf("spatial_%s", etype)
+    prefix <- sprintf("sample_%s_", etype)
+    ref <- if (is.null(elem_key)) NULL else .elementRegistryRef()
+    resources <- list()
+    for (i in seq_along(ll)) {
+        region <- names(ll)[i]
+        lyr <- ll[[i]]
+        if (!is.null(elem_key)) {
+            k <- paste(etype, region, as.character(lyr[["instance_id"]]),
+                       sep = "\r")
+            lyr[["__element__"]] <- as.integer(elem_key[k])
+        }
+        resources <- c(resources,
+                       writeParquet(lyr,
+                                    path = file.path(path, paste0(prefix, region)),
+                                    name = region, dimension = "sample",
+                                    layout = layout, refs = ref, ...))
+    }
+    resources
+}
+
 ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 ### MultiAssaySpatialExperiment objects
 ###
@@ -1850,17 +1914,33 @@ function(x,
                         resources = list()),
          ...)
 {
-    # Points
     pts <- MultiAssaySpatialExperiment::spatialPoints(x)
+    shps <- MultiAssaySpatialExperiment::spatialShapes(x)
+
+    # Element-instance registry
+    reg <- .spatialElementRegistry(pts, shps)
+    elem_key <- NULL
+    if (!is.null(reg)) {
+        elem_key <- .spatialElementKey(reg)
+        resources <- callGeneric(as.data.frame(reg, optional = TRUE),
+                                 path = file.path(path, "spatial_element_registry"),
+                                 indexcol = "__element__", keycol = NULL,
+                                 name = "spatial_element_registry", dimension = "sample",
+                                 layout = "spatial_element_registry", ...)
+        package[["resources"]] <- c(package[["resources"]], resources)
+    }
+
+    # Points
     if (length(pts) > 0L) {
-        resources <- callGeneric(pts, path = path, ...)
+        resources <- .writeSpatialLayersWithRegistry(pts, "points", path,
+                                                     elem_key, ...)
         package[["resources"]] <- c(package[["resources"]], resources)
     }
 
     # Shapes
-    shps <- MultiAssaySpatialExperiment::spatialShapes(x)
     if (length(shps) > 0L) {
-        resources <- callGeneric(shps, path = path, ...)
+        resources <- .writeSpatialLayersWithRegistry(shps, "shapes", path,
+                                                     elem_key, ...)
         package[["resources"]] <- c(package[["resources"]], resources)
     }
 
@@ -2003,11 +2083,23 @@ function(x,
         package[["resources"]] <- c(package[["resources"]], resources_img)
     }
 
-    # Spatial Map
+    # Spatial Map: a monomorphic bridge with two single-target FKs
     spatial_map <- MultiAssaySpatialExperiment::spatialMap(x)
     if (!is.null(spatial_map) && nrow(spatial_map) > 0L) {
+        sm_refs <- list()
+        if (!is.null(elem_key)) {
+            k <- paste(as.character(spatial_map[["element_type"]]),
+                       as.character(spatial_map[["region"]]),
+                       as.character(spatial_map[["instance_id"]]), sep = "\r")
+            spatial_map[["__element__"]] <- as.integer(elem_key[k])
+            sm_refs <- c(sm_refs, .elementRegistryRef())
+        }
+        sm_refs <- c(sm_refs, list(list(
+            fields = c("assay", "colname"),
+            reference = list(fields = c("assay", "colname"),
+                             resource = "sample_map"))))
         resources_sm <- callGeneric(spatial_map, path = file.path(path, "spatial_map"),
-                                    dimension = "unbound", ...)
+                                    dimension = "unbound", refs = sm_refs, ...)
         package[["resources"]] <- c(package[["resources"]], resources_sm)
     }
 

inst/schema/biocduckdb-profile.json

@@ -56,6 +56,7 @@
             "spatial_shapes",
             "spatial_raster_ref",
             "spatial_label_coord",
+            "spatial_element_registry",
             "nested_data_frame",
             "nested_experiment"
           ],

tests/testthat/test-datapackage-schema-enums.R

@@ -20,6 +20,7 @@
     "spatial_shapes",
     "spatial_raster_ref",
     "spatial_label_coord",
+    "spatial_element_registry",
     "nested_data_frame",
     "nested_experiment"
 )

tests/testthat/test-datapackage-schema.R

@@ -162,3 +162,73 @@ test_that("MultiAssayExperiment sample_map declares the primary -> subjects fore
 
     unlink(tmpdir, recursive = TRUE)
 })
+
+test_that("MASE conforms spatialMap via an spatial_element_registry + monomorphic bridge (ADR-067)", {
+    skip_if_not_installed("MultiAssaySpatialExperiment")
+    validator <- .profileValidator()
+    suppressPackageStartupMessages(library(MultiAssaySpatialExperiment))
+
+    mat <- matrix(rpois(20, 5), 5, 4,
+                  dimnames = list(paste0("G", 1:5), paste0("obs", 1:4)))
+    pts <- S4Vectors::DataFrame(x = 1:4, y = 1:4, instance_id = paste0("obs", 1:4))
+    mase <- MultiAssaySpatialExperiment(
+        experiments = ExperimentList(rna = mat),
+        colData = S4Vectors::DataFrame(tissue = c("core", "margin"),
+                                       row.names = c("specimen_A", "specimen_B")),
+        sampleMap = S4Vectors::DataFrame(
+            assay = factor(rep("rna", 4), "rna"),
+            primary = rep(c("specimen_A", "specimen_B"), each = 2),
+            colname = paste0("obs", 1:4)),
+        points = PointsLayerList(coords = pts),
+        spatialMap = S4Vectors::DataFrame(
+            assay = factor(rep("rna", 4), "rna"),
+            colname = paste0("obs", 1:4), element_type = "points",
+            region = "coords", instance_id = paste0("obs", 1:4)))
+
+    tmpdir <- tempfile()
+    writeParquet(mase, tmpdir)
+
+    # Conforms to the profile (new spatial_element_registry layout + composite FK).
+    expect_true(.validateDataPackage(validator, tmpdir))
+
+    dp <- jsonlite::fromJSON(file.path(tmpdir, "datapackage.json"),
+                             simplifyVector = FALSE)
+    get_res <- function(nm) Find(function(r) identical(r[["name"]], nm),
+                                 dp[["resources"]])
+    fk_map <- function(res) {
+        fks <- res[["schema"]][["foreignKeys"]]
+        stats::setNames(lapply(fks, function(k)
+            c(resource = k[["reference"]][["resource"]],
+              fields = paste(unlist(k[["reference"]][["fields"]]), collapse = "+"))),
+            vapply(fks, function(k) paste(unlist(k[["fields"]]), collapse = "+"), ""))
+    }
+
+    # The conformed registry dimension.
+    reg <- get_res("spatial_element_registry")
+    expect_false(is.null(reg))
+    expect_identical(reg[["layout"]], "spatial_element_registry")
+    expect_true(all(c("__element__", "element_type", "region", "instance_id") %in%
+                    vapply(reg[["schema"]][["fields"]], `[[`, "", "name")))
+
+    # The typed layer foreign-keys the registry's integer spine.
+    coords_fk <- fk_map(get_res("coords"))
+    expect_identical(coords_fk[["__element__"]][["resource"]], "spatial_element_registry")
+
+    # The bridge carries both single-target FKs.
+    sm_fk <- fk_map(get_res("spatial_map"))
+    expect_identical(sm_fk[["__element__"]][["resource"]], "spatial_element_registry")
+    expect_identical(sm_fk[["assay+colname"]][["resource"]], "sample_map")
+    expect_identical(sm_fk[["assay+colname"]][["fields"]], "assay+colname")
+
+    # Round-trip: the internal spine does not leak back into the object model.
+    m2 <- readParquet(tmpdir)
+    sm2 <- MultiAssaySpatialExperiment::spatialMap(m2)
+    expect_false(any(c("__element__", "__index__") %in% colnames(sm2)))
+    expect_true(all(c("assay", "colname", "element_type", "region",
+                      "instance_id") %in% colnames(sm2)))
+    layer2 <- as.data.frame(
+        MultiAssaySpatialExperiment::spatialPoints(m2)[["coords"]])
+    expect_false("__element__" %in% colnames(layer2))
+
+    unlink(tmpdir, recursive = TRUE)
+})