The Runtask Hera Interface
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 ProcedureYou 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.
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
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
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
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 FeaturesMost 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 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
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).
ScriptingScripting 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:
"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,
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:
The script also can contain information that been created in one sequence and used in another one. For example,
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:
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 '%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:
Command SwitchesThere 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.,
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:
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:
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:
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 helpHere are the commands for getting help on the the available tasks:
To get a list of all FTOOLS tasks:
Plotting and GraphicsMost 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'.