## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(cache=FALSE, message=FALSE, warning=FALSE)

## ----eval=FALSE---------------------------------------------------------------
# ok <- require("BiocManager", quietly=TRUE)
# if (!ok) install.packages("BiocManager")
# BiocManager::install("spatialdataR")

## ----eval=FALSE---------------------------------------------------------------
# BiocManager::install("HelenaLC/SpatialData.data") # example datasets
# BiocManager::install("HelenaLC/SpatialData.plot") # visualization

## ----schematic, echo=FALSE, fig.wide=TRUE-------------------------------------
knitr::include_graphics("schematic.png")

## ----load---------------------------------------------------------------------
# dependencies
library(spatialdataR)
library(SingleCellExperiment)

# path to 'spatialdata' Zarr store
zs <- file.path("extdata", "blobs.zarr")
zs <- system.file(zs, package="spatialdataR")

# read as 'SpatialData' R object
(sd <- readSpatialData(zs))

## ----get-one, results="hide"--------------------------------------------------
# preferred way
# (using accessor)
image(sd, 1)
image(sd, "blobs_image") 

# alternative ways 
# (using list-style)
images(sd)[[1]]
images(sd)[["blobs_image"]]

sd$images[[1]]
sd$images$blobs_image
sd$images[["blobs_image"]]

## ----get-nms, results="hide"--------------------------------------------------
# preferred way 
# (using accessor)
imageNames(sd)

# alternative ways 
# (using list-style)
names(sd$images)
names(sd[["images"]])

## ----sub, results="hide"------------------------------------------------------
# keep image-layer only
sd[1]
sd["images"]

# keep 1st image & label element
sd[c(1, 2), list(1, 1)]
sd[c("images", "labels"), list(1, 1)]

## ----data---------------------------------------------------------------------
# get multi-scale image
i <- image(sd, 2)

a <- data(i, 1)   # highest
b <- data(i, Inf) # lowest

# available resolutions
l <- data(i, NULL)

# dimensions of each
d <- vapply(l, dim, integer(3))
rownames(d) <- c("c", "y", "x")
colnames(d) <- seq_along(l)
show(d)

## ----tables-------------------------------------------------------------------
# access annotation
(se <- table(sd))

# annotated region(s)
region(se)
    
# annotated instance(s)
instances(se)

## ----ct-graph, fig.width=6, fig.height=3--------------------------------------
g <- CTgraph(sd)
CTplot(g)

## ----transform----------------------------------------------------------------
# get element 
a <- label(sd)

# project into 'global'
b <- spatialdataR::transform(a, "scale")

# compare XY extents
do.call(rbind, c(a=extent(a), b=extent(b)))

## ----crop, echo=-1, results="hold", out.width="75%", fig.align="center"-------
par(mfrow=c(1,2), mar=c(0,1,2,1))

# bounding box
xy <- list(xmin=-Inf, xmax=Inf, ymin=20, ymax=40)
sp <- crop(sd, xy)

plot(
    point(sd)$geometry, col="blue", 
    main="crop() with\nbounding box") 
points(point(sp)$geometry, col="red") 

# polygon
xy <- rbind(c(0, 0), c(64, 0), c(32, 64))
sq <- crop(sd, xy)

plot(
    point(sd)$geometry, col="blue", 
    main="crop() with\npolygon") 
points(point(sq)$geometry, col="red") 

## ----mask-image-label---------------------------------------------------------
# average channel-wise pixel values by labels
sp <- mask(sd, i="blobs_image", j="blobs_labels")
se <- table(sp, "blobs_image_by_blobs_labels")
assay(se)

## ----mask-point-shape---------------------------------------------------------
# count different point species in polygons
sp <- mask(sd, i="blobs_points", j="blobs_polygons")
se <- table(sp, "blobs_points_by_blobs_polygons")
assay(se)

## ----mask-shape-shape, eval=FALSE---------------------------------------------
# # average shape-level data by other shapes
# sp <- mask(sd, i="blobs_polygons", j="blobs_circles")

## ----query--------------------------------------------------------------------
se <- table(sd)
se$foo <- sample(c("A", "B"), ncol(se), replace=TRUE)
sp <- `table<-`(sd, value=se)
(sp <- query(sp, foo == "A"))
table(sp)$foo

## ----combine------------------------------------------------------------------
sp <- combine(list(foo=sd, bar=sd))
cbind(
    original=lengths(colnames(sd)),
    combined=lengths(colnames(sp)))
imageNames(sp)

## ----centroids----------------------------------------------------------------
head(centroids(point(sd)))

## -----------------------------------------------------------------------------
# object-wide
xy <- extent(sd)
unlist(xy)

# one element
xy <- extent(point(sd))
unlist(xy)

# with prior alignment to target coordinate space
xy <- extent(label(sd))
yx <- extent(label(sd), "scale")
rbind(native=unlist(xy), scaled=unlist(yx))

## ----sessionInfo--------------------------------------------------------------
sessionInfo()