Merge pull request #5 from pwalczysko/fix-flows

Fix flows

docs/import-cli.rst

@@ -1,5 +1,5 @@
-**Import data using the Command Line Interface (CLI)**
-======================================================
+Import data using the Command Line Interface (CLI)
+==================================================
 
 Description:
 ------------
@@ -8,7 +8,7 @@ This chapter will show how to import data for another user, using Command Line I
 
 The user importing the data needs to have some admin (or restricted-admin) privileges. More information about restricted privileges can be found at \ https://docs.openmicroscopy.org/latest/omero/sysadmins/restricted-admins.html
 
-The import for another user will be done only as demo since the user is required to have specific privileges. We will use a user with login name importer1, who could be in real life e.g. a facility manager\ .
+The import for another user will be done only as demo since the user is required to have specific privileges. We will use a user with login name importer1, who could be in real life e.g. a facility manager.
 
 We will show:
 
@@ -43,7 +43,7 @@ We will show:
 
 -  Example files for bulk import
 
-   -  `https://github.com/ome/training-scripts/tree/latest/practical/other <https://github.com/ome/training-scripts/tree/v0.7.0/practical/other>`__
+   -  :download:`bulk.yml <../scripts/bulk.yml>`
 
 Setup:
 ------
@@ -59,49 +59,49 @@ Note: When importing for another user using the CLI, the importer1 does not have
 **Step-by-step:**
 -----------------
 
-#.  Open a terminal and connect to the server as importer1 using ssh.
+#.  Open a terminal and connect to the server as importer1 using ``ssh``.
 
-#.  The aim is to import an image from /OMERO/in-place-import/FRAP
+#.  The aim is to import an image from /OMERO/in-place-import/FRAP::
     
-    ``$ ls /OMERO/in-place-import/FRAP``
+    $ ls /OMERO/in-place-import/FRAP
 
-#.  Activate the virtual environment where ``omero-py`` is installed or add it to ``PATH`` e.g.
+#.  Activate the virtual environment where ``omero-py`` is installed or add it to ``PATH`` e.g.::
 
     
-    ``$ export PATH=/opt/omero/server/venv3/bin:$PATH``
+    $ export PATH=/opt/omero/server/venv3/bin:$PATH
 
-#.  Point ``OMERODIR`` to the location where the OMERO server is installed e.g.
+#.  Point ``OMERODIR`` to the location where the OMERO server is installed e.g.::
 
-    ``$ ls export OMERODIR=/opt/omero/server/OMERO.server``
+    $ export OMERODIR=/opt/omero/server/OMERO.server
 
-#.  The importer1 user logs in as themselves
+#.  The importer1 user logs in as themselves::
 
-    ``$ omero -u importer1 login``
+    $ omero -u importer1 login
 
-#.  Creates a Dataset import_for_myself
+#.  Creates a Dataset import_for_myself::
 
-    ``$ DID=$(omero obj new Dataset name=import_for_myself)``
+    $ DID=$(omero obj new Dataset name=import_for_myself)
 
-#.  Import the data in the newly created Dataset:
+#.  Import the data in the newly created Dataset::
 
-    ``$ omero import -d $DID /OMERO/in-place-import/FRAP/U20S-RCC1.10_R3D_FRAP.dv``
+    $ omero import -d $DID /OMERO/in-place-import/FRAP/U20S-RCC1.10_R3D_FRAP.dv
 
-#.  The importer1 user logs in as user-1:
+#.  The importer1 user logs in as user-1::
 
-    ``$ omero --sudo importer1 -u user-1 login``
+    $ omero --sudo importer1 -u user-1 login
 
-#.  Create a Dataset import_for_user_one as user-1:
+#.  Create a Dataset import_for_user_one as user-1::
 
-    ``$ DID=$(omero obj new Dataset name=import_for_user_one)``
+    $ DID=$(omero obj new Dataset name=import_for_user_one)
 
-#.  Import the data in the newly created Dataset:
+#.  Import the data in the newly created Dataset::
 
-    ``$ omero import -d $DID /OMERO/in-place-import/FRAP/U20S-RCC1.10_R3D_FRAP.dv``
+    $ omero import -d $DID /OMERO/in-place-import/FRAP/U20S-RCC1.10_R3D_FRAP.dv
 
 #. Check that the images are successfully imported.
 
-**In-place Import CLI** 
-========================
+In-place Import using the CLI 
+=============================
 
 Instead of being copied into OMERO’s managed repository, the image files
 stay at their original place and are just linked into the repository.
@@ -112,7 +112,7 @@ It is only available for the CLI importer, using the argument ``--transfer=ln_s`
 
 **Advantages:**
 
--  All in-place import scenarios provide non-copying benefit. Data that is too large toxist in multiple places, or which is accessed too frequently in its original form to be renamed,remains where it was originally acquired.
+-  All in-place import scenarios provide non-copying benefit. Data that is too large to exist in multiple places, or which is accessed too frequently in its original form to be renamed, remains where it was originally acquired.
 
 **Limitations:**
 
@@ -122,11 +122,11 @@ It is only available for the CLI importer, using the argument ``--transfer=ln_s`
 
 **Important:**
 
-Someone wanting to perform an in-place import MUST have:
+A user performing an in-place import MUST have:
 
 -  a regular OMERO account
 
--  an OS-account with access to bin/omero
+-  an OS-account with ability to run omero commands on server machine
 
 -  read access to the location of the data
 
@@ -138,35 +138,38 @@ Someone wanting to perform an in-place import MUST have:
 **Step-by-step:**
 -----------------
 
--  We are still in the omero server directory: ``/opt/omero/server/OMERO.server/bin``
+- Make sure that the virtual environment where ``omero-py`` is installed is activated and ``OMERODIR`` is defined, as above
 
--  Log in again: ``$ ./omero --sudo importer1 -u user-1 login``
+-  Log in again::
 
--  ‘In place’ import a large SVS file into the same dataset as before:
-      ``$ ./omero import -d $DID --transfer=ln_s /OMERO/in-place-import/svs/77917.svs``
+    $ omero --sudo importer1 -u user-1 login
+
+-  ‘In place’ import a large SVS file into the same dataset as above::
+
+    $ omero import -d $DID --transfer=ln_s /OMERO/in-place-import/svs/77917.svs
 
 -  Check that the image is successfully imported.
 
 -  Click on the paths icon |image3| to show the difference between the normal and in-place (ln_s) imported images. Validate that In-place import is indicated \ |image4|\ .
 
--  Note: The script \ https://github.com/ome/training-scripts/blob/master/maintenance/scripts/in_place_import_as.sh\  shows how to perform the in-place import steps described above in one single command.
+-  Note: The script `in_place_import_as.sh <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/in_place_import_as.sh>`_  shows how to perform the in-place import steps described above in one single command.
 
-**Bulk Import CLI**
-===================
+Bulk Import using the CLI
+=========================
 
 In this example, we show how to combine several import strategies using a configuration file. This is a strategy heavily used to import data to \ https://idr.openmicroscopy.org/\ .
 
 We import two folders named *siRNA-HeLa* and *condensation*. For this training, the path to the OMERO.server is /opt/omero/server.
 
-#. Open a terminal and connect to the server as importer1 over SSH.
+#. Open a terminal and connect to the server as importer1 over ``SSH``.
 
 #. Note: Connecting over SSH is necessary only if you intend to import in-place. If a classic import is being performed, you can connect to the server remotely using OMERO.cli and still use the bulk import as described below.
 
-#. Description of the files used to set up the import, the files are in the directory ``/OMERO/in-place-import``. See  \ https://github.com/ome/training-scripts/tree/master/practical/other\  and \ https://docs.openmicroscopy.org/latest/omero/users/cli/import-bulk.html#bulk-imports\ for further details.
+#. Description of the files used to set up the import (see :download:`bulk.yml <../scripts/bulk.yml>`, :download:`import-paths.csv <../scripts/import-paths.csv>` and `import-bulk.html#bulk-imports <https://docs.openmicroscopy.org/latest/omero/users/cli/import-bulk.html#bulk-imports>`_ for further details).
 
    - ``import-paths.csv``: (.csv, comma-separated values) this file has at least two columns. In this case the columns are separated by commas. The first column is the name of the target Dataset and the second one is the path to the folder to import. We will import two folders (the ``import-paths.csv`` has two rows).
 
-      Example csv (note the comma between the “HeLa” and “/OMERO…”):
+      Example csv (note the comma between the "HeLa" and "/OMERO..."):
 
       ``*Dataset:name:Experiment1-HeLa,/OMERO/in-place-import/siRNAi-HeLa*``
 
@@ -177,38 +180,40 @@ We import two folders named *siRNA-HeLa* and *condensation*. For this training,
 
       Example bulk.yml:
 
-.. code-block:: python
+    .. code-block:: python
 
-      *continue: "true"*
+        *continue: "true"*
 
-      *transfer: "ln_s"*
+        *transfer: "ln_s"*
 
-      *# exclude: "clientpath"*
+        *# exclude: "clientpath"*
 
-      *checksum_algorithm: "File-Size-64"*
+        *checksum_algorithm: "File-Size-64"*
 
-      *logprefix: "logs"*
+        *logprefix: "logs"*
 
-      *output: "yaml"*
+        *output: "yaml"*
 
-      *path: "import-paths.csv"*
+        *path: "import-paths.csv"*
 
-      *columns:*
+        *columns:*
 
-          -  *target*
+            -  *target*
 
-          -  *path*
+            -  *path*
 
 
-#. Go to /OMERO/in-place-import i.e. ``cd /OMERO/in-place-import``
+#. Find the place where the ``bulk.yml`` file is located, for example ``/OMERO/in-place-import``::
 
-#. The importer1 (Facility Manager with ability to import for others) user logs in as user-1:
+   $ cd /OMERO/in-place-import
 
-   ``$ bin/omero --sudo importer1 -u user-1 login``
+#. The importer1 (Facility Manager with ability to import for others) user logs in as user-1::
 
-#. Import the data using the --bulk command:
+   $ omero --sudo importer1 -u user-1 login
 
-   ``$ bin/omero import --bulk bulk.yml``
+#. Import the data using the ``--bulk`` command::
+
+   $ omero import --bulk bulk.yml
 
 #. Go to the webclient during the import process to show the newly created dataset. The new datasets in OMERO are named Experiment1-HeLa and Experiment2-condensation. This was specified in the first column of the ``import-paths.csv`` file.
 
@@ -224,13 +229,15 @@ We import two folders named *siRNA-HeLa* and *condensation*. For this training,
 
 -  Large amount of data imported using one import command.
 
+-  Heterogeneous data for multiple users can be imported using bulk import in combination with bash scripting, e.g. `in_place_import_as.sh <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/in_place_import_as.sh>`_
+
 -  Reproducible import.
 
 **Limitations:**
 
 -  Preparation of the .csv or .tsv file.
 
-For more information about CLI import options, go to \ https://docs.openmicroscopy.org/latest/omero/users/cli/import.html\ .
+For more information about CLI import options, go to `import.html <https://docs.openmicroscopy.org/latest/omero/users/cli/import.html>`_.
 
 .. |image0| image:: images/importcli4.png
    :width: 4.46235in

docs/import-desktop-client.rst

@@ -1,5 +1,5 @@
-**Import data using the Desktop Client**
-========================================
+Import data using the Desktop Client
+====================================
 
 Description:
 ------------
@@ -119,8 +119,8 @@ Step-by-step:
 
 #. (demo only step) Now, the demonstrator will log out from OMERO.insight and log in again, this time as some other user and will show the import process again, this time importing a different set of images. After this import, the two sets of images (belonging to two different users) will be shown in the webclient.
 
-**Import for another user**
-===========================
+Import for another user
+=======================
 
 In this example, we show how to import data for another user. A facility manager importer1 with restricted admin privileges imports the data for user-1. The facility manager has been given the ability to import for others.
 

docs/import-dropbox.rst

@@ -1,5 +1,5 @@
-**Import data using OMERO.dropbox**
-===================================
+Import data using OMERO.dropbox
+===============================
 
 **Description:**
 ----------------

docs/index.rst

@@ -7,3 +7,4 @@ Contents:
    :maxdepth: 1
 
    import
+   render

docs/render.rst

@@ -0,0 +1,81 @@
+Change image rendering settings and channel names using the Command Line Interface (CLI)
+========================================================================================
+
+Description:
+------------
+
+This chapter will show how to change rendering settings on images using the Command Line Interface (CLI).
+
+This action is typically done after a successful import of images.
+
+We will show:
+
+-  How to change rendering settings of large amount of images on the CLI in a repeatable manner.
+
+**Resources:**
+--------------
+
+-  Documentation:
+
+   -  https://docs.openmicroscopy.org/latest/omero/users/cli/installation.html
+
+   -  `https://docs.openmicroscopy.org/omero/latest/users/cli/index.html <https://docs.openmicroscopy.org/omero/latest/users/cli/index.html>`__
+
+-  Data: example images from
+
+   -  IDR data http://idr.openmicroscopy.org/webclient/?show=project-51
+
+-  Rendering plugin for OMERO 
+
+   - https://pypi.org/project/omero-cli-render/
+
+-  Rendering yml files defining the various rendering parameters, such as the channel color, channel name and minimum and maximum values.
+
+   - https://github.com/ome/training-scripts/blob/master/maintenance/preparation/renderingdef.yml
+   - https://github.com/ome/training-scripts/blob/master/maintenance/preparation/renderingdef2.yml
+
+-  Rendering mapping file has two columns, in the left-hand one there are the images to be rendered and in the right-hand side column points to the appropriate ​renderingdef.yml​ for that image.
+
+   - https://github.com/ome/training-scripts/blob/master/maintenance/preparation/renderingMapping.tsv
+
+-  Shellscript for batch modification of rendering settings of images
+
+   - https://github.com/ome/training-scripts/blob/master/maintenance/scripts/apply_rnd_settings_as.sh
+
+Setup:
+------
+
+**Rendering plugin installation**
+
+- Go to the environment where you installed your OMERO.cli as specified under -  https://docs.openmicroscopy.org/latest/omero/users/cli/installation.html.
+
+- Activate the virtual environment.
+
+- Run::
+    
+    $ pip install omero-cli-render
+
+**Step-by-step:**
+-----------------
+
+#.  On your local machine, open a terminal
+
+#.  Activate the virtual environment where ``omero-py`` is installed or add it to ``PATH`` e.g.::
+    
+    $ export PATH=/opt/omero/server/venv3/bin:$PATH
+
+#.  The variable ``$ID​`` below is the ID of the ​selected Dataset. To change the rendering of images in one Dataset, run::
+    
+    $ ​omero render set Dataset:$ID local_path/to/renderingdef.yml
+
+#.  Verify the change in the browser.
+
+#.  To change the rendering of images in two Datasets, run::
+
+    $ omero render set Dataset:$ID1 Dataset:$ID2 renderingdef2.yml
+
+#.  Modify the rendering settings in batch using a shellscript such as `apply_rnd_settings_as.sh <https://github.com/ome/training-scripts/blob/master/maintenance/scripts/apply_rnd_settings_as.sh>`_ which uses ​HQL ​to find the Images IDs in OMERO and deliver them to the omero-cli-render​ plugin. The script reads the Datasets in which the Images are located in OMERO are listed from a​ renderingMapping.tsv ​​file, such as `renderingMapping.tsv <https://github.com/ome/training-scripts/blob/master/maintenance/preparation/renderingMapping.tsv>`_. Go to the folder where the script is located. Then run the bash script with the default parameters::
+
+    $ ​sh apply_rnd_settings.sh
+
+    The script could be run by a facility manager on behalf of other users.

scripts/bulk.yml

@@ -0,0 +1,11 @@
+---
+continue: "true"
+transfer: "ln_s"
+# exclude: "clientpath"
+checksum_algorithm: "File-Size-64"
+logprefix: "logs/"
+output: "yaml"
+path: "import-paths.csv"
+columns:
+  - target
+  - path

scripts/import-paths.csv

@@ -0,0 +1,2 @@
+Dataset:name:Experiment1-HeLa,/OMERO/in-place-import/siRNAi-HeLa
+Dataset:name:Experiment2-condensation,/OMERO/in-place-import/condensation