Search:

[Advanced Search]



The Runtask Hera Interface

Runtask Hera is the command line interface to Hera that allows you to run any of the software tasks that are installed on the Hera servers to analyze data files that reside on your local computer. You execute the task the same way you would if the software were installed locally, by specifying the name of the task on the command line followed by the values of any task parameters, except that you preface the entire command with the string "fv -r". The 'runtask' interface then transparently uploads the input data files from your computer to a temporary disk area on the Hera server, runs the task, and then downloads any output text and data back to your local computer. If the task is expected to take a while to run, you may optionally request that Hera send you an email notification when the task has completed, at which point you may reconnect to Hera and download the results. To give a simple example, to run the ftlist program to get a listing of all the HDUs and table columns in the FITS file myfile.fits on your local machine, you would enter the following command:
    fv -r ftlist myfile.fits hc

The Runtask Hera interface is especially useful if you only have an occasional need to run the software or would like to experiment with it to see if it meets your needs. For example, if you only need to run the arfgen and rmfgen calibration tasks in the XMM SAS package, then instead of having to install the entire large SAS package on your computer, you can simply use Runtask Hera to execute these 2 tasks. Very frequent users of the software should consider installing the software locally to obtain the best performance.

Note that the standard Hera user interface also provides a way to run the software on your local data files. It has the advantage that you can use the graphical parameter editor to enter all the input parameters for the task, instead of entering them on the command line. It also allows you to view the help file for any task on your web browser with a single click of the 'Help' button.

Setup Procedure

You should follow the Getting Started instructions to configure your computer to use Hera. This basically involves installing the small fv program on your local machine and then testing that the required network connections are functioning.

Simple Examples

To run one of the available software tasks using the runtask Hera interface, you enter the command exactly as you would if the software were installed locally, except that you preceed the command with 'fv -r'. For example, to run the 'fhelp' task get help about the fverify task, you would enter the command

    fv -r fhelp fverify

After a short pause, while the connection to the Hera server is established, the help file for the fverify task (which verifies that the input file is a valid FITS file) will be displayed in your terminal window. Once the task has completed, the connection to the Hera server is closed.

To run the fverify task itself, enter the command

    fv -r fverify myfile.fits

where 'myfile.fits' is the name of the file to be verified. After another short pause to reestablish the connection to the Hera server, the runtask Hera interface will copy the input file to the hera server and then run the fverify task. Finally, the output report from the task will be displayed on your terminal and the connection to the Hera server will be closed.

In the cases where the task creates new output data files, the files are automatically download from the Hera server to your current work directory. For example, the command

    fv -r fcopy myfile.fits outfile.fits

will copy the input file (myfile.fits) to the hera server, run the fcopy task to create the new FITS file called outfile.fits, and then copy the output file back to your local directory.

More Features

Most of the features of the interactive parameter interface that are available when running these software tasks locally are also available when using the runtask Hera interface. In particular, you can specify the task parameters in positional order, or by using the 'parameter = value' syntax, as in these examples which call the fsort table sorting task:

    fv -r fsort intable.fits temp.fits
    fv -r fsort infile=intable.fits outfile=temp.fits
    fv -r fsort infile=intable.fits outfile=temp.fits method=insert

If you do not specify all the required input parameters, as in

    fv -r fsort intable.fits

Then you will be prompted for the value of any required parameters that were not specified (the name of the output file in this case).

Scripting

Scripting is a powerful tool available on runtask. A script file contains a list of commands (with parameters) in a text file. The commmand to run the script is:

    fv -r runsc script_file

"runsc" is the Hera system defined command to start runtask module in script mode. And the next parameter on the command line must be denoting a valid script file.

In the script file, user can specify the commands in sequence of execution. For example,

    ftcopy infile='rate.fit[col rate]' just_rate.fit
    ftlist rate.fit hck outfile=ftlist.out
    fdump rate.fit outfile=fdump.time.out columns=time rows=-
    fdump rate.fit outfile=fdump.rate.out columns=rate rows=-

Output will be downloaded to user local directory when the execution of the whole sequence is done. From above example, the result files been downloaded to user local machine are:

    just_rate.fit, ftlist.out, fdump.time.out, fdump.rate.out

The script also can contain information that been created in one sequence and used in another one. For example,

    ftcopy 'rate.fit[col rate]' just_rate.fit
    ftcopy 'just_rate.fit[ rate > 100 ]' rate_gt_100.fit
    ftlist just_rate.fit hc outfile=ftlist.rate.out
    ftlist rate_gt_100.fit hck outfile=ftlist.rate_gt_100.out

From above example, the result files been downloaded to user local machine are:

    just_rate.fit, rate_gt_100.fit, ftlist.rate.out, ftlist.rate_gt_100.out

The script also can contain temporary file name to be used between commands. The temporary file is denoted in script by a format of "%n" where n is a positive integer (i.e., %w12, or %123A is not a temporary file name.)

    ftcopy 'rate.fit[col rate]' %1
    ftcopy '%1[ rate > 100 ]' %2
    ftlist %1 hc outfile=ftlist.rate.out
    ftlist %2 hck outfile=ftlist.rate_gt_100.out

The file with a temporary file name will not be downloaded to user local machine when the operation sequence is finished. From above example, the result files been downloaded to user local machine are:

    ftlist.rate.out, ftlist.rate_gt_100.out

Command Switches

There are 3 optional switches that can be applied to the runtask option:

-p Display the contents of the task parameter file after the task has finished.

-u Upload a list of files to the Hera server before executing the task.

-nowait [email address] Send an email notification when the task has completed

The -p option is useful when running tasks that write the value of output parameters into the parameter file, but it is also a useful debugging option to confirm the value of all the input parameters, e.g.,

    fv -r -p ftstat myimage.fits

The -u option is only useful when running the small number of tasks in which the input files are not all specified by task parameters on the command line. When running most tasks, the runtask Hera interface is able to recognize the names of any input files and automatically upload them to the Hera server before running the task. In a few cases however, the user must explicitly specify which input files are needed. For example, when running the Xspec spectral fitting program you would typically need to specify the names of the input source and background pha files, and the .rmf and .arf calibration files:

    fv -r -u source.pha,back.pha,file.rmf,file.arf xspec

This will upload the 4 specified files to the Hera working directory before starting up Xspec. You can then interactively use the 'data', 'backgrnd', 'response' and 'arf' commands in xspec to read those files. You may optionally write the list of files to be uploaded into an ASCII text file (one filename per row) and specify the name of the text file with the command:

    fv -r -u @filelist xspec

Only FITS files and small text files may be uploaded.

The -nowait option is useful if the task is expected to take a long time to finish and you do not want to keep the terminal connection open for the entire time. In this example:

    fv -r -nowait dsmith@yale.edu fsort intable.fits temp.fits

the local connection to the Hera server will be terminated as soon as the fsort task starts. When it finishes, an email message will be sent to the specified email address with instructions on how to download the output sorted file.

Getting help

Here are the commands for getting help on the the available tasks:

To get a list of all FTOOLS tasks:

    fv -r fhelp ftools
To get help on any individual FTOOLS task:
    fv -r fhelp taskname
To get help on any individual CIAO task:
    fv -r ahelp taskname

Plotting and Graphics

Most HEASOFT tasks that generate plots or graphs using pgplot can be run using the POW device driver. Specify /POW as the type of plotting device with the 'cpd' command or as the value of the input plot device parameter.

About the 'current working directory'

When files are uploaded to the Hera server, they are all copied into the 'current working directory', regardless of their original location on your local machine. Similarly, any output files, or modified input files will be copied back to your local 'current working directory'.

Return to Hera main page