Metadata-Version: 2.1
Name: omero-vitessce
Version: 1.0.1
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.3.0

![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 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 fully 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/b95c77a3-77c5-4221-83f2-c9c460a83f2e)  


- **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/5c81aba3-adfd-465c-86f0-9e03506ec3ea)  
  
#### 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)



### 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 the images are in the OME-NGFF format v0.4 and that [omero-web-zarr](https://github.com/ome/omero-web-zarr) is
available to serve the images.
The attachements must be 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:
- `Config file name`    (required, "VitessceConfig-YYYY.MM.DD_HHMMSS.json"): Name of the config file to attach, a ".json" extension is added if missing. 	
- `Image`               (required): 	                                       OMERO Image to view, OME-NGFF images only.
- `Segmentation`        (optional, `None`): 	                               Segmentation to overlay on the image, OME-NGFF images only.
- `Cell identities`     (optional, `None`): 	                               `.csv` file with at least 2 columns: `Cell id column` and `Label column` defined in the 2 fileds 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 with the `Cell id column` all other columns are considered as expression values and should be numerical.
- `Embeddings`          (optional, `None`):                                  `.csv` file with the `Cell id column` and the `Embedding x` and `Embedding y` columns defined in the 2 fileds 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 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 `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.  

#### 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 / 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).

Development
=======================

## Sources

The main sources are:
- omero-vitessce from Will Moore: 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

## 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.

