omero-vitessce 1.2.1

OMERO Vitessce multimodal data viewer plugin for OMERO.web

OMERO.omero_vitessce

OMERO-vitessce is an OMERO.web plugin for the Vitessce multimodal data viewer.

Installation

This section assumes that an OMERO.web is already installed.

Install the app using pip:

NB: You need to ensure that you are running pip from the python environment where omero-web is installed.

$ pip install -U omero-vitessce

Add the app to the omero.web.apps setting:

$ omero config append omero.web.apps '"omero_vitessce"'

Add omero_vitessce as a tab in the right-hand-side panel:

$ omero config append omero.web.ui.right_plugins '["Vitessce", "omero_vitessce/webclient_plugins/right_plugin.vitessce.js.html", "vitessce_tab"]'

Add omero_vitessce as an open-with option:

omero config append omero.web.open_with '["omero_vitessce", "open_vitessce", {"supported_objects": ["project", "dataset", "image"], "label": "Vitessce"}]'

Add the omero web address (replace ´'"http://localhost:4080"'´ with your address):

$ omero config set omero.web.omero_vitessce.serveraddress '"http://localhost:4080"'

Now restart OMERO.web as normal for the configuration above to take effect.

omero-web-zarr

While omero-web-zarr is not a requirement, but it is strongly recommended to have it installed and enabled for using this plugin omero-web-zarr is necessary to take advantage of the autogenerated config files for the Vitessce viewer, as they rely on omero-web-zarr to serve the images to the viewer.

Please see https://pypi.org/project/omero-web-zarr/ for instructions on installing and enabling the omero-web-zarr plugin.

Usage

Selecting the viewer

The plugin can be used with:

• Vitessce Tab on the right hand side panel.
• Open with -> Vitessce on the left side panel.

Right-hand-side panel:

• Prexisting config files:

Clicking the link will open a new tab with the viewer displaying the selected configuration.

• Generating custom config files:

The form allows the user to automatically generate a config file with the selected parameters. After clicking the Generate Config button a config file is generated and attached to the dataset/image. The viewer displaying the autogenerated configuration will open in a new tab.

Open-with:

Right click on a dataset or an images in the left-panel and select open-with -> Vitessce.
This will open the vitessce viewer in a new tab using the first configuration file attachement.

Viewer window

After autogenerating or selecting a config file, the Vitessce viewer is opened in a new tab:

The viewer panels can also be rearranged to better fit the image type/size.

Config files

The omero-vitessce plugin considers all files with the .json extension attached to the image or dataset as config files for the viewer. The config files should follow the vitessce view-config-json format: http://vitessce.io/docs/view-config-json/

Custom config files generated from the right-tab

Config files can be generated for:

• images
• datasets

Assumes that omero-web-zarr is available to serve the images. The attachements must be either OMERO.tables or files in.csv format and the column with the cell identifiers should be consistent across attachements. Only files attached to the dataset/image are available in the form.

The following fields are available:

• Save Config (required, True): Save the viewer configuration as an attahment to the current Image/Dataset before launching the viewer.
• Config file name (optional, "VitessceConfig-YYYY.MM.DD_HHMMSS.json"): Name of the config file to attach, a ".json" extension is added if missing.
• Images (required): OMERO Image(s) to view, assumes the same pixel size for all images.
• Segmentation (optional, None): Label image to overlay on the image, pixel values correspond to cell identities.
• ROIs (optional, False): Use the ROIs from OMERO as a cell segmentation. Assumes 1 polygon/rectangle shape per ROI, whose text value is the cell identity.
• Cell identities (optional, None): .csv file / OMERO.table with at least 2 columns: Cell id column and Label column defined in the 2 fields below.
• Cell id column (optional, "cell_id"): Name of the Cell id column used in Cell identities, Expression, Embeddings.
• Label column (optional, "label"): Name of the Label used in Cell identities.
• Expression (optional, None): .csv file / OMERO.table with the Cell id column all other columns are considered as expression values and should be numerical.
• Embeddings (optional, None): .csv file / OMERO.table with the Cell id column and the Embedding x and Embedding y columns defined in the 2 fields below.
• Embedding x (optional, "UMAP_1"): Name of the Embedding x used in Embeddings.
• Embedding y (optional, "UMAP_2"): Name of the Embedding y used in Embeddings.
• Molecules (optional, None): .csv file / OMERO.table with at least 4 columns: Molecule id, label, x, y (headers in the fields below).
• Molecule id (optional, "id"): Name of the Molecule id column used in Molecules.
• Molecule label (optional, "gene"): Name of the Molecule label column used in Molecules.
• Molecule x (optional, "x"): Name of the Molecule x column used in Molecules.
• Molecule y (optional, "y"): Name of the Molecule y column used in Molecules.
• Histograms (required , True): Add 3 plots showing: The number of transcripts per cell, the number of cells in each set, gene expression in each set.
• Heatmap (required , True): Adds an heatmap.
• Status (required , False): Adds a status panel to display info on the selected cell.
• Description (required , False): Adds a description panel to display info on the dataset/image (taken from the description metadata field from OMERO).

The Config file name field depends on the Save Config field. When the Save Config field is not checked, the Config file name field is disabled and its value ignored.
The ROIs and Segmentation fields are mutually exclusive, when the ROI field is selected the segmentation image is not considered.
The Expression and Cell identities files are required to show the histograms.
The Embeddings file is necessary to show the cells in a scatterplot.
The Molecules file is used to overlay molecules on the image. All molecules are displayed and selecting by gene is not yet possible.
The Status panel will be empty unless a Segmentation or Embeddings are provided.

The ROIs are used as cells. Only the first shape is considered, and only polygons and rectangles are kept (TO DO: add support for ellipses). Other shapes are skipped. The text value of the shape is used as a cell identity to link with expression/labels/embeddings, if there is no text value the ROI is skipped.

OMERO.tables for use with omero-vitessce can be generated with:

• OMERO python API (https://omero.readthedocs.io/en/stable/developers/Tables.html) or ezomero (https://thejacksonlaboratory.github.io/ezomero/ezomero.html#ezomero.post_table)
• Fiji (https://wiki-biop.epfl.ch/en/data-management/omero/omero-tables#create-omerotables-from-a-fiji-script)
• QuPath (https://wiki-biop.epfl.ch/en/data-management/omero/qupath#annotations-measurement-tables)
• other tools / APIs:

OMERO.tables with a number of rows > omero.web.max_table_download_rows (default 10000) will be truncated, and the value ignored by omero-vitessce.

Attaching preexisting config files

Custom config files should have a .json extension and added as attachements to a dataset or an image. The configuration files does not need to refer to the dataset / image it is attached to and can refer to other images.

For how to create a custom config file see:

• VItessce Docs
• Vitessce Examples

Serving the images / rois / data / metadata

Images and data can be served through:

• omero-web-zarr: OME-NGFF images only.
• omero-openlink: all images and file attachements.
• webclient/annotation/ endpoint: only for Annotations (useful for file attachments).
• webclient/omero_table/ID/csv?limit=MAX_TABLE_DOWNLOAD_ROWS endpoint (ID = OMERO file ID of the OMERO.table, MAX_TABLE_DOWNLOAD_ROWS = the OMERO.web setting): for getting OMERO.tables as csv files.
• omero_vitessce/vitessce_json_rois/ID1,ID2,... endpoint where ID1,ID2,... is a comma-separated list of image ids, to get the first shape of each ROI in json format.

Example showing ROIs from OMERO displayed in the omero-vitessce viewer window:

Development

Sources

The main sources this project relies on are:

• omero-vitessce from Will Moore for handling ROIs: https://github.com/will-moore/omero-vitessce
• cookiecutter-omero-webapp: https://github.com/ome/cookiecutter-omero-webapp
• react_webapp from omero-web-apps-examples: https://github.com/ome/omero-web-apps-examples/tree/master/react-webapp
• Vitessce python package used for generating config files http://python-docs.vitessce.io/
• omero-web-zarr to serve OME-NGFF images: https://github.com/ome/omero-web-zarr
• omero-openlink to serve images and other files: https://github.com/sukunis/OMERO.openlink
• omero-test-infra for testing: https://github.com/ome/omero-test-infra

Tests

Test dataset

The dataset used for automated testing is at: test/data/MB266 This is a cropped version derived from larger images and their associated data available at: https://doi.org/10.5281/zenodo.13832665

The original data are available at: https://www.ebi.ac.uk/biostudies/bioimages/studies/S-BIAD1093

The associated publication is available at: https://www.biorxiv.org/content/10.1101/2024.04.03.586404v1

omero-test-infra configuration

omero-test-infra is used for automated tests with github-actions. The workflow setups an omero installation in docker and then:

1. Runs app-config to set up the omero-web plugin configuration.
2. Runs app-build which:

• runs to create a test user/group and upload a test dataset.
• runs pytest tests in: test/integration

It is possible to perform these tests locally by:

1. Starting the docker daemon.
2. Cloning the omero-test infra repository inside the base folder of omero-vitessce: git clone https://github.com/openmicroscopy/omero-test-infra .omero
3. Running: .omero/app-docker

React web app

omero_vitessce web app

We serve a custom version of the vitesce app: http://vitessce.io/

The app sets up a vitessce view configured through a text file in json format: http://vitessce.io/docs/view-config-json/

The configuration file is taken from the ?config url parameter.

Installation

This project was created with Create React App.

You can run this project in development mode or as an OMERO.web Django app.

To get started:

$ cd vitessce_app
$ npm install

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

npm run build

Builds the app for production to the build folder and copies the html and static files to the Django app in vitessce app. See the deploy_build.sh script.

You also need to install the app into your omero-web environment:

# cd to the root of the repo
$ pip install -e .

You will need to have the app configured in your OMERO.web install:

$ omero config append omero.web.apps '"omero_vitessce"'
$ omero config append omero.web.ui.right_plugins '["Vitessce", "omero_vitessce/webclient_plugins/right_plugin.vitessce.js.html", "vitessce_tab"]'
$ omero config set omero.web.omero_vitessce.serveraddress '"http://localhost:4080"'

It bundles React in production mode and optimizes the build for the best performance.

See the Create React App section about deployment for more information.