From 3e2995041c9f184b732d7cc05300f5153d77f284 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Mon, 12 Jan 2026 16:52:33 +0100
Subject: [PATCH 1/7] update read basilisk

---
 R/read.R | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/R/read.R b/R/read.R
index 929fd14..45ab2a6 100644
--- a/R/read.R
+++ b/R/read.R
@@ -128,25 +128,30 @@ readShape <- function(x, ...) {
 #' @importFrom SingleCellExperiment int_metadata
 #' @importFrom basilisk basiliskStart basiliskStop basiliskRun
 .readTables_basilisk <- function(x) {
-    proc <- basiliskStart(.env)
-    on.exit(basiliskStop(proc))
-    basiliskRun(proc, x=x, \(x) {
-        # read in 'SpatialData' from .zarr store
-        sd <- import("spatialdata")
-        zs <- sd$read_zarr(x)
-        # return (named) list of SCEs
-        names(ts) <- ts <- names(zs$tables$data)
-        lapply(ts, \(z) {
-            se <- AnnData2SCE(zs$tables[z])
-            nm <- "spatialdata_attrs"
-            md <- metadata(se)[[nm]]
-            int_metadata(se)[[nm]] <- md
-            metadata(se)[[nm]] <- NULL
-            se
-        }) 
-    })
+  proc <- basiliskStart(.env)
+  on.exit(basiliskStop(proc))
+  basiliskRun(proc, x=x, \(x) {
+    # read in 'SpatialData' from .zarr store
+    # sd <- import("spatialdata")
+    sd <- import("anndata")
+    z <- import("zarr")
+    # zs <- sd$read_zarr(x)
+    # return (named) list of SCEs
+    # names(ts) <- ts <- names(zs$tables$data)
+    names(ts) <- ts <- list.dirs(file.path(x,"tables/"), 
+                                 recursive = FALSE, 
+                                 full.names = FALSE)
+    lapply(ts, \(z) {
+      zs <- sd$read_zarr(file.path(x, "tables", ts))
+      se <- AnnData2SCE(zs)
+      nm <- "spatialdata_attrs"
+      md <- metadata(se)[[nm]]
+      int_metadata(se)[[nm]] <- md
+      metadata(se)[[nm]] <- NULL
+      se
+    }) 
+  })
 }
-
 .readTable_anndataR <- function(x) {
     if (!requireNamespace('anndataR', quietly=TRUE)) {
         stop("To use this function, install the 'anndataR' package via\n",

From af96e7f90c1940ea97659c79f26c300f721f89c7 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:31:16 +0100
Subject: [PATCH 2/7] fix indent

---
 R/read.R | 46 +++++++++++++++++++++++-----------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/R/read.R b/R/read.R
index 45ab2a6..dce2ec0 100644
--- a/R/read.R
+++ b/R/read.R
@@ -128,29 +128,29 @@ readShape <- function(x, ...) {
 #' @importFrom SingleCellExperiment int_metadata
 #' @importFrom basilisk basiliskStart basiliskStop basiliskRun
 .readTables_basilisk <- function(x) {
-  proc <- basiliskStart(.env)
-  on.exit(basiliskStop(proc))
-  basiliskRun(proc, x=x, \(x) {
-    # read in 'SpatialData' from .zarr store
-    # sd <- import("spatialdata")
-    sd <- import("anndata")
-    z <- import("zarr")
-    # zs <- sd$read_zarr(x)
-    # return (named) list of SCEs
-    # names(ts) <- ts <- names(zs$tables$data)
-    names(ts) <- ts <- list.dirs(file.path(x,"tables/"), 
-                                 recursive = FALSE, 
-                                 full.names = FALSE)
-    lapply(ts, \(z) {
-      zs <- sd$read_zarr(file.path(x, "tables", ts))
-      se <- AnnData2SCE(zs)
-      nm <- "spatialdata_attrs"
-      md <- metadata(se)[[nm]]
-      int_metadata(se)[[nm]] <- md
-      metadata(se)[[nm]] <- NULL
-      se
-    }) 
-  })
+    proc <- basiliskStart(.env)
+    on.exit(basiliskStop(proc))
+    basiliskRun(proc, x=x, \(x) {
+      # read in 'SpatialData' from .zarr store
+      # sd <- import("spatialdata")
+      sd <- import("anndata")
+      z <- import("zarr")
+      # zs <- sd$read_zarr(x)
+      # return (named) list of SCEs
+      # names(ts) <- ts <- names(zs$tables$data)
+      names(ts) <- ts <- list.dirs(file.path(x,"tables/"), 
+                                   recursive = FALSE, 
+                                   full.names = FALSE)
+      lapply(ts, \(z) {
+        zs <- sd$read_zarr(file.path(x, "tables", ts))
+        se <- AnnData2SCE(zs)
+        nm <- "spatialdata_attrs"
+        md <- metadata(se)[[nm]]
+        int_metadata(se)[[nm]] <- md
+        metadata(se)[[nm]] <- NULL
+        se
+      }) 
+    })
 }
 .readTable_anndataR <- function(x) {
     if (!requireNamespace('anndataR', quietly=TRUE)) {

From 2a2d892217257b81a990fb18209130281073f8d8 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:48:44 +0100
Subject: [PATCH 3/7] fix lapply bug in readBasilisk

---
 .Rbuildignore | 2 ++
 .gitignore    | 2 ++
 R/read.R      | 8 ++------
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.Rbuildignore b/.Rbuildignore
index 824fa78..c5b2efa 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -4,3 +4,5 @@
 vignettes/*html
 vignettes/*cache
 vignettes/*files
+^doc$
+^Meta$
diff --git a/.gitignore b/.gitignore
index 7ac4af5..ad437a8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@ inst/extdata/xenium1.zarr
 inst/extdata/visiumhd.zarr
 *.Rproj
 *.html
+/doc/
+/Meta/
diff --git a/R/read.R b/R/read.R
index dce2ec0..bead6e4 100644
--- a/R/read.R
+++ b/R/read.R
@@ -132,17 +132,13 @@ readShape <- function(x, ...) {
     on.exit(basiliskStop(proc))
     basiliskRun(proc, x=x, \(x) {
       # read in 'SpatialData' from .zarr store
-      # sd <- import("spatialdata")
       sd <- import("anndata")
-      z <- import("zarr")
-      # zs <- sd$read_zarr(x)
-      # return (named) list of SCEs
-      # names(ts) <- ts <- names(zs$tables$data)
+      za <- import("zarr")
       names(ts) <- ts <- list.dirs(file.path(x,"tables/"), 
                                    recursive = FALSE, 
                                    full.names = FALSE)
       lapply(ts, \(z) {
-        zs <- sd$read_zarr(file.path(x, "tables", ts))
+        zs <- sd$read_zarr(file.path(x, "tables", z))
         se <- AnnData2SCE(zs)
         nm <- "spatialdata_attrs"
         md <- metadata(se)[[nm]]

From fcea8955cf5244db1e03a8d8d0e726596da13573 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:51:01 +0100
Subject: [PATCH 4/7] fix comments

---
 R/read.R | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/R/read.R b/R/read.R
index bead6e4..0ae40ec 100644
--- a/R/read.R
+++ b/R/read.R
@@ -131,9 +131,10 @@ readShape <- function(x, ...) {
     proc <- basiliskStart(.env)
     on.exit(basiliskStop(proc))
     basiliskRun(proc, x=x, \(x) {
-      # read in 'SpatialData' from .zarr store
+      # read in 'AnnData' tables from .zarr store
       sd <- import("anndata")
       za <- import("zarr")
+      # return (named) list of SCEs
       names(ts) <- ts <- list.dirs(file.path(x,"tables/"), 
                                    recursive = FALSE, 
                                    full.names = FALSE)

From 5faf495daccfa79dc09cb9031b98a65e56f79201 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:52:09 +0100
Subject: [PATCH 5/7] more redundant fixes

---
 .Rbuildignore       |   4 +-
 .gitignore          |   4 +-
 Meta/vignette.rds   | Bin 0 -> 197 bytes
 doc/SpatialData.R   |  70 ++++++++++++++++++++
 doc/SpatialData.Rmd | 157 ++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 229 insertions(+), 6 deletions(-)
 create mode 100644 Meta/vignette.rds
 create mode 100644 doc/SpatialData.R
 create mode 100644 doc/SpatialData.Rmd

diff --git a/.Rbuildignore b/.Rbuildignore
index c5b2efa..448e34d 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -3,6 +3,4 @@
 ^\.github$
 vignettes/*html
 vignettes/*cache
-vignettes/*files
-^doc$
-^Meta$
+vignettes/*files
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index ad437a8..af4f780 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,4 @@ inst/extdata/mibitof.zarr
 inst/extdata/xenium1.zarr
 inst/extdata/visiumhd.zarr
 *.Rproj
-*.html
-/doc/
-/Meta/
+*.html
\ No newline at end of file
diff --git a/Meta/vignette.rds b/Meta/vignette.rds
new file mode 100644
index 0000000000000000000000000000000000000000..1e01f0673518e3f5073ec7d2250b80f92491e5de
GIT binary patch
literal 197
zcmV;$06PC4iwFP!000001B>8dU|?WkU||K4%s?iyFpyvaVgVp#WME<71k(J$1&Jk@
zi8(HbC5d`LxhZJU+(^=BQUb_2GfHxE(ByehOa{6^7%T}<1OzNhNQznW5_40F(M(`>
zNi9gtO92W0!>*t4KbjT}@6^ij{34hh6g6y6H7stKIjJyvLo!R?9OeKQHz<=a2;B`B
z=A*cuvnan@59SA6P`Eb$iT^-=?$P9&#A0-ha;1R6D6I&nALMQT2}<jAxd8wG4jE66

literal 0
HcmV?d00001

diff --git a/doc/SpatialData.R b/doc/SpatialData.R
new file mode 100644
index 0000000..282417a
--- /dev/null
+++ b/doc/SpatialData.R
@@ -0,0 +1,70 @@
+## ----setup, include=FALSE-----------------------------------------------------
+knitr::opts_chunk$set(cache=FALSE, message=FALSE, warning=FALSE)
+
+## ----load-libs----------------------------------------------------------------
+library(SpatialData)
+library(SingleCellExperiment)
+
+## ----blobs-read---------------------------------------------------------------
+x <- file.path("extdata", "blobs.zarr")
+x <- system.file(x, package="SpatialData")
+(x <- readSpatialData(x, anndataR=FALSE))  # VJC Dec 8, test effect of absence of anndataR
+
+## ----get, results="hide"------------------------------------------------------
+shapeNames(x) # there are two images
+shapes(x) # this is a list of them
+shape(x, i=1) # this is the 1st one
+shape(x, "blobs_polygons") # this is the 3nd one
+x$shapes$blobs_circles # list-like handling also works
+
+## ----data/meta----------------------------------------------------------------
+data(shape(x))
+meta(shape(x)) 
+
+## ----tbl----------------------------------------------------------------------
+# retrieve 'table' for an element
+(t <- getTable(x, i <- "blobs_labels"))
+head(colData(t))
+meta(t)
+# get values from an element's 'table'
+valTable(x, i, "channel_0_sum")
+# add an artificial 'table' to an element
+i <- "blobs_points"
+# ...passing a preconstructed 'data.frame'
+id <- unique(point(x)$instance_id)
+df <- data.frame(n=runif(length(id)))
+y <- setTable(x, i, df)
+head(colData(getTable(y, i)))
+# ...using a list of data generating functions
+f <- list(
+    numbers=\(n) runif(n),
+    letters=\(n) sample(letters, n, TRUE))
+args <- c(list(x, i), f)
+y <- do.call(setTable, args)
+head(colData(getTable(y, i)))
+
+## ----cs-methods---------------------------------------------------------------
+z <- meta(label(x))
+axes(z)
+CTdata(z)
+CTname(rmvCT(z, "scale"))
+CTname(addCT(z, 
+    name="D'Artagnan", 
+    type="scale", 
+    data=c(19, 94)))
+
+## ----cs-graph-----------------------------------------------------------------
+(g <- CTgraph(x))
+plotCoordGraph(g)
+
+## ----cs-path, results="hold"--------------------------------------------------
+# the following are equivalent
+i <- "blobs_labels"
+j <- "sequence"
+y <- label(x, i)
+CTpath(x, i, j)
+invisible(CTpath(y, j))
+
+## ----sessionInfo, echo=FALSE--------------------------------------------------
+sessionInfo()
+
diff --git a/doc/SpatialData.Rmd b/doc/SpatialData.Rmd
new file mode 100644
index 0000000..956096f
--- /dev/null
+++ b/doc/SpatialData.Rmd
@@ -0,0 +1,157 @@
+---
+title: "`SpatialData`"
+date: "`r format(Sys.Date(), '%B %d, %Y')`"
+package: "`r BiocStyle::pkg_ver('SpatialData')`"
+author: 
+  - name: Helena Lucia Crowell
+  - name: Louise Deconinck
+  - name: Artür Manukyan
+  - name: Dario Righelli
+  - name: Estella Dong
+  - name: Vince Carey
+output:
+  BiocStyle::html_document
+vignette: |
+  %\VignetteIndexEntry{SpatialData}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(cache=FALSE, message=FALSE, warning=FALSE)
+```
+
+```{r load-libs}
+library(SpatialData)
+library(SingleCellExperiment)
+```
+
+# Introduction
+
+The `SpatialData` package contains a set of reader and plotting functions for 
+spatial omics data stored as [SpatialData](https://spatialdata.scverse.org/en/latest/index.html) 
+`.zarr` files that follow [OME-NGFF specs](https://ngff.openmicroscopy.org/latest/#image-layout).
+
+Each `SpatialData` object is composed of five layers: images, labels, shapes, 
+points, and tables. Each layer may contain an arbitrary number of elements.
+
+Images and labels are represented as `ZarrArray`s (`r BiocStyle::Biocpkg("Rarr")`). 
+Points and shapes are represented as `r BiocStyle::CRANpkg("arrow")` objects linked 
+to an on-disk *.parquet* file. As such, all data are represented out of memory.
+
+Element annotation as well as cross-layer summarizations (e.g., count matrices)
+are represented as `r BiocStyle::Biocpkg("SingleCellExperiment")` as tables.
+
+## Handling
+
+For demonstration, we read in a toy dataset that is available through the package:
+
+```{r blobs-read}
+x <- file.path("extdata", "blobs.zarr")
+x <- system.file(x, package="SpatialData")
+(x <- readSpatialData(x, anndataR=FALSE))  # VJC Dec 8, test effect of absence of anndataR
+```
+
+`SpatialData` object behave like a list, thereby supporting flexible accession, 
+e.g., via `$` and `[[`, using character or integer indices etc. Specifically,
+
+- `image/label/shape/point/table()` retrieve one element
+- `images/labels/shapes/points/tables()` retrieve one layer
+- `image/label/shape/point/tableNames()` retrieve element names
+
+Let's demonstrate these capabilities using the image layer:
+
+```{r get, results="hide"}
+shapeNames(x) # there are two images
+shapes(x) # this is a list of them
+shape(x, i=1) # this is the 1st one
+shape(x, "blobs_polygons") # this is the 3nd one
+x$shapes$blobs_circles # list-like handling also works
+```
+
+Each element is made up of two key components: 
+
+- `data`: the actual array or table (for images/labels and shapes/points, respectively)
+- `meta`: list of metadata retrieved from an OME-NGFF compliant *.zattrs* (stored as `Zattrs`)
+
+```{r data/meta}
+data(shape(x))
+meta(shape(x)) 
+```
+
+## Annotations
+
+Currently supported methods for the `tables` layers include:
+
+- `getTable()` to retrieve the `table` annotating a given element
+- `setTable()` to construct a new annotation for a given element
+- `valTable()` to retrieve specific values from a `table`
+
+```{r tbl}
+# retrieve 'table' for an element
+(t <- getTable(x, i <- "blobs_labels"))
+head(colData(t))
+meta(t)
+# get values from an element's 'table'
+valTable(x, i, "channel_0_sum")
+# add an artificial 'table' to an element
+i <- "blobs_points"
+# ...passing a preconstructed 'data.frame'
+id <- unique(point(x)$instance_id)
+df <- data.frame(n=runif(length(id)))
+y <- setTable(x, i, df)
+head(colData(getTable(y, i)))
+# ...using a list of data generating functions
+f <- list(
+    numbers=\(n) runif(n),
+    letters=\(n) sample(letters, n, TRUE))
+args <- c(list(x, i), f)
+y <- do.call(setTable, args)
+head(colData(getTable(y, i)))
+```
+
+## Transformations
+
+To facilitate .zattrs handling, we provide a set of functions to access and modify its contents. Specifically,
+
+- `axes` to access a given element's dimension names and types
+- `CTdata/name/type` to access coordinate transformation components
+- `rmv/addCT` to remove, add, or append coordinate transformations
+
+```{r cs-methods}
+z <- meta(label(x))
+axes(z)
+CTdata(z)
+CTname(rmvCT(z, "scale"))
+CTname(addCT(z, 
+    name="D'Artagnan", 
+    type="scale", 
+    data=c(19, 94)))
+```
+
+`Zattrs` specify an explicit relationship between elements and coordinate systems.
+We can represent these are a graph as follows:
+
+```{r cs-graph}
+(g <- CTgraph(x))
+plotCoordGraph(g)
+```
+
+The above representation greatly facilitates queries of the transformation(s) 
+required to spatially align elements. `blobs_labels`, for example, requires a
+sequential transformation (scaling and translation) for the `sequence` space:
+
+```{r cs-path, results="hold"}
+# the following are equivalent
+i <- "blobs_labels"
+j <- "sequence"
+y <- label(x, i)
+CTpath(x, i, j)
+invisible(CTpath(y, j))
+```
+
+# Session info
+
+```{r sessionInfo, echo=FALSE}
+sessionInfo()
+```

From d2f9fc29eac33aed556f6d05b84bb29671f3a411 Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:53:10 +0100
Subject: [PATCH 6/7] add back some lines

---
 .Rbuildignore | 2 +-
 .gitignore    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.Rbuildignore b/.Rbuildignore
index 448e34d..824fa78 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -3,4 +3,4 @@
 ^\.github$
 vignettes/*html
 vignettes/*cache
-vignettes/*files
\ No newline at end of file
+vignettes/*files
diff --git a/.gitignore b/.gitignore
index af4f780..7ac4af5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,4 +9,4 @@ inst/extdata/mibitof.zarr
 inst/extdata/xenium1.zarr
 inst/extdata/visiumhd.zarr
 *.Rproj
-*.html
\ No newline at end of file
+*.html

From cdf4eb83507f822030956584880d6b7da8e9e41c Mon Sep 17 00:00:00 2001
From: Artur-man <artur-man@hotmail.com>
Date: Thu, 29 Jan 2026 16:54:29 +0100
Subject: [PATCH 7/7] remove doc and meta

---
 Meta/vignette.rds   | Bin 197 -> 0 bytes
 doc/SpatialData.R   |  70 --------------------
 doc/SpatialData.Rmd | 157 --------------------------------------------
 3 files changed, 227 deletions(-)
 delete mode 100644 Meta/vignette.rds
 delete mode 100644 doc/SpatialData.R
 delete mode 100644 doc/SpatialData.Rmd

diff --git a/Meta/vignette.rds b/Meta/vignette.rds
deleted file mode 100644
index 1e01f0673518e3f5073ec7d2250b80f92491e5de..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 197
zcmV;$06PC4iwFP!000001B>8dU|?WkU||K4%s?iyFpyvaVgVp#WME<71k(J$1&Jk@
zi8(HbC5d`LxhZJU+(^=BQUb_2GfHxE(ByehOa{6^7%T}<1OzNhNQznW5_40F(M(`>
zNi9gtO92W0!>*t4KbjT}@6^ij{34hh6g6y6H7stKIjJyvLo!R?9OeKQHz<=a2;B`B
z=A*cuvnan@59SA6P`Eb$iT^-=?$P9&#A0-ha;1R6D6I&nALMQT2}<jAxd8wG4jE66

diff --git a/doc/SpatialData.R b/doc/SpatialData.R
deleted file mode 100644
index 282417a..0000000
--- a/doc/SpatialData.R
+++ /dev/null
@@ -1,70 +0,0 @@
-## ----setup, include=FALSE-----------------------------------------------------
-knitr::opts_chunk$set(cache=FALSE, message=FALSE, warning=FALSE)
-
-## ----load-libs----------------------------------------------------------------
-library(SpatialData)
-library(SingleCellExperiment)
-
-## ----blobs-read---------------------------------------------------------------
-x <- file.path("extdata", "blobs.zarr")
-x <- system.file(x, package="SpatialData")
-(x <- readSpatialData(x, anndataR=FALSE))  # VJC Dec 8, test effect of absence of anndataR
-
-## ----get, results="hide"------------------------------------------------------
-shapeNames(x) # there are two images
-shapes(x) # this is a list of them
-shape(x, i=1) # this is the 1st one
-shape(x, "blobs_polygons") # this is the 3nd one
-x$shapes$blobs_circles # list-like handling also works
-
-## ----data/meta----------------------------------------------------------------
-data(shape(x))
-meta(shape(x)) 
-
-## ----tbl----------------------------------------------------------------------
-# retrieve 'table' for an element
-(t <- getTable(x, i <- "blobs_labels"))
-head(colData(t))
-meta(t)
-# get values from an element's 'table'
-valTable(x, i, "channel_0_sum")
-# add an artificial 'table' to an element
-i <- "blobs_points"
-# ...passing a preconstructed 'data.frame'
-id <- unique(point(x)$instance_id)
-df <- data.frame(n=runif(length(id)))
-y <- setTable(x, i, df)
-head(colData(getTable(y, i)))
-# ...using a list of data generating functions
-f <- list(
-    numbers=\(n) runif(n),
-    letters=\(n) sample(letters, n, TRUE))
-args <- c(list(x, i), f)
-y <- do.call(setTable, args)
-head(colData(getTable(y, i)))
-
-## ----cs-methods---------------------------------------------------------------
-z <- meta(label(x))
-axes(z)
-CTdata(z)
-CTname(rmvCT(z, "scale"))
-CTname(addCT(z, 
-    name="D'Artagnan", 
-    type="scale", 
-    data=c(19, 94)))
-
-## ----cs-graph-----------------------------------------------------------------
-(g <- CTgraph(x))
-plotCoordGraph(g)
-
-## ----cs-path, results="hold"--------------------------------------------------
-# the following are equivalent
-i <- "blobs_labels"
-j <- "sequence"
-y <- label(x, i)
-CTpath(x, i, j)
-invisible(CTpath(y, j))
-
-## ----sessionInfo, echo=FALSE--------------------------------------------------
-sessionInfo()
-
diff --git a/doc/SpatialData.Rmd b/doc/SpatialData.Rmd
deleted file mode 100644
index 956096f..0000000
--- a/doc/SpatialData.Rmd
+++ /dev/null
@@ -1,157 +0,0 @@
----
-title: "`SpatialData`"
-date: "`r format(Sys.Date(), '%B %d, %Y')`"
-package: "`r BiocStyle::pkg_ver('SpatialData')`"
-author: 
-  - name: Helena Lucia Crowell
-  - name: Louise Deconinck
-  - name: Artür Manukyan
-  - name: Dario Righelli
-  - name: Estella Dong
-  - name: Vince Carey
-output:
-  BiocStyle::html_document
-vignette: |
-  %\VignetteIndexEntry{SpatialData}
-  %\VignetteEngine{knitr::rmarkdown}
-  %\VignetteEncoding{UTF-8}
----
-
-```{r setup, include=FALSE}
-knitr::opts_chunk$set(cache=FALSE, message=FALSE, warning=FALSE)
-```
-
-```{r load-libs}
-library(SpatialData)
-library(SingleCellExperiment)
-```
-
-# Introduction
-
-The `SpatialData` package contains a set of reader and plotting functions for 
-spatial omics data stored as [SpatialData](https://spatialdata.scverse.org/en/latest/index.html) 
-`.zarr` files that follow [OME-NGFF specs](https://ngff.openmicroscopy.org/latest/#image-layout).
-
-Each `SpatialData` object is composed of five layers: images, labels, shapes, 
-points, and tables. Each layer may contain an arbitrary number of elements.
-
-Images and labels are represented as `ZarrArray`s (`r BiocStyle::Biocpkg("Rarr")`). 
-Points and shapes are represented as `r BiocStyle::CRANpkg("arrow")` objects linked 
-to an on-disk *.parquet* file. As such, all data are represented out of memory.
-
-Element annotation as well as cross-layer summarizations (e.g., count matrices)
-are represented as `r BiocStyle::Biocpkg("SingleCellExperiment")` as tables.
-
-## Handling
-
-For demonstration, we read in a toy dataset that is available through the package:
-
-```{r blobs-read}
-x <- file.path("extdata", "blobs.zarr")
-x <- system.file(x, package="SpatialData")
-(x <- readSpatialData(x, anndataR=FALSE))  # VJC Dec 8, test effect of absence of anndataR
-```
-
-`SpatialData` object behave like a list, thereby supporting flexible accession, 
-e.g., via `$` and `[[`, using character or integer indices etc. Specifically,
-
-- `image/label/shape/point/table()` retrieve one element
-- `images/labels/shapes/points/tables()` retrieve one layer
-- `image/label/shape/point/tableNames()` retrieve element names
-
-Let's demonstrate these capabilities using the image layer:
-
-```{r get, results="hide"}
-shapeNames(x) # there are two images
-shapes(x) # this is a list of them
-shape(x, i=1) # this is the 1st one
-shape(x, "blobs_polygons") # this is the 3nd one
-x$shapes$blobs_circles # list-like handling also works
-```
-
-Each element is made up of two key components: 
-
-- `data`: the actual array or table (for images/labels and shapes/points, respectively)
-- `meta`: list of metadata retrieved from an OME-NGFF compliant *.zattrs* (stored as `Zattrs`)
-
-```{r data/meta}
-data(shape(x))
-meta(shape(x)) 
-```
-
-## Annotations
-
-Currently supported methods for the `tables` layers include:
-
-- `getTable()` to retrieve the `table` annotating a given element
-- `setTable()` to construct a new annotation for a given element
-- `valTable()` to retrieve specific values from a `table`
-
-```{r tbl}
-# retrieve 'table' for an element
-(t <- getTable(x, i <- "blobs_labels"))
-head(colData(t))
-meta(t)
-# get values from an element's 'table'
-valTable(x, i, "channel_0_sum")
-# add an artificial 'table' to an element
-i <- "blobs_points"
-# ...passing a preconstructed 'data.frame'
-id <- unique(point(x)$instance_id)
-df <- data.frame(n=runif(length(id)))
-y <- setTable(x, i, df)
-head(colData(getTable(y, i)))
-# ...using a list of data generating functions
-f <- list(
-    numbers=\(n) runif(n),
-    letters=\(n) sample(letters, n, TRUE))
-args <- c(list(x, i), f)
-y <- do.call(setTable, args)
-head(colData(getTable(y, i)))
-```
-
-## Transformations
-
-To facilitate .zattrs handling, we provide a set of functions to access and modify its contents. Specifically,
-
-- `axes` to access a given element's dimension names and types
-- `CTdata/name/type` to access coordinate transformation components
-- `rmv/addCT` to remove, add, or append coordinate transformations
-
-```{r cs-methods}
-z <- meta(label(x))
-axes(z)
-CTdata(z)
-CTname(rmvCT(z, "scale"))
-CTname(addCT(z, 
-    name="D'Artagnan", 
-    type="scale", 
-    data=c(19, 94)))
-```
-
-`Zattrs` specify an explicit relationship between elements and coordinate systems.
-We can represent these are a graph as follows:
-
-```{r cs-graph}
-(g <- CTgraph(x))
-plotCoordGraph(g)
-```
-
-The above representation greatly facilitates queries of the transformation(s) 
-required to spatially align elements. `blobs_labels`, for example, requires a
-sequential transformation (scaling and translation) for the `sequence` space:
-
-```{r cs-path, results="hold"}
-# the following are equivalent
-i <- "blobs_labels"
-j <- "sequence"
-y <- label(x, i)
-CTpath(x, i, j)
-invisible(CTpath(y, j))
-```
-
-# Session info
-
-```{r sessionInfo, echo=FALSE}
-sessionInfo()
-```