Metadata-Version: 2.2
Name: omero-vitessce
Version: 1.2.4
Summary: OMERO Vitessce multimodal data viewer plugin for OMERO.web
Home-page: https://github.com/MicheleBortol/omero-vitessce
Author: Michele Bortolomeazzi
Author-email: michele.bortolomeazzi@dfkf.de
License: AGPLv3
Keywords: OMERO.web,OMERO,Vitessce,viewer
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vitessce>=3.4.2
Requires-Dist: shapely==2.0.7
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![Badge_OMERO](https://github.com/MicheleBortol/omero-vitessce/actions/workflows/omero_plugin.yml/badge.svg)
![Badge_PyPI](https://img.shields.io/pypi/v/omero-vitessce?label=pypi%20package)

OMERO.omero_vitessce
=======================

OMERO-vitessce is an OMERO.web plugin for the [Vitessce](http://vitessce.io/) multimodal data viewer. 

Installation
============

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

Install the app using [pip](https://pip.pypa.io/en/stable/):

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](https://github.com/ome/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.  
![Link-List-image](https://github.com/user-attachments/assets/7f556f86-7edf-49a0-bf2a-9c5f168922b1)

- **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.    
![Form-image](https://github.com/user-attachments/assets/6e9bbb79-6b40-4d5f-bb0f-48f7bc6a13f1)

#### 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.
![Openwith-image](https://github.com/user-attachments/assets/f75cc27c-4cd3-4a19-ae20-7d8f0a47aa87)

### Viewer window
After autogenerating or selecting a config file, the Vitessce viewer is opened in a new tab:
![Viewer GIF](https://github.com/user-attachments/assets/0f1effac-e681-4782-a69e-76702451fcbb)

The viewer panels can also be rearranged to better fit the image type/size.
![Viewer slide](https://github.com/user-attachments/assets/5c8c9559-ea2c-44c9-acbe-26caaf951432)

### 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](https://github.com/ome/omero-web-zarr) is available to serve the images.
The attachements must be either [OMERO.tables](https://omero.readthedocs.io/en/stable/developers/Tables.html) 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](https://omero-guides.readthedocs.io/en/latest/external_tools.html) / [APIs](https://omero-guides.readthedocs.io/en/latest/api_usage.html):

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](http://vitessce.io/docs/view-config-json/)
- [Vitessce Examples](http://vitessce.io/examples/)

#### Serving the images / rois / data / metadata
Images and data can be served through:
- [omero-web-zarr](https://pypi.org/project/omero-web-zarr/):  OME-NGFF images only.
- [omero-openlink](https://github.com/sukunis/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:
![ROI comparison](https://github.com/user-attachments/assets/807026b8-4ed2-4977-890b-73aa9c547ca2)

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](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](https://github.com/ome/omero-test-infra) is used for automated tests with [github-actions](.github/workflows/omero_plugin.yml).
The workflow setups an omero installation in docker and then:
1)  Runs [app-config](.omeroci/app-config) to set up the omero-web plugin configuration.
2)  Runs [app-build](.omeroci/app-build) which:
- runs to create a test user/group and upload a [test dataset](test/data/MB266).
- runs pytest tests in: [test/integration](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](https://github.com/facebook/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.<br>
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.

The page will reload if you make edits.<br>
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.<br>

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](https://facebook.github.io/create-react-app/docs/deployment) for more information.
