Scripting Service User Guide. OMERO 4.2

The  OMERO scripting service API allows Python scripts to be uploaded to the server and registered in the server database. These scripts can then be called from a client with the scripts running on the server. This allows extra functionality to be added to an OMERO server.

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 OmeroScripts page.

In addition to this guide, you may find the following pages useful for more information on using the OMERO Python API: PythonClientBeginners, OmeroClients, OmeroPy/Gateway.

Some example code PythonClientCodeExamples are provided, which can be used in client scripts or scripting-service scripts. More info and server code for the scripting service can be found  at scripts.py.

Scripts can be run from Insight, using a UI generated from the script. The script results can also be handled by Insight. Scripts should conform to the OmeroPy/ScriptingStyleGuide in order to improve usability of the script.

Script

The Python script that is to be run on the server needs to declare its name, description and the parameters it will require from the scripting service in order to run. These are defined in the following way (see the  Edit_Descriptions.py example):

import omero.scripts as scripts

if __name__ == "__main__":

    # name, description, parameters
    client = scripts.client('Edit_Descriptions.py', 'Edits the descriptions for all the images in a given Dataset.', 
    scripts.Long("Dataset_ID", optional=False, description="Specifiy the Dataset by ID"),
    scripts.String("New_Description", description="The new description to set for each Image in the Dataset"),
    )

This declaration must be called when the script is run, but does not necessarily have to come directly below the if __name__ == "__main__": statement.

Following this declaration, the OMERO session can be retrieved and used in the same way as in client scripts, meaning that no other changes are required to convert 'client' scripts into 'scripting service' scripts.

session = client.getSession()

Script-writing workflows

The workflow of writing, uploading, running, editing and deploying scripts is slightly different depending on whether you have admin access to your chosen server.

Regular User workflow

If you are using a server for which you do not have admin access, you must upload scripts as 'user' scripts, which are not trusted to run on the server machine. The OMERO scripting service will still execute these scripts in a similar manner to official 'trusted' scripts but behind the scenes it uses the client machine to execute the script. This means that any package imports required by the script should be available on the client machine.

The first step is to connect to the server and set up the processor on the client (See diagram to the right).

• You need to download 'Ice' from ZeroC and set the environment variables, as described  here.
• You also need the OMERO server download. Go to the OMERO downloads page and get the appropriate server package (Version must be OMERO 4.2 or later and match the server you are connecting to). Unzip the package in a suitable location.

In a command line terminal, change into the unzipped OMERO package, connect to the server and start user processor. For example for host: openmicroscopy.org.uk and user: will

$ cd Desktop/OMERO.server-Beta-4.2/
$ bin/omero -s openmicroscopy.org.uk -u will script serve user
$ password: ......

If you want to run scripts belonging to another user in the same collaborative group you need to set up your local user processor to accept scripts from that user. First, find the ID of the user, then start the user processor and give it the user's ID:

$ cd Desktop/OMERO.server-Beta-4.2/
$ bin/omero -s openmicroscopy.org.uk -u will user list
$ bin/omero -s openmicroscopy.org.uk -u will script serve user=5

From this point on, the user and admin workflows are the same, except for a couple of options that are not available to regular users. Follow on from 'script command line interface' below.

Admin workflow

It is assumed that scripts written by a server admin are "trusted" to run on the server without causing any disruption or security risks. Also, official scripts are available to all regular users of the server. Because these 'official' scripts are run on the server Processor, there is no need to start a separate processor.

Several official scripts are included in the release of OMERO and can be found under the lib/scripts/omero/ directory of the server package. It is possible to add and edit scripts directly in the 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'. When accessed from Insight, they will be organised by path (see screen-shot).

Server admins can also use the Scripting Service API or OMERO command line to edit and upload official scripts from a client-side file system. You will find it makes sense to organise your scripts on your local machine in the same way as in OMERO, so that the file structure is preserved when you upload scripts.

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.

The Scripting Service API or OMERO command line interface (described below) can also be used to list and run scripts on OMERO, either on the server machine itself (using -s localhost) or remotely.

script command line interface

The examples below assume that you have scripts in a folder E.g. Desktop/scripts/

For an example, download  Edit_Description.py and put it in a new folder: Desktop/scripts/examples. This can also be used as a template for other scripts.

You may find it useful to add the OMERO.server-Beta-4.2/bin/ folder to your PATH so you can call 'bin/omero' commands when working in the scripts folder. E.g:

export PATH=$PATH:/Users/will/Desktop/OMERO.server-Beta-4.2/bin/

Start by printing help for the script command:

$ omero script -h
usage: /Users/will/Documents/workspace/Omero/dist/bin/omero script
       [-h] <subcommand> ...

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 <subcommand> -h for more information.

  <subcommand>
    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 non-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

Change into the scripts directory and upload the script to the server. -s <server> -u <username> You will be asked for your password if you have not already logged in.

$ cd Desktop/scripts
$ omero -s openmicroscopy.org.uk -u will script upload examples/Edit_Descriptions.py

NB. Because non-official scripts do not have a unique path name, you will be able to run the upload command multiple times on the same file. This will create multiple copies of a file in OMERO and then you will have to choose the most recent one (highest ID) if you want to run the latest script. It is best to avoid this and use the 'replace' command (see below) once the script has been uploaded.

If you are an admin, you can use the --official option to specify that you are uploading an official script. Any folders in the script path are created on the server under /lib/scripts/

$ omero -s openmicroscopy.org.uk -u will script upload omero/examples/Edit_Descriptions.py --official

This will put the file in lib/scripts/omero/examples/Edit_Descriptions.py

List the scripts available to run on the server. Use the 'user' option to see user scripts. NB. You don't have to be an admin to list and run the official scripts.

$ omero -s openmicroscopy -u will script list user      # lists user scripts
 id  | Scripts for user                                                                            
-----+---------------------------------------------------------------------------------------------
 151 | examples/HelloWorld.py        
 251 | examples/Edit_Descriptions.py         


$ omero -s openmicroscopy -u will script list       # lists official scripts
 id   | Official scripts                            
------+---------------------------------------------
 101  | /omero/analysis_scripts/FLIM.py             
 1155 | /omero/example_scripts/Edit_Descriptions.py 
 102  | /omero/export_scripts/Make_Movie.py         
 152  | /omero/figure_scripts/Movie_Figure.py       
 601  | /omero/figure_scripts/Movie_ROI_Figure.py   
 901  | /omero/figure_scripts/ROI_Split_Figure.py   
 155  | /omero/figure_scripts/Split_View_Figure.py  
 1071 | /omero/figure_scripts/Thumbnail_Figure.py   
 603  | /omero/import_scripts/Populate_ROI.py       
 108  | /omero/setup_scripts/FLIM_initialise.py     
 109  | /omero/util_scripts/Combine_Images.py       
 1058 | /omero/examples/Edit_Descriptions.py

You can list scripts belonging to another user that are available for you (E.g. You are both in the same collaborative group) by using the user ID as described above:

$ omero -s openmicroscopy.org.uk -u will user list
$ omero -s openmicroscopy.org.uk -u will script list user=5

Now run the script, specifying the script ID. In this case, user will is running his own 'user' script (ID 251) which will require the user-processor running as described above. You will be asked to provide input for any non-optional parameters that do not have default values specified.

$ omero -s openmicroscopy.org.uk -u will script launch 251
Enter value for "Dataset_ID":

Parameter values can also be specified in the command.

$ omero -s openmicroscopy.org.uk -u will script launch 251 New_Description="Demo description from the command line"

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.

$ omero -s openmicroscopy.org.uk -u will script params 251
id: 1155
name: Edit_Descriptions.py
version: 4.2.0
authors: Will Moore, OME Team
institutions: 
description: Edits the descriptions for all the images in a given Dataset.
namespaces: 
stdout: text/plain
stderr: text/plain
inputs:
  Edit_Description - The new description to set for each Image in the Dataset
    Optional: True
    Type: ::omero::RString
    Min: 
    Max: 
    Values: 
  Dataset_ID - Specifiy the Dataset by ID
    Optional: False
    Type: ::omero::RLong
    Min: 
    Max: 
    Values: 
outputs:

Edit the script and upload it to replace the previous copy, specifying the ID of the file to replace.

$ omero -s openmicroscopy.org.uk -u will script replace 251 omero/examples/Edit_Descriptions.py

Finally, you can run your script or another user's from Insight. The scripts uploaded as above will be found under 'User Scripts' in the scripts menu. In both cases, you will need to have your user processor running and set up to accept scripts from the appropriate user.