---

title: "ondisk"

output: 

  html_document:

    toc: true

    toc_float:

      collapsed: false

      smooth_scroll: false

---

<style>

.title{

  display: none;

}

body {

  text-align: justify

}

.center {

  display: block;

  margin-left: auto;

  margin-right: auto;

}

</style>

```{css, echo=FALSE}

.watch-out {

  color: black;

}

```

```{r setup, include=FALSE}

# use rmarkdown::render_site(envir = knitr::knit_global())

knitr::opts_chunk$set(highlight = TRUE, echo = TRUE)

```

<br>

## Import VisiumHD Data

We first have to download some packages that are necessary to import datasets from `.parquet` and `.h5` files provided by the VisiumHD readouts.

```{r class.source="watch-out", eval = FALSE}

install.packages("arrow")

BiocManager::install("rhdf5")

library(arrow)

library(rhdf5)

```

We use the **importVisiumHD** function to start analyzing the data. The data has 393401 spots which we will use OnDisk-backed methods to efficiently manipulate, analyze and visualize these spots.

The VisiumHD readouts provide multiple bin sizes which are aggregated versions of the original 2$\mu$m $x$ 2$\mu$m capture spots. The default bin sizes are **(i)** 2$\mu$m $x$ 2$\mu$m, **(ii)** 8$\mu$m $x$ 8$\mu$m and **(iii)** 16$\mu$m $x$ 16$\mu$m.

```{r class.source="watch-out", eval = FALSE}

hddata <- importVisiumHD(dir.path = "VisiumHD/outs/", 

                         bin.size = "8", 

                         resolution_level = "hires")

```

<br>

## Saving/Loading VoltRon Objects

We use **BPCells** and **ImageArray** packages to accelerate operations of feature matrices and images. Here **BPCells** allows users access and operate on large feature matrices or clustering/spatial analysis, while **ImageArray** provides [pyramids images](https://en.wikipedia.org/wiki/Pyramid_(image_processing)) to allow fast access to large microscopy images. You can download these package from GitHub using **devtools**.

```{r class.source="watch-out", eval = FALSE}

devtools::install_github("bnprks/BPCells/r")

devtools::install_github("BIMSBbioinfo/ImageArray")

library(BPCells)

library(ImageArray)

```

We can now save the VoltRon object to disk, large matrices and images will be written to either **hdf5** or **zarr** files depending on the **format** arguement, and the rest of the R object would be written to an `.rds` file, both under the designated **output**.

```{r class.source="watch-out", eval = FALSE}

hddata <- saveVoltRon(hddata, format = "HDF5VoltRon", output = "data/VisiumHD")

```

If you want you can load the VoltRon object from the same path as you have saved.

```{r class.source="watch-out", eval = FALSE}

hddata <- loadVoltRon("data/VisiumHD/")

```

<br>

## Cell/Spot Analysis

The **BPCells** package provides fast methods to achieve operations common to single cell analysis such as filtering, normalization and dimensionality reduction. Here we have an example of single-cell like clustering of VisiumHD bins which is efficiently clustered.

```{r class.source="watch-out", eval = FALSE}

spatialpoints <- vrSpatialPoints(hddata)[as.vector(Metadata(hddata)$Count > 10)]

hddata <- subset(hddata, spatialpoints = spatialpoints)

hddata <- normalizeData(hddata, sizefactor = 10000)

hddata <- getFeatures(hddata, n = 3000)

selected_features <- getVariableFeatures(hddata)

hddata <- getPCA(hddata, features = selected_features, dims = 30)

hddata <- getUMAP(hddata, dims = 1:30)

```

We can now visualized genes over embedding or spatial plots.

```{r class.source="watch-out", eval = FALSE}

vrEmbeddingFeaturePlot(hddata, features = "Nrgn", embedding = "umap")

vrSpatialFeaturePlot(hddata, features = "Nrgn")

```

<table>

<tbody>

  <tr style = "vertical-align: center">

  <td style = "width:50%; vertical-align: center"> <img src="https://bimsbstatic.mdc-berlin.de/landthaler/VoltRon/Package/images/ondisk_embeddingfeature.png" class="center"></td>

  <td style = "width:55%; vertical-align: center"> <img src="https://bimsbstatic.mdc-berlin.de/landthaler/VoltRon/Package/images/ondisk_spatialfeature.png" class="center"></td>

  </tr>

</tbody>

</table>

<br>

## Spatial Data Alignment

The image registration workflow in the [Spatial Data Alignment](registration.html) tutorial can also be conducted using disk-backed methods of the VoltRon package. 

```{r class.source="watch-out", eval = FALSE}

library(VoltRon)

Xen_R1 <- importXenium("Xenium_R1/outs", sample_name = "XeniumR1", resolution_level = 3)

Xen_R1_image <- importImageData("Xenium_FFPE_Human_Breast_Cancer_Rep1_he_image.tif",

                                sample_name = "XeniumR1image",

                                image_name = "H&E")

```

<br>

We can save both Xenium and H&E (image) datasets to disk before using the mini Shiny app for registration

```{r class.source="watch-out", eval = FALSE}

Xen_R1_disk <- saveVoltRon(Xen_R1, 

                           format = "HDF5VoltRon", 

                           output = "data/Xen_R1_h5", replace = TRUE)

Xen_R1_image_disk <- saveVoltRon(Xen_R1_image,

                                 format = "HDF5VoltRon", 

                                 output = "data/Xen_R1_image_h5", replace = TRUE)

```

<br>

These disk-based datasets can then be loaded from the disk easily. 

```{r class.source="watch-out", eval = FALSE}

Xen_R1_disk <- loadVoltRon("../data/OnDisk/Xen_R1_h5/")

Xen_R1_image_disk <- loadVoltRon("../data/OnDisk/Xen_R1_image_h5/")

```

<br>

VoltRon stores large images as pyramids to increase interactive visualization efficiency. This storage strategy allows shiny apps to zoom in to tissue niches in a speedy fashion. VoltRon incorporates `Image_Array` objects (https://github.com/BIMSBbioinfo/ImageArray) to define these pyramids. 

```{r class.source="watch-out", eval = FALSE}

vrImages(Xen_R1_image_disk, as.raster = TRUE)

```

```

Image_Array Object 

Series 1 of size (3,27587,20511) 

Series 2 of size (3,13794,10256) 

Series 3 of size (3,6897,5128) 

Series 4 of size (3,3449,2564) 

Series 5 of size (3,1725,1282) 

Series 6 of size (3,863,641) 

Series 7 of size (3,432,321) 

```

<br>

We can now visualize and align the Xenium and H&E objects. 

```{r class.source="watch-out", eval = FALSE}

# Align spatial data

xen_reg <- registerSpatialData(object_list = list(Xen_R1_disk, Xen_R1_image_disk))

```

<div>

  <video width="100%" height="100%" controls autoplay>

    <source src="https://bimsbstatic.mdc-berlin.de/landthaler/VoltRon/Package/images/video_temp.mov" type="video/mp4">

  Your browser does not support the video tag.

  </video>

</div>

<br>

```{r class.source="watch-out", eval = FALSE}

# transfer aligned H&E to Xenium data

Xenium_reg <- xen_reg$registered_spat[[2]]

vrImages(Xen_R1_disk[["Assay1"]], name = "main", channel = "H&E") <- vrImages(Xenium_reg, name = "H&E_reg")

# visualize

vrImages(Xen_R1_disk, channel = "H&E", scale.perc = 10)

```

<br>

<img width="92%" height="92%" src="https://bimsbstatic.mdc-berlin.de/landthaler/VoltRon/Package/images/ondisk_alignedHE.png" class="center">