General Introduction

This section covers the general concepts of OMERO. Those concepts are demonstrated using the Web client. This section introduces the data management functionalities of OMERO, shows how to annotate data and demonstrates how to search for data and metadata. Also, the management of groups and users is presented, both in the Web client as well as on the command line.

Contents:

Data management and cooperation

In this document, we introduce the basic concepts of data management, such as browsing, navigating to others’ data, and changing the display of the images in OMERO. The example here uses OMERO.web, but majority of the features described here are also present in OMERO.insight.

Further, we show how to use the Command Line Interface (CLI) for data management, introducting mainly the features which are not present in the OMERO.web.

Description

We will show:

• How to browse data in OMERO.web, navigating to yours and other users’ Images.
• How to use the basic layout of OMERO.web for Images organized in Projects and Datasets.
• How to use OMERO.web for viewing of High-Content Screening (HCS) data.
• How to use the Preview panel.
• How to adjust the rendering settings of your and other users’ images from the Preview panel.
• How to organize Images in Projects and Datasets.
• How to move the data between groups if you are data owner.
• How to move the data between groups if you are an administrator working on behalf of others.
• How to change the ownership of objects.
• How to use Command Line for duplicating objects such as Images, Datasets or Projects.

Setup

OMERO.server has been installed and provisioned using an Ansible playbook.

Resources

• All data have been pre-imported. For more details, look at data.md.
• For the HCS data screenshot, the IDR data https://idr.openmicroscopy.org/webclient/?show=run-5403 were used.
• To import Images and metadata, see the maintenance scripts for more details.
• For import of Images, we use in_place_import_as.sh.
• The cooperation in OMERO is described in Groups and permissions system.
• See also the documentation for Moving objects between groups and Changing ownership of objects using the Command Line Interface.

Step-by-Step

Data layout and ownership, usernames (when running a workshop)

All Images have been pre-imported into the OMERO.server. For training purposes, we prepared 50 users on the OMERO.server. Each of these 50 users has their own set of Images. These sets consist of Images of the same name, size, shape, form and quality for each user. Thus, the data of each user appears the same but, in actual fact, are different and totally independent sets. Thus, small discrepancies and differences between the users are completely possible. Further, if one user deletes their own data in OMERO (please do not delete anything on our server), this will not have any bearing on the other 49 sets of Images belonging to the 49 other users.

The login names of the 50 users are “user-x” where x goes from 1 to 50. We have given to each of the 50 users in OMERO a unique first name and surname which we picked from a list of 50 famous scientists e.g. Ada Lovelace or Francis Crick. This is the name (“your” name) which you will see in the top-right corner of the OMERO webclient after you log in with your loginname.

In the OMERO webclient the default view shows only your own Images.

Browsing and rendering

1. In your web browser, go to the server address provided.

2. Log in using the username and password provided.

3. OMERO offers various levels of permissions for groups and users. Depending on the permissions level of each group, a given user might be able to view, annotate or edit data belonging to other users. Permissions are managed by users with admin privileges. To highlight some of the collaborative aspects of OMERO, we will use a “Read-Annotate” group. This implies that users can view and annotate each other’s data but cannot delete other people’s data.

4. To see other people’s data, click on the (for example Lab1) group name in the top-left corner of the webclient. Note that in case you are in a differently named group, the name in the top-left corner will accordingly reflect this. Then use the menu to select the name of the group you wish to browse and then the user inside that group whose data you wish to see.

   

5. You can browse ‘folders’ in the left-hand pane: Image folders are called Datasets and they are within Projects.

6. When a Dataset is selected, Image thumbnails are shown in the centre panel.

7. These represent imported Images. The original Images are stored on the server and the generated thumbnails allow us to browse them.

8. Bio-Formats is used to read the pixel-data and metadata from over 150 different Image formats, including multi-z timelapse Images with many channels, they are referenced as 5D Images. Large pathology and medical Images are also supported.

9. For HCS data, the layout of the OMERO.web is a bit different. The HCS data are usually organized in following manner:

   • Images are contained in Wells.
   • Wells are contained in Plates.
   • Plates are organized in Screens.
   • A Plate may or may not contain several Runs.
   • The screenshot below shows the typical layout of a Plate in OMERO.web, where the Wells are organized in rows and columns. The Plate contains one Run. One Well is selected in the central pane and it contains four Images whose thumbnails are displayed below the central pane. The bottom-left corner shows the positions of the Images (called Fields in this context) inside that Well.

   

10. Select an Image. In the right-hand pane, metadata read by Bio-Formats and stored in a relational database is displayed:

    • Core metadata in the General tab.
    • Additional metadata in the Acquisition tab.
    • All the metadata read by Bio-Formats can be downloaded at any time.

11. In the Preview tab in the right-hand panel, you can also view the Image.

12. For multi-plane Images, sliders allow you to move through Z or Time dimensions.

13. Viewing Images does not download the whole Image to the client. Only the viewed Image plane is rendered from the original Image file on the server and sent back to the OMERO.web client.

14. You can adjust the rendering settings for each channel e.g. turn on/off the channels, adjust color settings, look-up tables, etc.

15. The rendering settings can be saved to the server. This never changes the original Image data and can be reverted at any time.

16. The rendering settings can also be copied and pasted between Images. To modify the rendering settings in batch, click on the Save to All button to apply the same settings to, for example, all Images in a given Dataset.

17. You can use the settings which other users saved on your Images and apply them for your own Image. These settings are highlighted as thumbnails in the lower part of the Preview pane.

    

18. Your own settings are highlighted in blue.

19. You can revert to the original settings for an Image or Dataset. For example, using the context menu for a Dataset in the tree, select Rendering Settings > Set Imported and Save.

20. Stay in General tab of the right-nand pane and adjust the channel names:

    • Select any image inside that Dataset and click on the pencil icon in the right-hand pane next to Channels.
    • Input “DAPI” instead of channel “457” and “GFP”, “Aurora-B” and “CY-6” for the other channels.
    • Click the Apply to All button and confirm by clicking Continue. This will change the channel names of all the images in that Dataset.

Manage Images in Datasets/Projects

You can organize the data in the left-hand side tree by creating new Projects and Datasets. You can link the Images to the new or existing Datasets and Datasets to new or existing Projects. For HCS data, you can create new Screens and link Plates to these Screens.

1. Use the Project and Dataset icons above the left-hand side tree or the right-click contextual menu to create new Datasets or Projects.

2. Drag and drop Images between Datasets and Datasets between Projects. For HCS data, drag and drop Plates between Screens.

3. Copy Images using the right-click context menu:

   • Select the Images to be copied, then right-click and click Edit > Copy Link.

   • Select the Dataset you want to copy the Images to, right-click and click on Edit > Paste Link.

     

Warning

The Copy Link feature will only create new links between an Image and a Dataset, so that one Image becomes linked to multiple Datasets. This does not create a new independent copy of the Image. The only way to create a fully independent copy in OMERO is to use the Duplicate feature.

If you delete one of the Datasets, any Images within it that are linked to other Datasets will be retained. Nevertheless, if you directly select and delete an Image that has been copied from another Dataset it will be deleted and lost from both Datasets. There is a clear warning in the OMERO.web when you try to delete such a doubly linked Image, see screenshot below.

Note

Organizing data of other users as an administrator, restricted administrator or group owner is made easier in OMERO.web in the following manner.

If you are an administrator or administrator with restricted privileges working in a group you are not a member of, except for private groups where this workflow is not possible, all containers (Projects, Datasets, Screens) created in OMERO.web in such a group will belong to the user whose portfolio you are working with.

Changed in version 5.8.0: Also the links between the containers and their content will belong to that user. In case there are different owners of the container and of the linked content, then the created link will belong to the owner of the linked content.

This helps to retain the possibility for this user to manipulate their containers even though you created them.

Nevertheless if the workflow is executed by a group owner (i.e. not an administrator), the new links will belong to the group owner and the user will not be able to unlink the objects later. This is a current limitation.

Move data between groups

In OMERO, Users are organized in Groups. The Groups allow a level of viewing and cooperation between the members of the group which can be adjusted by changing the permissions level on that group. A User can be a member and have their data in one or more Groups. Thus it is sometimes necessary to move the data between groups. This action can be done by the owners of the data themselves or by an administrator or an administrator with restricted privileges.

Note that caution has to be taken in case the data are linked to other users’ containers (Datasets, Projects). If you move only the contents of those containers (Datasets or Images) and not the containers themselves (Projects or Datasets), the links between such containers and the Images or Datasets which are moved will be deleted.

Further, if any objects are moved, the links to any annotations such as Tags or attached File annotations linked to these objects will be deleted in case these annotations belong to others or in case these annotations belong to you but are also linked to some other objects in the original group which are not being moved.

If you want to retain a copy of your data in its current position, then you should Duplicate it first. The Duplication also bypasses the unlinked annotations problem highlighted in the previous paragraph. Because the Duplicate feature creates new objects, which are not dependent on the originals, the relationships between these duplicates are then preserved even during a subsequent move to another group.

Note that except for using OMERO.web described below, it might be worth in some situations to consider moving data between groups using the Command Line Interface see CLI Moving Objects between Groups.

Move data between groups: owners of data

If you are an owner of the data, you can move the data between the groups you are a member of.

1. In OMERO.web, select the data to be moved in the left-hand side tree.

2. Right-click and select Move to Group....

   

3. Select the group you want to move the data to.

4. A message Checking which linked objects will be moved will appear and a spinner to the left of it. Wait until the spinner vanishes and a list of objects to be moved and a list of objects which are not included in the move appears.

   

5. Check both lists. Please read the note above about which objects are typically not included and reconsider the Move action. The not included objects will not be linked to the Moved objects anymore if you go ahead with the move, the linkage will be lost.

6. In case you are happy with the Move``action to go ahead, select a target Dataset or Project or create a new one and click ``OK.

Move data between groups: administrators

The administrators can move the data to any group, not only to the group where the owner of the data is a member. Note though that it is not desirable to create a situation where the data belong to someone who is not a member of the group where the data reside.

Typically an administrator works on behalf of other users in a group where the administrator is not a member. For these cases, some features of OMERO.web help to facilitate the moving of data for others (note that these features are not yet available in the Command Line Interface).

1. Navigate to the data of a user in a group that you are not a member of.
2. Select the data in the left-hand tree.
3. Right-click and select Move to Group....
4. Follow further the steps described in the section Move data between groups: owners of data, taking note of the Not included objects.
5. When creating new Datasets or Projects during the move, note that these containers will belong to the owner of the data, not yourself. Also the links between the new containers and the moved data will belong to the owner of the data. This should help to facilitate a smooth workflow, retaining data-handling possibilities such as reorganizing the data, renaming the containers you created for them etc. for the owner of the data.

Change ownership of data

Every object in OMERO has a single, particular user as an owner. The ownership of objects can be changed but only if you are an Administrator, Administrator with restricted privileges or a Group owner.

There is also a possibility of changing ownership of objects using the Command Line Interface. The Command Line Interface implementation contains some features not present in OMERO.web.

1. Select a Project, Dataset or Images in the left-hand side tree of OMERO.web.

2. Right-click and in the context menu, select Change owner.

3. In the new dialog, select the new owner of the data.

4. Wait until the Checking which objects will be moved is done and the spinner vanishes. This might take time depending on the number of objects you are attempting to change owner of. For example, a large number of ROIs on the images can be a cause of longer waiting times.

   

5. Check the list of objects which are supposed to be transferred to the new owner. Also consider the possible loss of linkage between objects listed in the Will be removed from line.

   

6. Click OK.

7. Observe the Activities item above the central pane of OMERO.web and wait until the change of ownership is finished.

   

8. The Activities item will stop showing a spinner and a link to the data you have just changed the owner of will appear. This link will help you to find the data you just changed the ownership of. This data will be shown as a part of the tree of the new owner in the OMERO.web interface, and are now removed from the old owner tree.

   

9. Click on the link Show ... in the Activities and inspect the data you just transferred the ownership of.

Command Line: Duplicating objects

You can duplicate objects in OMERO. The functionality is available only on the CLI for now. The duplication creates a full copy of the objects as if they were created independently. When desired, the newly duplicated objects can additionally be linked to other objects. When the duplicate is later deleted, it will not have an influence on the original, which stays preserved. Similarly, when the original is later deleted, the duplicate stays preserved as well.

In case of Image objects, which have image files linked, the duplication creates a new image file which is linked to the original image file by a hard link when possible. This means every duplication of an Image increases the number of hard links on the image file in OMERO.server’s Managed Repository, but does not duplicate the image file itself, and thus does not increase the storage demands too much, except for rare cases where the linking is not possible. If creation of the hard link is not possible, the Image duplication will still proceed, creating a full new image file copy.

In case of File Attachment objects though, which also have files to them, each duplication will duplicate the linked file, thus doubling the storage space necessary for these File Attachment files.

Use this Duplicate feature to replace the discontinued Shares feature.

Resources

• Necessary software versions:
  • OMERO.server 5.6.3 or later
  • omero-cli-duplicate plugin 0.4.0 or later
• Documentation:
  • README of the omero-cli-duplicate repository
  • Application Programming Interface documentation
• Plugin for duplication on Command Line:
  • omero-cli-duplicate on PyPI

Setup

Duplicate plugin installation

• Go to the environment where you installed your OMERO.cli as specified under Installation.

• Activate the virtual environment where omero-py is installed or add it to PATH e.g.:

  $ export PATH=/opt/omero/server/venv3/bin:$PATH
  

• Run:

  $ pip install omero-cli-duplicate
  

Step-by-Step

1. On your local machine, open a terminal

2. Activate the virtual environment as indicated in the Setup section above.

3. The variables $ID​1 and $ID2 below are the IDs of the ​selected Datasets. To duplicate two Datasets with their Images and annotations on both the Images and the Datasets, run:

   $ ​omero duplicate Dataset:$ID1,$ID2 --report
   

4. The duplicated Datasets will not be linked to any Project, even if the originals were linked to some Project.

5. Duplicate two Images with many ROIs on them. The ROIs duplication might take a long time. To exclude the duplication of the ROIs, run:

   $ omero duplicate Image:$ID1,$ID2 --ignore Roi --report
   

6. Find the duplicated Images in the Orphaned Images and Drag and Drop them into a Dataset or create a new Dataset for them.

7. Duplicate two Projects of another user in read-annotate group type. This will duplicate also the Datasets linked to those Projects as well as Images linked to those Datasets. Here we specify some classes of objects that we do not want to duplicate (reference-classes), even though they are linked to the objects we are duplicating. Instead, the duplicated objects will be linked to these reference-classes of objects. We can also specify classes that we explicitly do want to duplicate using the duplicate argument. In this example, we specify all Annotations as reference-classes, but a subset of these (Comments and LongAnnotations such as Ratings) are duplicate-classes. This means that the duplicated Projects will be linked to the original annotations such as Tags, Key-Value pairs and FileAnnotations, but Comments and Ratings will be duplicated. This can be useful to ensure that a single Comment is not attached to multiple objects which might cause confusion when the Comment is edited. Also it prevents a loss of link between the Comment and an object in case that object gets moved into another group after the duplication. The duplicated Annotations and the two Projects with the linked Datasets and Images will belong to the current user (user-1), even if all the original Annotations may belong to other users in the read-annotate group. Run:

   $ omero logout
   $ omero login -u user-1 -g read-annotate-group
   $ omero duplicate Project:$ID1,$ID2 --reference Annotation --duplicate CommentAnnotation,LongAnnotation --report
   

8. Duplicate two Projects of another user in read-only group type. The group name in our example below is read-only-group. If the duplicator is not an administrator, administrator with restricted privileges or group owner, they cannot link the annotations of another user to their duplicate in a read-only group. They might duplicate all the annotations (this is the default behaviour) or exclude the duplication of all the annotations by excluding the Link duplication to the relevant objects as shown below. Run:

   $ omero logout
   $ omero login -u user-1 -g read-only-group
   $ omero duplicate Project:$ID1,$ID2 --ignore IAnnotationLink,Roi --report
   

Note

You must log in to the group where the data are, either by virtue of this group being your default group or by using the -g flag as shown in the examples above, otherwise the omero-cli-duplicate plugin will not find the data. This is a current limitation.

If you intend to move the duplicate into a different group, it is recommended that you duplicate the annotations as well. If you link the annotations from other objects to your duplicates, the link might be deleted during the subsequent move of that duplicate to another group.

Shares (discontinued feature)

Previously created Shares can still be viewed in the Shares tab above the left-hand side pane of OMERO.web. Nevertheless, the Shares feature is discontinued. It is not posssible to use the World icon above the left-hand pane in OMERO.web to create new Shares anymore. Shares are discontinued in OMERO.web 5.9.0 and later. You need to use the OMERO standard permissions to share Images, by moving the data into the appropriate group. If you also want to retain the Images in their current group, you can first duplicate them as described in Duplicate feature. Nevertheless, this Duplicate and Move workflow has following limitations:

• Duplicate is only available on the Command Line Interface (CLI)
• You need to already be in a non-private group with the user you wish to share with
• You will also be sharing the data with all the other members of that group

Note

Shares were never supported by OMERO.iviewer. If OMERO.iviewer or other viewer which does not support Shares is installed on your server and is set as a default viewer, then users with permissions to access the data in the Share cannot view images in any Full viewer.

Annotate Data and Filter using Annotations

There are several ways to add annotations to objects in OMERO. Here, addition and filtering of annotations using OMERO.web is described. You can add annotations using the OMERO.web interface to any object(s) that you can select in the left-hand-side tree or central pane, this means Project, Dataset, Image, Screen, Plate and Well.

Description

We will show:

• How to annotate Images, Datasets and Projects with:

  • Tags
  • Key-Value Pairs
  • File Attachments
  • Ratings

• How to filter thumbnails in the central pane of OMERO.web for:

  • Tags
  • Key-Value Pairs
  • Ratings

Setup

• The data used are from the siRNAi-HeLa folder.
• The tags and ratings were added manually, then propagated for all users on the OMERO.server using the script copy_tags_ratings.py.
• The Key-Value Pairs were added to the images in the siRNAi-HeLa Dataset for all users using the script key_value_pairs.py.

Step-by-step

1. Open a browser and enter the provided URL

2. Connect using the provided credentials

3. First, we will add Tags to indicate Metaphase stages of these cells.

   • Select one or more Images in the siRNAi-HeLa Dataset of cells which appear to be in metaphase.
   • Choose the Tag harmonica in the right-hand General tab and click [ + ] to launch the Tag dialog.
   • Choose the existing Metaphase tag from the list of Tags (to filter, type above the list).
   • Click > to move it to the right column, then click Save.

4. Let us now add Key-Value Pairs

   • Select an Image from the Dataset and in the right-hand pane in General tab, click the harmonica Key-Value Pairs.

     

     

   • The Key-Value Pairs allow you to add lab-book-like additional metadata for the Image. These Key-Value Pairs are also specifically searchable. See Search for Data.

5. For adding of File Attachments:

   • Select one or more objects in the left-hand side tree, such as Dataset or Image.

   • Expand the Attachments harmonica in the right-hand pane.

   • Click the plus button.

     

   • You can attach any type of file using this function. If you select a file from your local filesystem using the Browse button, the feature will upload that file to the OMERO.server and save it there. The content of .pdf, CSV and plain text files is also searchable in OMERO.

6. Remove a File Attachment.

   • Find the File Attachment you have just added.

   • Click on the minus sign to the right of it.

     

   • The removal action just unlinks the File Attachment from the selected object(s). The File Attachment is not deleted from the server. If deletion is needed, click in the workflow above on the cross icon instead of the minus icon.

7. You can also add Comments and Rating to selected objects - follow analogous steps to the ones descirbed above for Tags, Key-Value pairs and File Attachments.

8. Filter using annotations

   • Images can also be filtered by Name, Tag, Key-Value pairs or Rating in the centre pane, using the Add filter chooser above the thumbnails.

   • For example, choose Tag and then select Metaphase from the list of Tags to show the images we tagged earlier.

   • Or choose to filter by Key-Values. You can then filter by a particular Key. If you select a Key where all the values are numbers, you can filter for those that are greater than, less than or equal to a threshold value.

     

   • Review the filtered Images, choose a favourite Image and under the Ratings section in the right-hand pane, click on the 5th star to add a rating of 5

     

   • Now we can remove the filtering by Tag and instead filter by Rating of 5 to show only our favourite images.

Search for Data

In this section, we present the server-wide search in OMERO. This is an additional option for data management, which complements filtering, mining and using annotations to organize your data, which are described elsewhere in Annotate Data and Filter using Annotations.

Description

We will show:

• How to start a search in OMERO.web.
• How to search for objects annotated with a specific Key-Value Pair.
• How to use Advanced Search.
  • How to search for terms in specific fields e.g. “name”.
  • How to combine search terms using AND.
  • How to combine search terms using AND NOT.

Resources

• Documentation:
  • Search

Setup

• The data used are from the siRNAi-HeLa folder.
• The Key-Value Pairs were added to the images in the siRNAi-HeLa Dataset for all users using the script key_value_pairs.py.

Step-by-Step

1. Open a browser and enter the provided URL
2. Connect using the provided credentials
3. Enter mitomycin-A into the search box in the top right corner of the webclient
4. Press Enter.
5. The search results will show any objects e.g. Images or Datasets, which have anywhere the string mitomycin-A.
6. Several images should be found.
7. Refine the search now for only Key-Value Pairs which have the key mitomycin-A and value 0mM by entering mitomycin-A:0mM into the search box and pressing Enter.
8. This should narrow down your search and find less results compared with the previous case.
9. Click on the Browse link in one search result line of the last image (in the right-hand part of the centre pane) to navigate back to the main webclient.

Advanced search

The Advanced search in OMERO.web gives the opportunity to construct queries with Lucene syntax. These queries will be sent into the OMERO search (which is based on Lucene) unparsed. The possibilities include using logical operators (AND, OR, NOT, see workflow below) or fuzzy search (see Search Examples below).

1. Still on the search results page, click on the Advanced tab in the upper part of the left-hand side pane.

   

2. Enter mitomycin-A:0mM AND name:VRAQ which will narrow down your previous search for mitomycin-A:0mM to objects which also have VRAQ in their name.

3. Enter mitomycin-A:0mM AND NOT name:VRAQ which will reject all objects which have VRAQ in their name and find only the ones which are named differently.

Note

Spaces, stars, question marks and ^ characters are to be avoided in the Keys. If you already have these characters in Keys in your OMERO server, then try to replace them with underscores if you want to use the Search functionality on them. Spaces, stars, question marks and ^ characters in Values are acceptable, but should be avoided if possible, see Search Examples below.

Search examples

Considering the following setup of 13 separate images:

Images with Key-Value pairs

Image ID	Image Name	Key	Value
1	Aurora1	GFP H2B	2 uM
2	Aurora2	GFP^H2B	2 uM
3	Aurora3	H2B	2
4	Aurora4	H2B	4
5	Aurora5	GFP-H2B	2-uM
6	Aurora6	GFP-H2B	2 uM
7	Aurora7	GFP_H2B	2_uM
8	Aurora8	GFP^H2B	2^uM
9	GFP	none	none
10	uM	none	none
11	H2B	none	none
12	2	none	none
13	Aurora13	H2B	2 uM

Basic Search tab:

• GFP H2B:2 uM finds images 1,2,3,5,6,7,8,9,10. In that case, the query is interpreted as GFP OR H2B:2 OR uM.
• "GFP H2B":2 uM throws an error. Do not use quotes around Keys!
• GFP H2B:"2 uM" finds images 1,2,5,6,7,8,9. In that case, the query is interpreted as GFP OR H2B:2 uM which prevents finding of image 3 with Value 2.
• GFP^H2B:2 uM finds images 1,2,3,5,6,7,8,9,10. In that case, the query is interpreted as GFP OR H2B:2 OR uM.
• H2B:2 finds image 3.
• H2B:4 finds image 4.
• GFP-H2B:2 uM finds images 1,2,5,6,7,8,10.
• GFP-H2B:2-uM finds images 5,6.
• GFP-H2B:"2-uM" finds images 5,6.
• GFP-H2B:"2 uM" finds images 5,6.
• GFP-H2B:"2_uM" finds images 5,6.
• GFP_H2B:2_uM finds image 7.
• GFP^H2B:2^uM finds images 1,2,3,5,6,7,8,9,10.
• GFP finds images 1,2,5,6,7,8,9.
• GFP with checkbox Name under Restricted by Field section checked finds image 9.
• uM with checkbox Name under Restricted by Field section checked finds image 10.
• H2B with checkbox Name under Restricted by Field section checked finds image 11.
• 2 with checkbox Name under Restricted by Field section checked finds image 12.
• GFP*:2 uM throws an error. Do not use wildcards in Keys!
• H2B:* finds images 3,4,13. The wildcard can be used in Values.
• H2B:2* finds images 3,13.

Advanced tab:

• GFP^H2B:2^uM and GFP^H2B:2 uM throw an error in Advanced tab. This is due to the different interpretation of the ^ character between the basic Search and Advanced tabs.
• As there is no Name checkbox in the Advanced tab, use name:GFP instead, which finds image 9.
• Aurora2~0.85 finds 1,2,3,4,5,6,7,8. The ~ denotes a fuzzy search, which is possible only in Advanced tab. The number behind the ~ indicates the precision with which the result must match the query.
• Aurora2~0.86 finds image 2.

The behaviour for the rest of the query examples in Advanced tab is the same as listed above for the basic Search tab.

Administrate Groups and Users

Description

This chapter will show how to manage groups and users using the graphical interface in OMERO.web and the command-line interface. Most of the following tasks below can only be done by users with some administrator privileges. We will show:

• How to manage groups, creating and editing a new/existing group.
• How to manage users, creating and editing a new/existing user.
• How to set up the OMERO server to be able to email all users.

Resources

• Documentation:
  • https://docs.openmicroscopy.org/latest/omero/sysadmins/server-permissions.html
  • https://docs.openmicroscopy.org/latest/omero/sysadmins/restricted-admins.html
  • https://docs.openmicroscopy.org/omero/latest/sysadmins/cli/usergroup.html
• Script for Command Line User/Group management
  • create_groups_users.sh
• File defining the User/Group setup used by the script
  • create_groups_users_setup

Setup

No setup needed for OMERO.web administration panel (see Web Interface chapter below) except working OMERO.web.

Command Line interface installation

The installation instructions can be found at CLI installation.

Step-by-step

Administrate using the Web Interface

1. In your web browser, go to the server address provided.
2. Log in using the username and password provided.
3. In the top toolbar, click the Admin button . Note that the Admin button is only available for users with certain privileges: administrators and administrators with restricted privileges. If you are a user or a group owner, navigate to the section Web Interface: Users change their own settings below.

Web Interface: Managing Groups

1. Click on the Groups tab. You can search for groups if desired.
2. To create a new Group, click on the Add new Group button. Note that the Name and Permissions fields are mandatory.
3. Click Save.
4. The new group will be shown in the list of Groups.
5. To edit a Group, click on the Pencil button .
6. You can add or remove members or group’s owners or change group permissions.
7. Before removing a user from a group, it is preferable to move their data to another group or transfer ownership of their data to another user. Having a data owned by someone who is not a member of the group is not desirable.
8. Click Save.

Web Interface: Managing Users

1. Click on the Users tab.
2. You can search for users if you wish.
3. OMERO.web denotes the user categories using small helpful icons:
   • Users with administrator privileges have a tools icon .
   • Active users have an icon with blue circle .
   • Inactive users have a lock icon .
   • LDAP users have a red hexagon .
4. To create a new user, click on the Add new User button.
5. Mandatory fields are highlighted in red.
6. You can select the role of the user to be:
   • User (no special privileges).
   • Administrator (this means full administrator).
   • Administrator with restricted privileges.
7. If you choose the role to be Administrator with restricted privileges, you must also select the privileges in a subsequent menu. Hover with mouse over the checkboxes to see short descriptions of the privileges. Creating an administrator with restricted privileges allows to give some limited rights to some trusted users e.g. to allow a facility manager to import data for other users. It is currently preferable to create users with such roles via the OMERO.web Interface. More about Administrator with restricted privileges can be found in this OMERO documentation section.
8. Click Save.
9. To edit a User, click on the Pencil button to the right of the line with the name of the user. You can add/remove the User to/from a group or modify the roles.
10. Click Save.

Web Interface: Users change their own settings

1. Note that these features are not limited to administrators, any user can change their settings in the manner described here. Furthermore, this is the preferred way for Group Owners to manage their groups.

2. In OMERO.web, click in the top-right corner of the webclient, click on your name, then, in the dropdown menu, click on User settings.

   

3. In the interface that appears, you can change your password and default group. Default group is the group you log in to by default when logging to OMERO. Your data in your default group is what you typically see immediately after loggging in for example to OMERO.web, whereas your data in your other (non-default) groups have to be explicitly navigated to.

4. For group owners only: You can now navigate to the group(s) you own by clicking onto My Groups tab.

   

5. Identify the group you want to edit in your group list and click on Edit button.

6. You can now add or remove group members, add members as group owners (a group can have many owners, besides youself). When removing users from the group, make sure that the data owned by a user is moved or transferred to another user before removing the user from the group.

7. You can also change the permissions level of your group. Note though that this is an action which needs careful thinking, especially if you are going from more permissive group types towards less permissive ones.

Administrate using the Command Line Interface (CLI)

Typically, the administration of Groups and Users in OMERO is done in OMERO.web (see section above), as it is more user friendly. The Command Line Interface (CLI) cannot offer the easy quick overview, filtering and searching and intuitively named buttons and tabs. For creation of administrators with restricted privileges, there are several key features missing from the CLI which are present in OMERO.web. Nevertheless, some features for handling LDAP users are implemented only in the CLI. Further, the CLI offers an environment in which custom bash scripts for user/group creation and maintenance can be executed. One example of such script can be taken from create_groups_users.sh. The script consumes a file create_groups_users_setup in which a certain user-group setup is defined.

Command Line: Managing Groups

1. By default when creating a group, its permissions level is set to private. To create a new read-annotate group Lab1, run:

   $ omero group add Lab1 --type=read-annotate
   

2. Or, you can define the permissions of the new group in a different way:

   $ omero group add Lab1 --perms='rwra--'
   

3. To list all the groups and save the output for example in a CSV file:

   $ omero group list --style csv > groups.csv
   

4. To add an existing user user-1 to the Lab1 group and make that user a group owner (the option --as-owner is not needed when adding a member), run:

   $ omero group adduser user-1 --name=Lab1 --as-owner
   

5. Let us add trainer-1 as an owner of the group too:

   $ omero group adduser trainer-1 --name=Lab1 --as-owner
   

6. To remove user-1 from the list of owners (user-1 will still be a member of the Lab1 group):

   $ omero user leavegroup Lab1 --name=user-1 --as-owner
   

7. Note that the previous command when run without the --as-owner flag would remove the user-1 from the group completely. Thus, it is an alternative to the following command.

8. To remove user-1 from the Lab1 group, you can also run:

   $ omero group removeuser user-1 --name=Lab1
   

9. To edit the Lab1 group, first determine its ID:

   $ omero group info --group-name Lab1
   
   id \| name \| perms \| ldap \| # of owners \| # of members
   
   -----+-------+--------+-------+-------------+--------------
   
   653 \| Lab1 \| rwra-- \| False \| 0 \| 0
   

10. Change the group name to LabN:

    $ omero obj update ExperimenterGroup:653 name='LabN'
    

11. Let us reset the name back to Lab1 to simplify the rest of the workflow.

12. Change the group’s permissions to read-write:

    $ omero group perms --perms='rwrw--' --name='Lab1'
    

Command Line: Managing Users

1. Create a new user with login name lpasteur and at the same time add this user (with first and last name Louis Pasteur) to the Lab1 group:

   $ omero user add lpasteur Louis Pasteur --group-name Lab1
   

2. Let us now add the user to another group:

   $ omero user joingroup Lab2 --name=lpasteur
   

3. To edit the user and for example add an email address, first determine the user’s ID:

   $ omero user info --user-name lpasteur
   

4. Add an email address (supposing the ID of the user is 123):

   $ omero obj update Experimenter:123 email='lpasteur@demo.co.uk'
   

5. Make a user inactive. User cannot be deleted but it is possible to prevent a user from logging in. For that, we need to remove the user from the user group (an internal OMERO group):

   $ omero user leavegroup user --name=lpasteur
   

6. To reactivate the user:

   $ omero user joingroup user --name=lpasteur
   

Command Line: Managing LDAP Users

If LDAP authentication is configured on your OMERO.server, the OMERO.server synchronizes the user list with an LDAP server, thus enabling an easy user creation and maintenance. It is possible to convert non-LDAP OMERO users to LDAP authentication using the command omero ldap setdn. See further information in the links under the Resources section of this guide. See LDAP authentication and LDAP plugin design.

Typically, it is impractical to synchronize the OMERO groups with LDAP groups. In such case, the OMERO.server can be configured in such a way that LDAP users when they first log in to OMERO will be added to a specific private OMERO group (let us call this group My Data). This situation is further explored in the example below.

The administrator or administrator with restricted privileges can add an LDAP user to OMERO even before the user have ever logged in to OMERO:

1. First create the existing LDAP user as OMERO user. In the example below the user name is enoether:

   $ omero ldap create enoether
   

2. The user is now a member of the My Data group in OMERO. Then, if needed, add the user to the Lab1 group:

   $ omero group adduser enoether --name=Lab1
   

3. Note that it is advisable to clarify the OMERO group membership situation of the LDAP users soon after they joined OMERO. This can be done for example by adding the new user to their lab group (e.g. Lab1) in OMERO as well and by changing the default group of such user in OMERO to be their lab group. See above for how to change the default group of a user. Otherwise, the new LDAP&OMERO users might be importing their data into the My Data group for some period of time, without realizing the data are not accessible to their colleagues in the lab group for cooperative purposes because My Data is a private group.

Set up OMERO server to email users

If you are a full administrator or an administrator with restricted privileges with any or no privileges, you can email OMERO users. This can be helpful for example to inform users about downtimes, new features or imminent changes regarding OMERO.

1. In cooperation with you OMERO.server system administrator, consult the documentation on email in OMERO.

2. Once the OMERO.server is configured, log in to OMERO.web and in the top toolbar, click the Admin button .

3. Click on the Email tab.

4. Choose the appropriate options, enter the email subject and message. Note that depending on the number of users you are choosing to email, the action might take a long time to finish. You must keep the session of OMERO.web alive (i.e. doing actions still being logged in OMERO.web) until the Activities dropdown menu (icon to the left of the Search in the top bar of OMERO.web) reports that all emails were sent.

   

   

5. Click Send button.

Prepare data for publication using OMERO

Users can publish Image data to the world using OMERO. Here we describe some steps to facilitate that. The steps are to be done by an administrator or restricted administrator in OMERO.

Description

We will show:

• How to set up configurations in OMERO.web for establishing of a public user.
• How to set up a public group.
• How to get the data into the public group.
• How to open the public group to the outer world.

Setup

OMERO.server has been installed and provisioned using an Ansible playbook.

OMERO.server configurations for publication are described in the following chapter of the publication in OMERO documentation:

• Configuring public user.

Resources

• The publication in OMERO is described in the documentation.

Step-by-Step

1. Consult with the system administrator of your OMERO.server the configuring of public user on the server. Read the possibilities about how to restrict the access to the data in public group using url filtering in the publication with OMERO documentation
2. Establish a public group with read-only permissions. See the publication example documentation and the Administrate Groups and Users for how to do it. Note: The public group is just an ordinary read-only group, only a subsequent addition of the public user to this group makes it public.
3. Think about the best strategy of data layout in the public group, see suggestions about it in the Group setup part of publication example documentation.
4. Duplicate the data to be published as described in Data management and cooperation either yourself, or instruct the lead scientist on the publication to do this. It is recommended to duplicate the annotations as well, which is done by the duplication plugin by the default, as this will facilitate the preservation of the linkage between the data and annotations during the subsequent move to the public group.
5. Consult with the scientists intending to publish their data about how to Move the data into the public group, or move them yourself. Some helpful hints about the data Move can be found in the Data migration chapter of the documentation. The move between groups is made easier by making duplicates of the data prior to the move and then moving these duplicates (see previous step). Also see the chapter Move data between groups in Data management and cooperation for how to Move the data between groups. The other option is to import the data afresh into the public group. Note: there is no possiblity to copy or link the data in a single step into public group from another group in OMERO at the moment. The duplication of the data and subsequent move of the duplicate into the public group is the recommended workflow.
6. Once you are happy with the setup of the public group, add the public user into the public group as described in the documentation. See Administrate Groups and Users for how to add users into groups in OMERO. The additon of the public user will make the data in the public group visible to the world.