OMERO.scripts user guide ======================== :doc:`/developers/server-blitz` provides a service to run scripts on the server. The scripts are then passed on to a grid of processors called OMERO.grid that executes the script and returns the result to the server which in turn passes the result onto the caller. All scripts are of the form: :: # import the omero package and the omero.scripts package. import omero, omero.scripts as scripts ''' This method creates the client script object, with name SCRIPTNAME and SCRIPTDESCRIPTION. The script then supplies a number of variables that are both inputs and outputs to the script. The types allowed are defined in the script package, with the qualifier after the variable of in, out or inout depending on whether the variable if for input, output or input and output. ''' client = scripts.client("SCRIPTNAME", "SCRIPTDESCRIPTION", scripts.TYPE("VARIABLENAME").[in()|out()|inout()], …) # All variables are stored in a map accessed by getInput and setOutput via the client object. VARIABLENAME = client.getInput("VARIABLENAME"); client.setOutput("VARIABLENAME", value); This is a guide to getting started with the scripting service, without going into the 'behind the scenes' details. More technical details can be found on the :doc:`/developers/scripts/advanced` page. In addition to this guide, you may find the following pages useful for more information on using the OMERO Python API: |OmeroClients|, |OmeroPy|. Sample scripts -------------- Below are two sample scripts. You can find the core scripts that are distributed with the OMERO.server under the `scripts repository `_ or download them from OMERO.insight (from the bottom-left of any run-script dialog), or use the GitHub repositories forked from `ome/omero-user-scripts `_ to find scripts written by other users. Ping script ^^^^^^^^^^^ This script echoes the input parameters as outputs. :: import omero, omero.scripts as scripts client = scripts.client("ping.py", "simple ping script", scripts.Long("a"), scripts.String("b")) keys = client.getInputKeys() print "Keys found:" print keys for key in keys: client.setOutput(key, client.getInput(key)) Accessing an Image and Channels on the server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example shows usage of the Python Blitz Gateway to access an Image, using its ID. We then list the Channel names and the script returns them as outputs. :: import omero, omero.scripts as scripts from omero.gateway import BlitzGateway from omero.rtypes import wrap # Define the script name & description, and a single 'required' parameter client = scripts.client("Get_Channels.py", "Get channel names for an image", scripts.Long("imageId", optional=False)) # get the Image Id from the parameters. imageId = client.getInput("imageId", unwrap=True) # unwrap the rtype # Use the Python Blitz Gateway for convenience conn = BlitzGateway(client_obj=client) # get the Image, print its name image = conn.getObject("Image", imageId) print image.getName() # Print each channel 'label' (Name or Excitation wavelength) for i, ch in enumerate(image.getChannels()): print ch.getLabel() # Return as output. Key is string, value is rtype client.setOutput("Channel%s" % i, wrap(str(ch.getLabel()))) # Cleanup client.closeSession() Dynamic arguments ^^^^^^^^^^^^^^^^^ In general, script parameters are processed on server startup and cached for later use. If you have a script which should recalculate its arguments on each invocation, use the `NSDYNAMIC` namespace: .. literalinclude:: Example_Dynamic_Script.py :start-after: # Included in :download:`Example_Dynamic_Script.py ` Script writing as 'Admin' ------------------------- The basic steps in a script-writing workflow are: - Write a script using your favorite text editor, save locally - Use command line (or OMERO.insight) to upload script to server - Use command line (or OMERO.insight or web clients) to run script on the server (results will be displayed) - Edit script and replace copy on server and run again, etc. Working with scripts is far more straightforward if you have admin access to your OMERO.server installation - this is the preferred workflow. It is possible to work with scripts as a regular user (see :doc:`advanced`) but the software you would be required to install means it is easier to install a server on your local machine so you have admin rights. It is assumed that scripts written by a server admin are "trusted" to run on the server without causing any disruption or security risks. Once uploaded these scripts are available to all regular users of the server alongside the official scripts included in each OMERO release. Download / Edit script ^^^^^^^^^^^^^^^^^^^^^^ The easiest way to get started is to take an existing script and edit it for your needs. An example created for the purpose of this tutorial can be found at :source:`Edit_Descriptions.py `. You should organize your scripts on your local machine in a way that makes sense to users, since your local file paths will be mimicked on the server and used to organize script menus in OMERO.insight (see screen-shot above). :: # Save the script to a suitable location. The tutorial will use this location: # Desktop/scripts/demo_tutorial/Edit_Descriptions.py The action of this script (editing Image descriptions) is trivial but it demonstrates a number of features that you may find useful, including conventions for inputs and outputs to improve interaction with OMERO.insight (as discussed on the :doc:`style-guide`). The script is well-documented and should get you started. A few points to note: If you are using the 'Blitz Gateway' then you can get a connection wrapper like this: :: from omero.gateway import BlitzGateway conn = BlitzGateway(client_obj=client) # now you can do E.g. conn.getObject("Image", imageId) etc. Alternatively, if you are working directly with the OMERO services, you can get a service factory like this: :: session = client.getSession() # now you can do E.g. session.getQueryService() etc. More example scripts ^^^^^^^^^^^^^^^^^^^^ Several official scripts are included in the release of OMERO and can be found under the lib/scripts/omero/ directory of the server package. Any script can also be download from the OMERO.insight client (bottom-left of the run-script dialog). .. Warning:: If you wish to edit the official scripts that are part of the OMERO release, you should be prepared to apply the same changes to future releases of these scripts from OMERO. If you think that your changes should be included as part of future released scripts, please let us know. Upload script ^^^^^^^^^^^^^ You can use the command line, OMERO.insight or the server file system to upload scripts. The ``script`` command line tool is discussed in more detail below. You may find it useful to add the OMERO.server/bin/ folder to your PATH so you can call ``bin/omero`` commands when working in the scripts folder. E.g: .. parsed-literal:: export PATH=$PATH:/Users/will/Desktop/OMERO.server-|release|/bin/ Upload the script we saved earlier, specifying it as 'official' (trusted to run on the server processor). You will need to log in the first time you use the :program:`omero script` command. The new script ID will be printed out: :: $ cd Desktop/scripts/ $ omero script upload demo_tutorial/Edit_Descriptions.py --official Previously logged in to localhost:4064 as root Server: [localhost] # hit 'enter' to accept default login details Username: [root] Password: Created session 09fcf689-cc85-409d-91ac-f9865dbfd650 (root@localhost:4064). Idle timeout: 10.0 min. Current group: system Uploaded official script as original file #301 You can add, remove and edit scripts directly in the OMERO\_HOME/lib/scripts/omero/ folder. Any changes made here will be detected by OMERO. Official scripts are uniquely identified on the OMERO server by their 'path' and 'name'. Any folders in the script path are created on the server under /lib/scripts/ E.g. the above example will be stored at /lib/scripts/examples/Edit\_Descriptions.py The ID of the script is printed after upload and can also be determined by listing scripts (see below). Run script ^^^^^^^^^^ You can run the script from OMERO.insight by browsing the scripts (see screen-shot above). A UI will be generated from the chosen script and the currently selected images or datasets will be populated if the script supports this (see :doc:`style-guide`). Or launch the script from the command line, specifying the script ID. You will be asked to provide input for any non-optional parameters that do not have default values specified. Any stdout and stderr will be displayed as well as any outputs that the script has returned. :: wjm:examples will$ omero script launch 301 # script ID Using session 1202acc0-4424-4fa2-84fe-7c9e069d3563 (root@localhost:4064). Idle timeout: 10.0 min. Current group: system Enter value for "IDs": 1201 Job 1464 ready Waiting.... Callback received: FINISHED *** start stdout *** * {'IDs': [1201L], 'Data_Type': 'Dataset'} * Processing Images from Dataset: LSM - .mdb * Editing images with this description: * No description specified * * Editing image ID: 15651 Name: sample files.mdb [XY-ch-02] * Editing image ID: 15652 Name: sample files.mdb [XY-ch-03] * Editing image ID: 15653 Name: sample files.mdb [XY-ch] * Editing image ID: 15654 Name: sample files.mdb [XYT] * Editing image ID: 15655 Name: sample files.mdb [XYZ-ch-20x] * Editing image ID: 15656 Name: sample files.mdb [XYZ-ch-zoom] * Editing image ID: 15658 Name: sample files.mdb [XYZ-ch0] * Editing image ID: 15657 Name: sample files.mdb [XYZ-ch] * *** end stdout *** *** out parameters *** * Message=8 Images edited *** done *** Parameter values can also be specified in the command. :: # simply specify the required parameters that don't have defaults $ omero script launch 301 IDs=1201 # can also specify additional parameters $ omero script launch 301 Data_Type='Image' IDs=15652,15653 New_Description="Adding description from script to Image" Edit and replace ^^^^^^^^^^^^^^^^ Edit the script and upload it to replace the previous copy, specifying the ID of the file to replace. :: $ omero script replace 301 examples/Edit_Descriptions.py Finally, you can upload and run your scripts from OMERO.insight. Other script commands ^^^^^^^^^^^^^^^^^^^^^ Start by printing help for the script command: :: $ omero script -h usage: /Users/will/Documents/workspace/Omero/dist/bin/omero script [-h] ... Support for launching, uploading and otherwise managing OMERO.scripts Optional Arguments: In addition to any higher level options -h, --help show this help message and exit Subcommands: Use /Users/will/Documents/workspace/Omero/dist/bin/omero script -h for more information. demo Runs a short demo of the scripting system list List files for user or group cat Prints a script to standard out edit Opens a script in $EDITOR and saves it back to the server params Print the parameters for a given script launch Launch a script with parameters disable Makes script non-executable by setting the mimetype enable Makes a script executable (sets mimetype to text/x-python) jobs List current jobs for user or group serve Start a usermode processor for scripts upload Upload a script replace Replace an existing script with a new value run Run a script with the OMERO libraries loaded and current login To list scripts on the server: :: $ omero script list Using session 09fcf689-cc85-409d-91ac-f9865dbfd650 (root@localhost:4064). Idle timeout: 10.0 min. Current group: system id | Official scripts -----+--------------------------------------------- 202 | /omero/export_scripts/Batch_Image_Export.py 203 | /omero/export_scripts/Make_Movie.py 204 | /omero/figure_scripts/Movie_Figure.py 205 | /omero/figure_scripts/Movie_ROI_Figure.py 206 | /omero/figure_scripts/ROI_Split_Figure.py 207 | /omero/figure_scripts/Split_View_Figure.py 208 | /omero/figure_scripts/Thumbnail_Figure.py 8 | /omero/import_scripts/Populate_ROI.py 209 | /omero/util_scripts/Channel_Offsets.py 210 | /omero/util_scripts/Combine_Images.py 211 | /omero/util_scripts/Images_From_ROIs.py (14 rows) If you want to know the parameters for a particular script you can use the params command. This prints out the details of the script, including the inputs. :: $ wjm:examples will$ omero script params 301 Using session 1202acc0-4424-4fa2-84fe-7c9e069d3563 (root@localhost:4064). Idle timeout: 10.0 min. Current group: system id: 301 name: Edit_Descriptions.py version: authors: institutions: description: Edits the descriptions of multiple Images, either specified via Image IDs or by the Dataset IDs. namespaces: stdout: text/plain stderr: text/plain inputs: New_Description - The new description to set for each Image in the Dataset Optional: True Type: ::omero::RString Min: Max: Values: IDs - List of Dataset IDs or Image IDs Optional: False Type: ::omero::RList Subtype: ::omero::RLong Min: Max: Values: Data_Type - The data you want to work with. Optional: False Type: ::omero::RString Min: Max: Values: Dataset, Image outputs: Debugging scripts ----------------- The stderr and stdout from running a script should always be returned to you, either when running scripts from the command line, via OMERO.insight or using the scripts API. This should allow you to debug any problems you have. You can also look at the output from the script in the OriginalFile directory, commonly stored in /OMERO/File/. The script file when executed is uploaded as a new OriginalFile, and the standard error, standard out are saved as the next two OriginalFiles after that. These files can be opened in a text editor to examine contents.