diff --git a/docs/annotate.rst b/docs/annotate.rst index 3170fc7..cf37bb7 100644 --- a/docs/annotate.rst +++ b/docs/annotate.rst @@ -4,12 +4,12 @@ Annotate Data and Filter using Annotations In this section, we show various types of annotations supported in OMERO and how to use them. -**Description** ---------------- +Description +----------- We will show: -- How to annotate Images, Datasets and Projects with +- How to annotate Images, Datasets and Projects with: - Tags @@ -19,7 +19,7 @@ We will show: - Ratings -- How to filter thumbnails in the central pane of OMERO.web for +- How to filter thumbnails in the central pane of OMERO.web for: - Tags @@ -27,17 +27,17 @@ We will show: - Ratings -**Setup** ---------- +Setup +----- -- The data used are from the siRNAi-HeLa folder available at \ https://downloads.openmicroscopy.org/images/DV/siRNAi-HeLa/ +- 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 \ https://github.com/ome/training-scripts/blob/master/maintenance/scripts/copy_tags_ratings.py +- 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 \ https://github.com/ome/training-scripts/blob/master/maintenance/scripts/key_value_pairs.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** ----------------- +Step-by-step +------------ #. Open a browser and enter the provided URL @@ -47,15 +47,15 @@ We will show: - Select one or more Images in the siRNAi-HeLa Dataset of cells which appear to be in metaphase. - - Choose the Tag option in the right-hand General tab and click [ + ] to launch the Tag dialog. + - Choose the Tag option in the right-hand ``General`` tab and click ``[ + ]`` to launch the Tag dialog. - Choose the existing Metaphase from the list of Tags (to filter, type above the list). - - Click > to move it to the right column, then click OK. + - Click ``>`` to move it to the right column, then click ``OK``. #. Let’s 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. + - Select an Image from the Dataset and in the right-hand pane in ``General`` tab, click the harmonica Key-Value Pairs. |image0| @@ -63,20 +63,20 @@ We will show: - 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 :doc:`search-omero`. -#. It is also possible to add Comment, Attachment and Rating to selected Images in the right-hand pane in General tab. +#. It is also possible to add Comment, Attachment and Rating to selected Images in the right-hand pane in the ``General`` tab. #. 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. + - 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. + - 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. |image3| - - Review the filtered Images, choose a favourite Image and under the Rating section in the right-hand pane, click on the 5th star to add a rating of 5 + - 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 |image2| diff --git a/docs/conf.py b/docs/conf.py index e7f32e3..aa953e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,7 +50,7 @@ # General information about the project. project = u'OMERO general introduction guide' -copyright = u'2019, Open Microscopy Environment' +copyright = u'2019-2020, Open Microscopy Environment' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/data-management.rst b/docs/data-management.rst index 5dd056e..ee0d9a6 100644 --- a/docs/data-management.rst +++ b/docs/data-management.rst @@ -6,44 +6,51 @@ 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. -**Description** ---------------- +Description +----------- We will show: -- How to browse data in OMERO.web, navigating to yours and other users’ images +- How to browse data in OMERO.web, navigating to yours and other users’ images. -- How to use the basic layout of OMERO.web -- How to use the Preview panel +- How to use the basic layout of OMERO.web for images organized in Projects and Datasets. -- How to adjust the rendering settings of yours and other users’ images from the Preview panel +- How to use OMERO.web for viewing of High-Content Screening (HCS) data. -**Setup** ---------- +- How to use the Preview panel. -OMERO.server has been installed and provisioned using the Ansible software, the corresponding playbook +- How to adjust the rendering settings of your and other users’ images from the Preview panel. -- https://github.com/ome/prod-playbooks/blob/master/omero/training-server/playbook.yml +- How to move the data between groups if you are data owner. -**Resources** -------------- +- How to move the data between groups if you are an administrator working on behalf of others. -- All data have been pre-imported. For more details, go to: https://github.com/ome/training-repos/blob/master/data.md +Setup +----- -- To import images and metadata, scripts were used. For more details, go to: https://github.com/ome/training-scripts/tree/master/maintenance +OMERO.server has been installed and provisioned using an `Ansible playbook `_. -- For import of images, the main script used was: https://github.com/ome/training-scripts/blob/master/maintenance/scripts/in_place_import_as.sh +Resources +--------- -- The cooperation in OMERO is described in https://docs.openmicroscopy.org/latest/omero/sysadmins/server-permissions.html +- All data have been pre-imported. For more details, look at `data.md `_. -**Step-by-Step** ----------------- +- For the HCS data screenshot, the IDR data https://idr.openmicroscopy.org/webclient/?show=run-5403 were used. -**Data layout and ownership, usernames** -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- 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 `_. -All images for this workshop have been pre-imported for you into the +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 @@ -69,9 +76,9 @@ Browsing and rendering #. Log in using the username and password provided. -#. 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. For this training session, we will work in a “Read-Annotate” group. This implies that users can view and annotate each other’s data but cannot delete other people’s data. +#. 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. -#. To see other people’s data, click on the Lab1 group name in the top-left corner of the webclient. Then use the menu to select the name of the user whose data you wish to see. +#. 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. \ |image0| @@ -81,23 +88,37 @@ Browsing and rendering #. These represent imported Images. The original Images are stored on the server and the generated thumbnails allow us to browse them. -#. Bio-Formats,\ https://www.openmicroscopy.org/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. +#. `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. + +#. 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 4 ``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``. + + |image3| #. 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 + - 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. + - additional metadata in the ``Acquisition`` tab. All the metadata read by Bio-Formats can be downloaded at any time. -#. In the Preview tab in the right-hand panel, you can also view the Image. +#. In the ``Preview`` tab in the right-hand panel, you can also view the Image. #. For multi-plane images, sliders allow you to move through Z or Time dimensions. -#. 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 client. +#. 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. #. You can adjust the rendering settings for each channel e.g. turn on/off the channels, adjust color settings, look-up tables, etc.. -#. The rendering settings can be saved to the server. This NEVER changes the original Image data and can be reverted at any time. +#. The rendering settings can be saved to the server. This **never** changes the original Image data and can be reverted at any time. #. 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. @@ -109,6 +130,56 @@ Browsing and rendering #. 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``. +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 severed 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. + +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. + +#. In OMERO.web, select the data to be moved in the left-hand side tree. + +#. Right-click and select ``Move to Group...``. + + |image4| + +#. Select the group you want to move the data to. + +#. 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. + + |image5| + +#. Check both lists. Please read the note above about which objects are typically not included and reconsider the ``Move`` action again. 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. + +#. 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). + +#. Navigate to the data of a user in a group that you are not a member of. + +#. Select the data in the left-hand tree. + +#. Right-click and select ``Move to Group...``. + +#. Follow further the steps described in the section ``Move data between groups: owners of data`` above, taking note of the ``Not included`` objects. + +#. 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 the data handling possibilities such as reorganizing the data, renaming the containers you created for them etc. for the owner of the data. + + .. |image0| image:: images/management1.png :width: 4.15104in :height: 3.4592in @@ -118,3 +189,12 @@ Browsing and rendering .. |image2| image:: images/management3.png :width: 3.41667in :height: 1.625in +.. |image3| image:: images/management4.png + :width: 7.51667in + :height: 5in +.. |image4| image:: images/management5.png + :width: 2in + :height: 2.4592in +.. |image5| image:: images/management6.png + :width: 4in + :height: 4.9in diff --git a/docs/group-user-management.rst b/docs/group-user-management.rst index 091ed1c..ea3c93a 100644 --- a/docs/group-user-management.rst +++ b/docs/group-user-management.rst @@ -21,11 +21,6 @@ Resources - https://docs.openmicroscopy.org/omero/latest/sysadmins/cli/usergroup.html - - https://docs.openmicroscopy.org/omero/latest/sysadmins/server-ldap.html - - - https://docs.openmicroscopy.org/omero/latest/developers/Server/Ldap.html?highlight=ldap - - - Script for Command Line User/Group management - `create_groups_users.sh `_ @@ -129,8 +124,8 @@ Administrate using the Web Interface 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 intiutively 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 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* @@ -216,7 +211,8 @@ Further, the CLI offers an environment in which custom bash scripts for user/gro *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. +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. diff --git a/docs/images/management4.png b/docs/images/management4.png new file mode 100644 index 0000000..dccd602 Binary files /dev/null and b/docs/images/management4.png differ diff --git a/docs/images/management5.png b/docs/images/management5.png new file mode 100644 index 0000000..231b2bf Binary files /dev/null and b/docs/images/management5.png differ diff --git a/docs/images/management6.png b/docs/images/management6.png new file mode 100644 index 0000000..11bb731 Binary files /dev/null and b/docs/images/management6.png differ diff --git a/docs/search-omero.rst b/docs/search-omero.rst index 132b817..dd363ec 100644 --- a/docs/search-omero.rst +++ b/docs/search-omero.rst @@ -3,56 +3,56 @@ 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 :doc:`annotate`. -**Description** ---------------- +Description +----------- We will show: -- How to start a search in OMERO.web +- How to start a search in OMERO.web. -- How to search for objects annotated with a specific Key-Value Pair +- How to search for objects annotated with a specific Key-Value Pair. -- How to use Advanced Search +- How to use Advanced Search. - - How to search for terms in specific fields e.g. "name" + - 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. - - How to combine search terms using AND NOT + - How to combine search terms using AND NOT. -**Setup** ---------- +Setup +----- -- The data used are from the siRNAi-HeLa folder available at \ https://downloads.openmicroscopy.org/images/DV/siRNAi-HeLa/ +- 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 \ https://github.com/ome/training-scripts/blob/master/maintenance/scripts/key_value_pairs.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** ----------------- +Step-by-Step +------------ #. Open a browser and enter the provided URL #. Connect using the provided credentials -#. Enter mitomycin-A into the search box in the top right corner of the webclient |image1| +#. Enter ``mitomycin-A`` into the search box in the top right corner of the webclient |image1| -#. Press Enter. +#. Press ``Enter``. #. The search results will show any objects e.g. Images or Datasets, which have anywhere the string mitomycin-A. #. Several images should be found, from two different datasets. -#. 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. +#. 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``. #. Now you should find only 21 images. -#. Click on the “Advanced search” tab in the search results. +#. Click on the ``Advanced search`` tab in the search results. -#. 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. +#. 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. #. You should see 5 results now. -#. 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. +#. 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. #. You should see 16 results now.