My first Jython task

Prerequisites

Before reading this tutorial, you should have some basic familiarity with scripting in HIPE and the Jython language. If this is not the case, please read Chapter 1 of the Scripting and Data Mining guide before continuing.

What is a HIPE task?

A HIPE task is everything you see in the Task view of HIPE.

Double click the All folder in the Tasks view to open it. Then type the first letters of loadObs to quickly jump to this task. Double click on the loadObs entry to open its graphical interface in the Editor view.

We can make a following observations about a HIPE task:

  • A task does a specific operation. Hover your mouse pointer on the loadObs entry in the Tasks view. A tooltip appear with a description of what this task does (in this case, loading an observation into HIPE).
  • A task takes input parameters. In the Inputs section of the loadObs interface you can see two input parameters, path and obsid. The path parameter is mandatory, while obsid is optional. Hover your mouse pointer on the parameter names to see tooltips with longer description. Note also that each parameter is of a specific type (for instance, path is of type String).
  • A task returns output parameters. In the Outputs section of the loadObs interface you can see the obs output parameter. This is the name of the variable that will contain the result of the task execution. Note that in this case the parameter has a pre-filled default value. This can also happen with input parameters.
  • A task has links to more information. At the bottom of the loadObs interface you can click Source to examine the source code of the task, and Help to view the task entry in the User's Reference Manual.

HIPE tasks can be written in Jython and Java. Jython is the language you use to write scripts in the Editor view of HIPE. Java is the language most of HIPE itself is written in. Writing tasks in Jython should be all you need for your data processing needs.

A simple HIPE task

The following is a simple Jython task that takes a table dataset as input and outputs an array with the averages of each column of the table dataset. For more information about table datasets, see the Scripting and Data Mining guide.

class TableAverageTask(JTask):  # 1
   'Averages the columns of a Table Dataset.'
   def __init__(self, name="tableAverage"):
       JTask.__init__(self, name)
       self.setDescription("Computes the average of each column of a Table Dataset.")  # 2
       p = TaskParameter("table", valueType = TableDataset, type = IN, mandatory = 1)  # 3
       p.description = "The table of whose columns to compute the average"  # 4
       self.addTaskParameter(p)
       p = TaskParameter("average", valueType = Double1d, type = OUT)  # 5
       p.description = "The array of averages of the table's columns"
       self.addTaskParameter(p)
   def execute(self):  # 6
       columns = self.table.columnCount
       self.average = Double1d(table.rowCount)
       for column in range(columns):
          self.average.add(table.getColumn(column).data)
       self.average = self.average / columns

Let us examine some lines of the script.

  1. This line defines a class called TableAverageTask. A class is basically a bundle of variables and functions, called methods, acting on these variables. For more information on classes in Jython, see the Scripting and Data Mining guide.
  2. This line sets the description of the task. It is what you see in the tooltip that appears when you hover on the task name in the Tasks view of HIPE. Every task must have a description.
  3. This line defines a task parameter. This parameter is called table, is of type TableDataset, is an input parameter and is mandatory.
  4. This line defines the description of the input parameter. Task parameters, like the task itself, must always have a description.
  5. This line defines the output parameter, called average. It is better to avoid vague parameter names such as result.
  6. This line defines the execute method. This is the heart of any task: it is the function that does the actual data processing.

The code you just examined defines the task itself, but to use it in HIPE there are two more steps you need to take:

  1. You must instantiate the task. That is, you must create an object from the TableAverageTask class.
  2. You must then register the task instance, so that HIPE is aware of the task and can put it in the right places in the Tasks view.

These additional steps are accomplished by the following lines. Note that these lines are not indented and not part of the TableAverageTask class.

tableAverage = TableAverageTask()  # 1
toolRegistry = TaskToolRegistry.getInstance()
toolRegistry.register(tableAverage, [Category.GENERAL, Category.SPECTRUM])  # 2
del(toolRegistry)

  1. Note that from the task name TableAverageTask we obtained tableAverage as instance name. This is a general rule. The task name is made of words with capitalised initials and ends with Task. The instance name starts with a lower case letter and drops the Task part.
  2. Here we register the task in the GENERAL and SPECTRUM categories. This means that the task will appear in the General and Spectrum folders in the Tasks view, in addition to the All folder. Of course this task has nothing to do with spectra: we include it in the SPECTRUM category for illustration purposes.

Turning the task into a HIPE plug-in

Now that your task is complete, you can turn it into a HIPE plug-in, so that you and your colleagues can easily install and uninstall it from HIPE.

To turn the tableAverage task into a plugin, follow these steps:

  1. Copy all the source code into a file called plugin.py. You can also download the file from this page: TODO PUT LINK
  2. Add the plugin.py file to a zip file (or download the zip file from TODO put link). The zip file name must be made by three parts:
    • The plug-in name, for example TableAveragePlugin.
    • An underscore character.
    • The plug-in version number, which can be any combination of digits separated by dots. For example, 0.1, 1.0.0, 2.3.3 and so on.

The plug-in is now ready. Read on to find out how to install it.

Installing the plug-in

To install the plug-in, follow these steps:

  1. In HIPE, choose Tools --> Plug-ins. The _Plug-ins_dialogue box opens.
  2. Click the Install new button. The Install new plug-in dialogue box opens.
  3. Since this is a local file, click the folder button and navigate to the zip file you just created. Click the Open button.
  4. Restart HIPE to complete the installation.

Now you should see the tableAverage task in three places within the Tasks view: in the All, General and Spectrum folders.

Executing the plug-in

Double click on any of the tableAverage entries in the Tasks view. A dialogue box opens in the Editor view. Although we did not write a single line related to graphical interfaces in our TableAverageTask class, the task framework made one available for free.

If you hover the mouse pointer on the table entry in the Inputs panel, you will see a tooltip informing you that the parameter is mandatory and must be a TableDataset. You will also see the short description we added in the source code. The same happens with the result parameter in the Outputs panel.

Create a variable by issuing the following command in the Console view:

notValid = Double1d([3.0, 5.0, 8.2])

This is not a good input for the task. Try dragging the notValid entry in the Variables view to the small grey circle next to the table entry in the task dialogue box. This is how you can set parameters via point and click, but in this case the small circle becomes red. In the source code we specified that the input must be a TableDataset, so HIPE is rejecting everything else. We could have specified even more stringent conditions (for example, that the TableDataset must not be empty).

Issue these commands to create a valid TableDataset:

TODO: put commands.

Sharing the plug-in

To share the plug-in with your colleagues, you can either send them directly the zip file, or put it on a Web server, so that they can install it directly by pointing HIPE to the file URL. For example, you can install the little task described in this tutorial by choosing Tools --> Plug-ins_in HIPE, clicking the _Install new button and entering the following in the Enter URL for plug-in field: TODO: put URL.

Edit | Attach | Watch | Print version | History: r11 | r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r3 - 2011-09-13 - DavideRizzo
 
This site is powered by the TWiki collaboration platform Powered by Perl