Vitessce Integration Design Document

*This is for internal use only; if you'd like to open an issue or request a new feature, please open a bug or enhancement issue*

### Instructions
This document should be filled out prior to embarking on any project that will take more than a couple of hours to complete. The goal is to make sure that everyone is on the same page for the functionality and requirements of new features. Therefore, it's important that this is detailed enough to catch any misunderstandings beforehand. For larger projects, it can be useful to first give a high-level sketch, and then go back and fill in the details. For smaller ones, filling the entire thing out at once can be sufficient.

**Relevant background**

[Vitessce](http://vitessce.io/) is a visualization tool for spatial single cell data. It can be used as a standalone web application, an embedded web component, or as a widget in Jupyter Lab. HuBMAP uses this to visualize certain datasets on their data portal.

Here is a brief overview of the components for a Vitessce HuBMAP Dataset: [HBM892.CCDZ.345](https://portal.hubmapconsortium.org/browse/dataset/fdfa344add5dcf9e8e0f6572efbf9312). One thing that's nice is we can download the Jupyter Notebook which creates this Vitessce visualization.

This visualization is composed of the following [Views](http://vitessce.io/docs/components/):

- Scatter plot
- Spatial
- Set Views
- Heatmap

There are coordination values and scopes with which "glue" views together. For example, hovering over a point in the UMAP scatter plot will also highlight the corresponding point in the Spatial view, along with the corresponding row in the Heatmap view.

Keep in mind that Vitessce works best with a single image per visualization.

## File Types and File Formats

With Vitessce, there are many ways to organize the data for ingestion.

### Implementation with current Cell Table + TIFF Files

Assuming we have a finalized Cell Table with respect to a single image, we can organize the data for a Vitessce visualization as follows:

1. *Necessary* - [**Observation Feature Matrix**](http://vitessce.io/docs/data-file-types/#obsfeaturematrixcsv) (csv)
1. This is an observation by feature matrix (cell segmentation ID x Channel Intensity)
| cell_id | CD33 | MYC |
|:-------:|:----:|:----:|
| cell_1 | 15.1 | 0.0 |
| cell_2 | 0.0 | 21.4 |
| cell_3 | 0.0 | 0.0 |

2. *Necessary* - [**Observation Sets**]("http://vitessce.io/docs/data-file-types/#obssetscsv") (csv)
1. Maps each observation (cell id) to one or more sets.
2. Mainly for assigning cells to clusters, cell types, groups, lineages, etc...

| cell_id | leiden | pixie | cell_type_coarse | cell_type_fine | pred_cell_type | pred_score |
|:-------:|:------:|-------|:----------------:|:-----------------:|:-----------------:|:----------:|
| cell_1 | 1 | 1 | Immune | B cell | B cell | 0.81 |
| cell_2 | 2 | 1 | Immune | T cell | T cell | 0.99 |
| cell_3 | 2 | 3 | Immune | T cell | Macrophage | 0.21 |
| cell_4 | 3 | 6 | Neuron | Excitatory neuron | Inhibitory neuron | 0.25 |
3. *Necessary* - [**Observation Segmentations**](http://vitessce.io/docs/data-file-types/#obssegmentationsome-tiff) (OME TIFF)
1. A cell segmentation mask
4. *Necessary* - [**Image**](http://vitessce.io/docs/data-file-types/#imageome-tiff) (OME TIFF / OME Zarr)
1. Can also be a Zarr store
1. Convert the FOV structure to a multichannel OME TIFF.
5. *Optional* - [**Observation Embedding**](http://vitessce.io/docs/data-file-types/#obsembeddingcsv) (csv)
1. UMAP, TSNE embeddings for each cell (UMAP Axis 1, UMAP Axis 2, TSNE Axis 1, TSNE Axis 2, etc...)
2. Requires 2D embeddings for each cell with respect to a dimensionality reduction technique.
6. *Optional* - [**Feature labels / Observation Labels**] (csv)
1. Alternate labels for cell IDs, and channel names
| cell_id | alt_cell_id |
|:-------:|:-----------:|
| cell_1 | ATGC |
| cell_2 | GTTA |

### Implementation with AnnData + TIFF Files

In the case where we have an [AnnData Zarr](http://vitessce.io/docs/data-file-types/#anndata-zarr) object, organizing the data is much easier.

Convert the FOV to a multichannel OME-TIFF.

For example, we mainly need to provide the following:

1. `X`: The observation by feature matrix (cell-by-marker)
2. `obs`: The observation metadata (cell metadata)
3. `var`: The feature metadata (marker metadata)
4. *Optional* - `obsm`: The observation embeddings (UMAP, TSNE, etc...)
1. Prefixed with `X_`, where `X_umap` is the UMAP embedding of `X`.
5. *Optional* - `layers`: The image data (cell segmentation mask, image, etc...)

### Implementation with `SpatialData`

In the case where we have a [`SpatialData`](http://vitessce.io/docs/data-file-types/#spatialdata) object, it's more straightforward than the `AnnData` implementation.

We just need the `SpatialData` object subset with a particular FOV of interest. The image is a `Zarr` store, and the `AnnData` is the Table object. The same notes about `AnnData` apply.

### Creating Views and Coordination Values

Depending on the data, the use case you can organize views in multiple ways.

For example, with the Bone Marrow data, we have MIBI, MALDI, and HnE images. We can create a Vitessce visualization with the following views:
- Spatial
- MIBI
- MALDI
- HnE
- Create a view which syncs all three images together (where a segmentation ID in one image is highlighted in the other two images)
- Scatter Plot
- UMAP / TSNE on Axis 1,2 colored by Pixie Clusters
- Layer controller for MIBI and MALDI, along with Feature List and Observation Sets for both

The user has artistic freedom to select what works best for them and the data they're trying to visualize. This is an iterative process which can be run in a Jupyter Notebook.

#### Example Code from some HuBMAP stuff in July:

```python
from vitessce import (
VitessceConfig,
Component as cm,
CoordinationType as ct,
OmeTiffWrapper,
OmeZarrWrapper,
MultiImageWrapper,
)
from os.path import join

vc = VitessceConfig(schema_version="1.0.16", name='MCMicro Bitmask Visualization', description='Segmentation + Data of Exemplar 001')
dataset = vc.add_dataset(name='MCMicro').add_object(
MultiImageWrapper(
image_wrappers=[
OmeZarrWrapper(
img_url="https://vitessce-data.storage.googleapis.com/0.0.33/main/human-lymph-node-10x-visium/human_lymph_node_10x_visium.ome.zarr", name="Image",
),
# We can mix and match image types as well
OmeTiffWrapper(img_url='https://vitessce-demo-data.storage.googleapis.com/exemplar-001/cellMask.pyramid.ome.tif', name='Mask', is_bitmask=True),
]
)
)
spatial = vc.add_view(cm.SPATIAL, dataset=dataset)
status = vc.add_view(cm.STATUS, dataset=dataset)
lc = vc.add_view(cm.LAYER_CONTROLLER, dataset=dataset)

# Organize the layout of the views
vc.layout(spatial | (lc / status));

# Create the Vitessce Object
vw = vc.widget()
vw
```
This is a rather basic view with just the Image, segmentation mask and a layer controller for the channels.

Vitessce configurations can be applied to other images, segmentation masks and cell tables as well. So a user can develop their ideal visualization structure on one FOV, and then easily apply it to other FOVs of interest.

It is not much more effort to go from a simple view such as in the example code, to a complex view like the HuBMAP one.

## Exporting and Data Hosting

Once the user is satisfied with their current Vitessce Visualization, the configuration schema can be exported (along with the data) to a Zarr store a supplementary JSON file.

This can be loaded locally, or ideally hosted on a cloud service (AWS, GCloud) for easy storage.

## Viewing the Data

When it comes to viewing the data object, we can set up a lab GitHub Pages site, or add the view to the existing lab site.
- [GitHub Pages Deployment](http://vitessce.io/docs/tutorial-gh-pages/)

**Timeline**

Estimated date when a fully implemented version will be ready for review: N/A

Estimated date when the finalized project will be merged in: N/A

## Resources

There are a lot of examples and resources for Vitessce.

- Official Vitessce Python Notebooks:
- https://github.com/vitessce/vitessce-python/tree/main/docs/notebooks
- https://github.com/vitessce/vitessce-python-tutorial
- Go to HuBMAP and take a look at Datasets with visualizations, pick one which may resemble a good starting point.

More examples out in the wild:
- Minimal:
- [Multiplexed imaging of high-density libraries of RNAs with MERFISH and expansion microscopy
](http://vitessce.io/#?dataset=wang-2018)
- [Four registered imaging modalities (PAS, IMS, AF) from HuBMAP collection HBM876.XNRH.336
](http://vitessce.io/#?dataset=neumann-2020)
- Maximal:
- [Spatial organization of the somatosensory cortex revealed by osmFISH
](http://vitessce.io/#?dataset=codeluppi-2018)
- [Spatial multi-omic map of human myocardial infarction. Visium slide from patient P9, region GT/IZ_P9
](http://vitessce.io/#?dataset=kuppe-2022)
- [Visium Spatial Gene Expression data from 10x Genomics
](http://vitessce.io/#?dataset=human-lymph-node-10x-visium)
- HuBMAP
- [HBM644.HLRW.739 MALDI IMS, Kidney](https://portal.hubmapconsortium.org/browse/dataset/b062b82bc2b5af072db4a3af191ec019)
- [HBM892.CCDZ.345, Slide-seq, Kidney](https://portal.hubmapconsortium.org/browse/dataset/fdfa344add5dcf9e8e0f6572efbf9312)