##### Vitessce: AnnData [image: .md][image]

This tutorial demonstrates how to use Vitessce to create interactive
visualizations for data stored as LaminDB artifacts. It requires a
remote LaminDB instance with cloud storage to enable the Vitessce
button (shown below) in the web interface.

It has been adapted from the data preparation examples in the Vitessce
documentation.

In this part, we'll visualize an AnnData object stored in both H5AD
and Zarr formats.

 # pip install 'vitessce[all]>=3.5.0' lamindb
 !lamin connect laminlabs/lamindata # <-- replace with your remote instance

 import vitessce as vit
 import lamindb as ln

 ln.track()

#### Visualize an AnnData object (H5AD format)

Here we use the Habib et al. 2017 dataset from the COVID-19 Cell Atlas
that has been previously subset to highly variable genes. The dataset
was ingested into the public laminlabs/lamindata instance in this
transform.

 h5ad_artifact = ln.Artifact.get(key="vitessce_examples/habib17.h5ad")

When using ".h5ad" files, we construct a Reference Specification which
enables interoperability with the Zarr interface. The Reference
Specification JSON was also generated in the transform above.

 ref_artifact = ln.Artifact.get(key="vitessce_examples/habib17.reference.json")

###### Save a VitessceConfig object

You can create a dashboard for one or several datasets by using
Vitessce's component API.

You can pass artifacts to the "AnnDataWrapper" class using the
"adata_artifact" and "ref_artifact" parameters.

 vc = vit.VitessceConfig(
 schema_version="1.0.18",
 description=h5ad_artifact.description,
 )

 dataset = vc.add_dataset(name="Habib 2017").add_object(
 vit.AnnDataWrapper(
 adata_artifact=h5ad_artifact,
 ref_artifact=ref_artifact,
 obs_feature_matrix_path="X",
 obs_embedding_paths=["obsm/X_umap"],
 obs_embedding_names=["UMAP"],
 obs_set_paths=["obs/CellType"],
 obs_set_names=["Cell Type"],
 )
 )

 obs_sets = vc.add_view(vit.ViewType.OBS_SETS, dataset=dataset)
 obs_sets_sizes = vc.add_view(vit.ViewType.OBS_SET_SIZES, dataset=dataset)
 scatterplot = vc.add_view(vit.ViewType.SCATTERPLOT, dataset=dataset, mapping="UMAP")
 heatmap = vc.add_view(vit.ViewType.HEATMAP, dataset=dataset)
 genes = vc.add_view(vit.ViewType.FEATURE_LIST, dataset=dataset)
 vc.link_views([scatterplot, heatmap], ["featureValueColormapRange"], [[0.0, 0.1]])
| vc.layout(((scatterplot | obs_sets) / heatmap) | (obs_sets_sizes / genes)) |

Save the "VitessceConfig" object.

 h5ad_vc_artifact = ln.integrations.save_vitessce_config(
 vc,
 description="View Habib17 (h5ad) in Vitessce",
 )

Note:

  After running "save_vitessce_config", a Vitessce button will appear
  next to the dataset on the Artifacts or Collections page of the web
  interface.If your "VitessceConfig" object references data from
  multiple artifacts, the Vitessce button will appear next to a
  collection that groups these artifacts (on the Collections tab of
  the Artifacts page).Note that when using an ".h5ad"-based artifact,
  the presence of the corresponding ".reference.json" file will result
  in the creation of a collection.

The Vitessce button for this dataset is available on the Collection
page.

#### Visualize an AnnData object (Zarr format)

AnnData objects can be saved on-disk to not only ".h5ad" files, but
also to Zarr stores using AnnData's write_zarr method.

Just like in the above section, we use a Zarr storage that has been
previously written with "write_zarr()" and subset to highly variable
genes and ingested into the public laminlabs/lamindata instance in
this transform.

 adata_zarr_artifact = ln.Artifact.get(key="vitessce_examples/habib17.adata.zarr")

###### Save a VitessceConfig object

You can create a dashboard for one or several datasets by using
Vitessce's component API. Here, we configure the visualization the
same way as above in the ".h5ad"-based example, with the exception of
the "ref_artifact" parameter, as ".zarr"-based AnnData objects do not
require a Reference Specification for Zarr interoperability.

 vc = vit.VitessceConfig(
 schema_version="1.0.18",
 description=adata_zarr_artifact.description,
 )

 dataset = vc.add_dataset(name="Habib 2017").add_object(
 vit.AnnDataWrapper(
 adata_artifact=adata_zarr_artifact,
 obs_feature_matrix_path="X",
 obs_embedding_paths=["obsm/X_umap"],
 obs_embedding_names=["UMAP"],
 obs_set_paths=["obs/CellType"],
 obs_set_names=["Cell Type"],
 )
 )

 obs_sets = vc.add_view(vit.Component.OBS_SETS, dataset=dataset)
 obs_sets_sizes = vc.add_view(vit.Component.OBS_SET_SIZES, dataset=dataset)
 scatterplot = vc.add_view(vit.Component.SCATTERPLOT, dataset=dataset, mapping="UMAP")
 heatmap = vc.add_view(vit.Component.HEATMAP, dataset=dataset)
 genes = vc.add_view(vit.Component.FEATURE_LIST, dataset=dataset)

 vc.link_views([scatterplot, heatmap], ["featureValueColormapRange"], [[0.0, 0.1]])
| vc.layout(((scatterplot | obs_sets) / heatmap) | (obs_sets_sizes / genes)) |

Save the "VitessceConfig" object.

 adata_zarr_vc_artifact = ln.integrations.save_vitessce_config(
 vc,
 description="View Habib17 in Vitessce",
 )

Note:

  After running "save_vitessce_config", a Vitessce button will appear
  next to the dataset on the Artifacts or Collections page of the web
  interface.If your "VitessceConfig" object references data from
  multiple artifacts, the Vitessce button will appear next to a
  "Collection" that groups these artifacts (on the Collections tab of
  the Artifacts page).

Clicking the Vitessce button for this ".zarr"-based artifact or
".h5ad"-based collection launches the same interactive viewer, as both
formats represent the same dataset:

 # compare the generated vitessce config to the public one on vitessce/examples (H5AD)
 db = ln.DB("vitessce/examples")
 public_vc_json = db.Artifact.get("ffUKrGJGNHL3TDhG0000").load()
 h5ad_vc_json = h5ad_vc_artifact.load()

 assert public_vc_json["layout"] == h5ad_vc_json["layout"]
 assert public_vc_json["coordinationSpace"] == h5ad_vc_json["coordinationSpace"]

 # compare the generated vitessce config to the public one on vitessce/examples (Zarr)
 public_vc_json = db.Artifact.get("J4tMB6qAeHvsgEsp0000").load()
 adata_zarr_vc_json = adata_zarr_vc_artifact.load()

 assert public_vc_json["layout"] == adata_zarr_vc_json["layout"]
 assert public_vc_json["coordinationSpace"] == adata_zarr_vc_json["coordinationSpace"]

 ln.finish()