OMERO.figure¶

OMERO.figure is a popular tool for creating figures from Images in OMERO. Image metadata can be used to facilitate figure creation. For more information, see https://github.com/ome/omero-figure.

Contents:

Create figures using OMERO.figure¶

OMERO.figure is a web-based tool for creating figures from Images in OMERO. Image metadata can be used to facilitate figure creation.

Description¶

This guide covers:

Opening images in OMERO.figure to create a new figure
How to add additional images to an existing figure
Arranging panels in the desired figure layout
How to synchronize the rendering settings between panels
How to add scalebars, labels and ROIs to panels
How to save and export figures as PDF or TIFF

Setup¶

Install the OMERO.figure web app as described at https://pypi.org/project/omero-figure/

Resources¶

Sample images from the Image Data Resource (IDR) idr0021. See idr0021-data-prep.md for download and import instructions.
DV images from siRNAi-HeLa.
SVS ‘big’ pathology images from SVS.

Step-by-Step¶

Using the sample images above, we will create a figure like this, but you can use any multi-channel images.

In the webclient, select 6 images from the idr0021 Project.
In the right-hand panel, click the Open with… button and choose OMERO.figure:
This will open these images in OMERO.figure in a new browser tab.
Drag to arrange the Images approximately into two rows, select all (use Ctrl-A or drag to select) and click the snap to grid button at the top of the page.
Select all Images and Zoom in around ~300%, using the Zoom slider in the right Preview tab.
Go to the Labels tab, select all Images and add a Scalebar: Click the Show button, choose a length of 2 μm, click the Label checkbox and adjust the size of the Label to 12.
Add labels: choose Dataset Name in the label input dropdown list, choose color white and position=top-left.
Click Add to create the new label.
Add labels: choose Key-Value Pairs in the label input dropdown list, and in the following popup choose the Key which you want to add the value of from the dropdown menu.
Click OK in that dialog to create the new label.
Select one image. In the Labels tab, click the Edit button for ROIs.
If the image has ROIs in OMERO, click Load ROIs.
Mouse over the list to show each ROI on the Image and click to add it to the Image.
Click OK to close the dialog.
Return to the webclient tab, select the siRNAi-HeLa Dataset. N.B.: You may wish to filter the images when selecting those to add to your figure, e.g. Filter by Rating.
Select 3 images and in the right-hand panel click the link icon then copy the link.
Return to the OMERO.figure tab, click Add Image button and paste the link into dialog. Click OK.
Arrange the 3 images into a vertical column, select all and click snap to grid button.
Copy the 3 images and paste (keyboard shortcut or Edit > Copy/Paste) 3 times to create 3 more columns.
Select the panels in the first column and adjust the rendering settings: Turn only the first channel on and set the color to white.
Repeat for the next 2 columns: 1 channel turned on for each column, adjusting the levels if desired, leaving the 4th column as merged with multiple channels on.
Select all panels and zoom a little. Then select all the panels from one row and drag the image in the Preview tab to pan the selected images to the same point.
Copy and paste the merged column again to create a 5th column. Zoom in to approx 500%.
Select the Labels tab, select the merged and zoomed columns and click Show Scalebar button.
Click the Label checkbox to add a label to the scalebar. Select only the zoomed-in panels and change the scalebar to 1 micron.
Select the top-left panel and enter a label text in the Add Labels form. “Prometaphase” in the example above.
Set the label size (14), position (left vertical) and color (black) and click Add to create a label.
If we have Tags on the images, we can use these to create labels:
Select the first column of panels and choose Tags from the label text-field drop-down options. Click Add.
Select the first row of panels and create the labels in the top position using the Channels option to add Labels for active channels in each image.
Edit the created labels located at the bottom of the Info tab to rename the green labels to GFP-INCENP.
Select just the first merged Image and click the ROIs Edit button in the Labels tab.
Draw arrows or other shapes on the Image, or load ROIs from OMERO. Click OK to close the dialog.
Click Copy ROIs in the Labels tab, select the other panels in the same row and click Paste to add ROIs to these panels.
To create a Rectangle ROI indicating the region of the zoomed-in image, select the zoomed-in image on the first row and click Copy of the cropped region at the bottom of the Preview tab.
Now select the zoomed-out ‘merged’ panel, and paste this region as an ROI by clicking Paste under ROIs section of the Labels tab.
Repeat for other rows of the figure. At this point we have created the figure in the screenshot above.

Saving and exporting figures¶

Go to File > Paper Setup… and in the dialog that pops up choose Pages: 2. Click OK.
Finally return to the webclient, select ‘Big’ images from the svs Dataset, copy the link to them and paste it into the Add Image dialog in OMERO.figure.
Move the big images to the 2nd page.
In the header, click on the Save button to save the Figure as “Figure 1”.
The URL will update. You can bookmark this URL or share with collaborators to view your figure.
To open other saved files, go File > Open…
We can view figures from our collaborators here and filter by name or Owner.
Choose a figure to Open. For example the Aurora-B figure 2 from trainer-2.
Select a panel and click on the Webclient link in the Info tab to show the image in the webclient.
Back in OMERO.figure, go to File > Open… to choose the “Figure 1” file saved above.
Click on Export PDF to export it as PDF.
Download the PDF and open it. If opened in a suitable application e.g. Illustrator, the elements on the page will still be editable.

OMERO.figure scripting¶

Description¶

We can use Python scripts on the OMERO.server or JavaScript in the browser Console to create or modify OMERO.figures. These are experimental features and not documented elsewhere.

Setup¶

Install the OMERO.figure web app as described at https://pypi.org/project/omero-figure/
Upload the script Split_View_Figure.py to the OMERO scripting service
For the Shapes heatmap from OMERO.table example, you’ll need to draw ROIs on an Image and create an OMERO.table on the Image with a Shape column as described in the example.

Resources¶

For Figure creation in Python, any multi-channel images, e.g. from siRNAi-HeLa
For the Labels from Map Annotations example, any time-lapse images, e.g. FRAP.
For the other sections, any images can be used.

Figure creation in Python¶

OMERO.figure files are simply JSON data, stored in OMERO File Annotations with a specific namespace of omero.web.figure.json. We can create these files using Python scripts, uploaded to the OMERO.scripting service to make them available to all OMERO users.

The format of the JSON is described in the Format page. We will use the example Split_View_Figure.py script.

Select a few multi-channel Images in the webclient.
Click on the Script button in the top-right of the webclient and choose the Split_View_Figure.py script (e.g. under Workshop Scripts).
Choose a value for Row Labels input. The default is label each row with the Image Name, but you can also choose Tags as in the example below.
Run the script. When complete, open the OMERO.figure app and File > Open.
Choose the most recent figure, called “Split View Figure”.

Figure editing in JavaScript¶

To see the data model for any current file in OMERO.figure, go to File > Export as JSON….

You will see that the panels list defines the panels and each panel has attributes. For example, a panel with a single white label might include the following attributes:

"name": "image1.tiff",
"labels":[{"text":"label text","size":12,"position":"topleft","color":"FFFFFF"}],
"x": 200, "y", 200, "width": 100, "height": 100,
...many other attributes not shown...

The figureModel variable is accessible in the Console of the browser Developer Tools. The easiest way to open the developer tools in most browsers is to open the context menu (right-click) anywhere on the page and choose Inspect.
We can use figureModel.getSelected() to get selected panels and for each panel we can call p.set() to change an attribute.
For example, to set the height of several panels to 200, we can select the panels in the figure UI and paste this code snippet in the Console:
```
figureModel.getSelected().forEach(function(p){
    p.set('height', 200)
});
```
There are several JavaScript examples in the scripts folder. Many of these are quite simple and self-explanatory. Below are some more complex examples that require specific set-up steps.

Example 1: Labels from Map Annotations¶

We will use the time-lapse images listed above to create a FRAP figure but you can use any time-lapse images.

We can use AJAX to load JSON data and we will use p.add_labels() to create labels.
In this example we will load the FRAP intensities from the Map Annotations on these images.
Select 2 FRAP images that have previously been analysed to create a Map Annotation with the namespace demo.simple_frap_data.
Alternatively, you can add your own Map Annotation with each Key being a T-index (start at 0), and the Value will be a FRAP intensity (number).
Create a Figure with 2 images.
Copy and paste each image several times and increment T-index in the Preview panel to show multiple time-points per image.
Open the browser console by right-click > Inspect Element (Firefox) or right-click > Inspect (Chrome) and click on the Console tab.
Copy the code from figure_frap_mapannotation_label.js <https://github.com/ome/omero-guide-figure/tree/master/scripts/figure_frap_mapannotation_label.js>.
Drag to select the FRAP movie images in the figure.
Paste the code into the console. Do not hit enter yet.
Inspect the code. It will iterate through each of the selected panels, an AJAX call is made to load the Map Annotations with the namespace that we created from FRAP values above.
NB: If you manually created your own Map Annotation above, you can remove the line url += '&ns=' + ns; to avoid filtering by namespace.
The FRAP values are a list of [key, value] pairs and we can get the value for the current T index of the panel with values[theT][1] and use this to create a label.
Hit Enter to run the code on selected panels.
The labels should be added. Note that you can undo and redo these changes in the UI as normal.

Example 2: Shapes heatmap from OMERO.table¶

This example uses an OMERO.table linked to each Image to generate a heatmap of colors applied to Shapes on the figure panel.

Setup:

If you wish to use Images and table data from idr0079, see the setup steps at idr0079-data-prep.
Alternatively, perform the following steps:
For the Image you wish to use, add some ROIs to the Image. You can see the ROI and Shape IDs in the iviewer ROI table.
To setup the OMERO.table, create a CSV file with an Roi column and a Shape column containing the corresponding IDs and 1 or more number columns. The #header defines the column types: l (long) for integers and d (double) for floats. For example:
```
# header roi,l,d,d,l
Roi,Shape,Area,Sphericity,Pixels
1,10,34.5,0.5,110
2,11,18.2,0.6,55
2,12,44.1,0.9,210
```
Save the edited csv as data.csv.
With omero-metadata installed on the command-line, we can create an OMERO.table on the Image, using the Image ID:
```
$ omero metadata populate Image:123 --file data.csv
```

OMERO.figure steps:

In OMERO.figure, add the Image to the figure, then in the ROIs dialog, load the Shapes from OMERO and add them to the panel. The JSON data for each Shape will have an id that corresponds to the Shape in OMERO.
View the JavaScript snippet at figure_table_data_shapes.js. This uses the ID of each Shape of the panel to query the most recent OMERO.table on the Image using the endpoint: /webgateway/table/Image/{imageId}/query/?query=Shape-{shapeId}, which returns all table rows for that Shape ID. From the JSON returned, we find the column index for the data we want, e.g. Sphericity, and then get the value for that column. Once the values for all Shapes on the panel are loaded, the code calculates the range and generates a heatmap color for each value in that range. This is set as the color on each Shape.
Select the panel in the figure, then paste the JavaScript code into the browser Console and hit Enter
In the screenshot below, Shapes in the first panel are colored according to the Centroids_RAW_X column and Shapes on the lower panel are colored according to the Sphericity column. Images in this example are from idr0079.

Move Figures between Groups¶

Moving Figures between Groups in OMERO might be necessary for example in cases where a scientist decides to move their data into another Group to enable cooperation and viewing by other colleagues or to make the data public.

As with all data in OMERO, Figures belong to a particular Group and are visible only to members of that Group. Figures can contain Images from the same Group as the Figure or from any other Group. Figures and the Images they contain can be independently moved from one Group to another but should ideally be kept in the same Group. This avoids the situation when a user can view a Figure, but not the Images within it.

This walkthrough offers two alternatives for getting Figures into another Group, either with or without duplicating the Figures and the Images contained in them.

Description¶

This guide covers:

Moving of Figures and Images between Groups.
Duplicating of Figures and Images into a new Group.

Setup¶

Install the scripts Figure_Images_To_Dataset.py and Dataset_Images_To_New_Figure.py on your OMERO.server.
We suggest in this workflow the installation under a folder Figure scripts but you can install the script in any folder.
See server-side script guides for further details.

Resources¶

Any Images and Figures created from these Images.

Step-by-Step¶

Moving of Figures and Images between Groups¶

This workflow assumes that you have an OMERO.figure already created and want to move this Figure into another Group.

Log in to OMERO.web.
Click on Figure link above the central pane to get into OMERO.figure.
Inside OMERO.figure, click File > Open and open the Figure you wish to move to another Group. Copy the last part of the url from the address bar of your browser, which contains the Figure ID, e.g.:

https://your-omero-server.org/web/figure/file/79828

has the Figure ID 79828. The Figure ID will be needed later in case you also want to collect and move the Images contained in the Figure as described below.
Click File > Move Figure to Group.... In the following dialog, select the Group you wish to move the Figure to and click OK.
Observe a dialog reporting a success of the move. Verify that when you now again click File > Move Figure to Group... the Figure is now reported to be in your intended Group.

Note

You might want to move the Images contained in the Figure to the other Group as well. This step is optional, if you want to use your Figures by yourself only, but you should consider it in case the users you want to share your Figure with do not have permissions to see your Images in the original Group (for example they are members of the target Group only).

In the following steps, we first collect all the Images in the Figure into a single Dataset to enable moving them to the target Group in a single step.
Go back to the tab with OMERO.web, create a new Dataset and select it.
Click on the Scripts icon above the central pane of OMERO.web. Select Figure scripts > Figure Images to Dataset. Start the script and in the dialog, enter the Figure ID into the Figure IDs field. If you wish to work with multiple Figures, IDs can be separated with commas, e.g. 79828, 79830, 71228. Click Run.
When the script finishes, refresh the page and find the Images contained in your Figure linked to the Dataset. Note that the Images are linked to the chosen Dataset without removing them from any existing Dataset. They will be doubly-linked but not duplicated.
The above means that when you execute the Move into another Group, the Images in your Dataset will no longer be available in the original Group.
Move the Images into the Group you have moved the Figure to. Be sure to select the Images in OMERO.web when moving, not the Dataset. If the Dataset is selected, the Images are left in the original Group, and only the empty Dataset is moved. This is because the Images are linked to the original Dataset which is left in the original Group. Follow the Move workflow to execute the Move. The Move will enable any member of the target Group to view both the Figure and the Images within it.

Duplicating of Figures and Images into a new Group¶

If you wish to keep your Figures and the contained Images in their original Group, while also making them available to users in another Group, you can duplicate them as described below.

In this workflow, we first duplicate the Images within one or more Figures. Then move these Images to the target Group.

Finally, using a script, we copy the Figure into the target Group, replacing the Images within it with the duplicated Images.

Note that this workflow involves usage of Command Line.

Collect the Images contained in the Figures into a single Dataset using the workflow Moving of Figures…. For this, you can find out the Figure IDs either manually as described in the Moving of Figures… or by running hql queries on the command line, such as:
```
$ omero hql --all --limit 1000 --style plain --ids-only  "select f.id from FileAnnotation f where (f.details.group.name = 'Lab1' and f.details.owner.id = 454)" | sed -e 's/^.*,//g' | paste -s -d, -
```
which will retrieve all the Figure IDs of user with ID 454 in a Group Lab1 in a format which you can immediately copy and paste into the Figure Images to Dataset script.
Start your command line terminal and duplicate the Dataset with the Images contained in the Figures as described in the Duplicate workflow.
Go to OMERO.web, select the duplicate Dataset and Move it to the target Group. For that, follow the Move workflow.
Find the Dataset which you have just moved and select it.
Click on the Scripts icon above the central pane of OMERO.web. Select Figure scripts > Dataset Images To New Figure.
Start the script and in the dialog, enter the Figure ID into the Figure IDs field. If you wish to work with multiple Figures, IDs can be separated with commas, e.g. 79828, 79830, 71228. Click Run. This will copy each specified Figure, update the Images within it to those in the duplicate Dataset (using the Image name to match the replacement Images) and save the Figure to the new Group.
Click on Figure link above the central pane to get into OMERO.figure.
Inside OMERO.figure, click File > Open. In the top-right corner of the new dialog, click on the Group dropdown and select your target Group name. Verify that the list contains the newly created Figures.

Contribute¶

Changes to the documentation or the materials should be made directly in the omero-guide-figure repository.