The Runtask Hera Interface
-
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).
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
- fv -r fhelp taskname
- fv -r ahelp taskname