Skip to main content

View Configs via file URLs

To allow quick and easy visualisation of an image or an AnnData object, Vitessce can generate a view config automatically, given the URLs to the data files. This page explains how to use this feature and which file formats are supported.

Supported formats​

Vitessce currently supports automatic view config generation for the following file formats:

How to use​

To use this functionality, go to the App page of this website and paste the URL of the file(s) to visualize, separating multiple URLs with semicolon (;).

Upon entering URLs, a list of layout options that are available for the respective file types will be displayed. Upon clicking one of the layout options, the JSON editor will be populated with the generated view config. Then, you can either launch Vitessce with the generated configuration directly, or customize the configuration before launching.

This functionality relies on file extensions to infer file formats, so ensure that each data file is of supported format and complies with the requirements. Note that all files will be treated as part of the same dataset (i.e., one element in config.datasets[]).

The currently-supported layout options (also referred to as user-provided "hints" to guide the config generation) for each dataset type can be found in constants.js file under https://github.com/vitessce/vitessce/tree/main/packages/config/src.

NOTE: In some cases, the automatically generated view config might need small manual adjustments. For instance, when using hint Spatial transcriptomics (with histology image and polygon cell segmentations), you will need to manually adjust the coordination values for the image and the segmentation layer, which are set to null by default, to match your particular files.

Requirements​

You will need one or more URLs, where each points to a static file to visualize. Each URL must end with one of the supported file extensions listed below.

OME-TIFF format​

If you want to view data in OME-TIFF format, make sure that the URL to the file ends with .ome.tif or .ome.tiff. For example:

AnnData-Zarr format​

If you want to view data in AnnData-Zarr format, make sure that the URL to the root of the Zarr store ends with .h5ad.zarr, .adata.zarr or .anndata.zarr.

If a .zmetadata file is present in the root of the Zarr store, it will be used for generating the view config. .zmetadata file can be generated by running the consolidate_metadata function on the Zarr store that results from AnnData.write_zarr.

For example, a Zarr store located at https://example.com/my_dataset.h5ad.zarr must have its consolidated metadata file at https://example.com/my_dataset.h5ad.zarr/.zmetadata. If this returns a 404 Not Found error instead, this means that the .zmetadata file is either missing or not uploaded at the root folder.

Alternatively, if no .zmetadata file is found at the root of the Zarr store, the view config will be generated after checking for existence of obsm/<folder>.zarray, where <folder> is one of: X_pca, X_spatial, X_tsne, X_umap, X_segmentations and the contents of obs/.zattrs. We currently support only 'encoding-type' = 'dataframe' and 'encoding-version' either 0.1.0 or 0.2.0.

OME-Zarr format​

If you want to view data in OME-Zarr format, make sure that the URL to the dataset ends with .ome.zarr. For example:

Assumptions​

When generating the view config, Vitessce makes a couple of assumptions, depending on the file format:

OME-TIFF format​

For datasets of OME-TIFF format, Vitessce adds description, spatial and layerController view types by default. You can delete or adjust each of them using the editor. For the layerController, the sliders for each Channel are removed if RGB is detected. If you don't want this behavoiur, remove the following lines from the view config:

"props": {
    "disable3d": [],
    "disableChannelsIfRgbDetected": true
}

AnnData-Zarr format​

For datasets of AnnData-Zarr format, Vitessce adds a heatmap and a featureList view type whenever X is present. The heatmap is transposed by default. If you don't want it transposed, remove the following lines from the view config:

"props": {
    "transpose": true
}

Vitessce adds linked layerController and spatial view types when obsm/X_segmentations and/or obsm/X_spatial are present.

Vitessce adds one scatterplot view with embeddingType equal to t-SNE, PCA, or UMAP if obsm/X_tsne, obsm/X_pca or obsm/X_umap are present in the dataset respectively.

Vitessce adds an obsSets view whenever any of the following are present in obs:

  • cluster or cell_type;
  • leiden or louvain. You can generate these subgroups using the leiden or louvain scanpy functions;
  • cell_type, disease, organism, self_reported_ethnicity, tissue, sex, which are some of the conventions used in cellxgene.

OME-Zarr format​

For datasets of OME-Zarr format, Vitessce adds description, spatial, layerController and status view types by default.