Merge pull request #4 from pwalczysko/data-management-additions

Data management additions

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,25 +19,25 @@ 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
 
    -  Key-Value Pairs
 
    -  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 <https://downloads.openmicroscopy.org/images/DV/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 <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/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 <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/key_value_pairs.py>`_.
 
-**Step-by-step**
-----------------
+Step-by-step
+------------
 
 #. Open a browser and enter the provided URL
 
@@ -47,36 +47,36 @@ 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|
 
       |image1|
 
    - 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|
 

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

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 <https://github.com/ome/prod-playbooks/blob/master/omero/training-server/playbook.yml>`_.
 
--  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 <https://github.com/ome/training-repos/blob/master/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 <https://github.com/ome/training-scripts/tree/master/maintenance>`_ for more details.
+
+-  For import of images, we use `in_place_import_as.sh <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/in_place_import_as.sh>`_.
+
+-  The cooperation in OMERO is described in `Groups and permissions system <https://docs.openmicroscopy.org/latest/omero/sysadmins/server-permissions.html>`_.
 
-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 <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.
+
+#.  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 <https://docs.openmicroscopy.org/omero/latest/users/cli/chgrp.html>`_.
+
+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