TWiki> Public Web>DpHipe>MyFirstJythonTask (revision 7)EditAttach

PDF Version Portrait Landscape

Help Did you spot something wrong or missing on this page? If you have an account on this TWiki, you can fix it yourself by editing the page. If you don't have an account, you can send a message to the Editorial Board to tell us about it. Thank you in advance!

My first Jython HIPE task

This tutorial will teach you the following:

  1. What a HIPE task is.
  2. How to write a simple Jython task.
  3. How to add the task to HIPE as a plug-in.
  4. How to share your plug-in with other users.

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 row of the table dataset. For more information about table datasets, see the Scripting and Data Mining guide.

class TableAverageTask(JTask):  # 1
   'Averages the rows of a Table Dataset.'
   def __init__(self, name="tableAverage"):
       JTask.__init__(self, name)
       self.setDescription("Computes the average of each row of a Table Dataset.")  # 2
       p = TaskParameter("table", valueType = TableDataset, type = IN, mandatory = 1)  # 3
       p.description = "The table of whose rows to compute the average"  # 4
       p = TaskParameter("average", valueType = Double1d, type = OUT)  # 5
       p.description = "The array of averages of the table's rows"
   def execute(self):  # 6
       columns = self.table.columnCount
       self.average = Double1d(table.rowCount)
       for column in range(columns):
       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 table 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

  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 You can also download the file from this page: TODO PUT LINK
  2. Add the 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 table dataset, so HIPE is rejecting everything else. We could have specified even more stringent conditions (for example, that the table dataset must not be empty).

Issue these commands to create a valid table dataset with three columns:

x = Double1d.range(5)
table = TableDataset(description = "A test table")
table["First"] = Column(x)
table["Second"] = Column(x + 1)
table["Third"] = Column(x + 2)

Now drag the table variable from the Variables view to the circle next to the table entry in the task dialogue box. The circle becomes green. Click the Accept button to execute the task. Two things happen:

  • The new variable average appears in the Variables view. This is the output of the task. Double click on it to inspect the output and make sure that the task did the correct calculations.
  • A new command appears in the Console view: average = tableAverage(table=table). This is the command line equivalent of executing the task from the graphical interface.

You have now successfully added your task to HIPE as a plug-in and made sure that it works correctly. The next step is to share your task with other users.

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.

Where to go from here

  • For an introduction to writing task in Java, see this tutorial.
  • For more information on writing tasks, see this page.
  • For more information on creating HIPE plug-ins, see the developer's manual of the plug-in infrastructure.

Edit | Attach | Watch | Print version | History: r11 | r9 < r8 < r7 < r6 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r7 - 2011-09-16 - DavideRizzo
This site is powered by the TWiki collaboration platform Powered by Perl