4. Hera

The Hera facility at HEASARC can run tasks from numerous environments, such as CIAO, xselect, and ftools, and includes the SAS environment, which is the software designed specifically for the reduction and analysis of XMM-Newton data. Hera lets users have access to this software remotely, without asking the users to download to the user's local machine such things as the calibration files or software. Data files stored on the user's local machine may be copied to a private space on the Hera server, or downloaded directly from the HEASARC data archive.

There are two flavors of Hera: anonymous and standard. These have identical graphical interfaces and produce identical outputs. Anonymous Hera is accessed though the HEASARC data archive by simply clicking on the ``H'' next to the dataset the user would like to examine. Files created through anonymous Hera will be deleted at the end of the session, but the user will be given the option to save the files to a new or existing Hera account. Standard Hera requires the user to install fv, available through the HEASARC, on his or her local machine (see § 4.2). Standard Hera requires the user to log in to an account, and only processes data that is located on the Hera server. Files may be transferred there via anonymous Hera, HEASARC archive links, or by right-clicking the filename on the local directory list in the Hera GUI and dragging it to the desired location. Please note that only file at a time may be copied, and that due to security restrictions, whole directories cannot be copied (see § 4.1).

There is no difference between the data analysis tasks in Hera's SAS and a locally-installed version of SAS - the only difference, as far as the user is concerned, is in the interface. Users who are familiar with SAS will need only to learn to navigate the Hera ``wrapper''; all tasks, procedures, and techniques of data reduction are the same as if SAS were locally installed.

For the sake of simplicity, it will be assumed throughout this Guide that the user will only use SAS tasks (unless where explicitly stated). Thus, anonymous and standard Hera are synonomous with the locally-installed SAS GUI and command line.

4.1 Placing Data on the Hera Servers

Please be aware that network security regulations at NASA forbid the uploading of multiple files at once, or directories from local machines to Hera servers! Therefore, if you want to run tasks like the repipelining procedures (i.e., emchain, emproc, epproc), which require data from the ODF directory, you must download the ODF directory (and the PPS directory) to Hera disk space directly from the HEASARC archive. Users of standard Hera can click on the ``Save to Hera'' button in the Data Products Retrieval tab of the Browse Query Results. Users with Hera accounts will be prompted for their login information, while new users will be given the opportunity to make an account. For users of anonymous Hera, the data will be downloaded to a temporary directory for analysis. They will be given the option to save their data in an account at the session.

4.2 Setting Up and Running Standard Hera

Hera currently runs on unix, Mac OS, and Windows. Unix users should install fv (version 4.4 or higher). Both Mac and Windows users will need to install a special Hera utility in addition to fv. Detailed information on downloading and installing the packages can be found at
http://heasarc.gsfc.nasa.gov/docs/software/ftools/fv/fv_download.html

The Hera GUI is called by either typing fv -hera on the command line or fv & on the command line and clicking on the ``Connect to Hera...'' option in the fv pop-up window, and logging in (see Figs. 4.1 and 4.2, respectively). If you do not yet have a Hera account, enter a username in the right-hand textbox and follow the instructions.

After logging in, the main Hera window will appear (see Figure 4.3). The main Hera window has five sections. The upper panel on the right side (``Remote Directory List'') lists the directories and files on the NASA server in the user's account. Directly beneath it is a panel showing the directories and files on the user's local machine (``Local Directory List''). To the left are three smaller panels: the top lists any scripts the user may have (``Special Analysis Scripts''), the middle shows which packages and tasks are available (``Available Tools''), and the bottom lists which task is active, gives a short task description, and has the clickable ``Help'', ``Run Tool...'', and ``Cmd Window'' buttons. New accounts are created with a directory called data and two sample fits files, visible in the Remote Directory List window. Right-clicking on these files will bring up various options, including copying, deleting, and renaming them. Similarly, right-clicking on the data directory will bring up options including renaming the directory or creating a new one (under data).

Figure 4.1: The fv menu list.

Figure 4.2: The Hera login screen.

Mission-specific software is found by single-clicking on the mission name in the middle window. SAS tasks are listed under ``XMM-SAS''. Once a file has been selected in the Remote Directory List panel by single-clicking it, a task can be run on it by either single-clicking on the task name, then clicking ``Run Tool...'', or by double-clicking the tool name. When a task is selected, its description will automatically appear in the ``Description'' box. Clicking on the ``Help'' button will pull up a website detailing the highlighted task, and clicking ``Cmd Window'' will cause a blank window with command line to pop up (see Fig. 4.4).

Running a task will cause a parameter window to appear, where the user can set the parameter values. When the parameters are set, clicking ``Run'' in the parameter window will run the task. If a Command Window is not already open, one will appear automatically, echoing the task name and all its parameter values. If Hera encounters problems while running the task, the warnings or error messages will be displayed there.

Figure 4.3: The main Hera GUI.

Figure 4.4: The Command Window.

Command lines can often be quite long with a variety of parameters. To avoid considerable typing when creating command scripts, a feature of the standard Hera GUI interface can be of assistance: when invoking a task through the GUI, a copy of the full command appears in the Command Window; this can quickly be cut and pasted into a text file for future use.

4.3 Command Line Hera Syntax and Logic

4.3.1 Table and Command Line Syntax

Veteran command-line SAS users, take note: there is some flexibility in command line Hera syntax, but less than what is in locally-installed SAS! First, all input tables in Hera are assumed to be event tables. Thus, there is no need to specify the EVENTS table when opening a file. The valid commands for opening a file in the Command Window are, therefore,

evselect table=filtered.fits
evselect table='filtered.fits'
evselect table="filtered.fits"

The following syntaxes, while valid in the local installation of SAS, are not valid in Hera!

evselect table=filtered.fits:EVENTS
evselect table='filtered.fits:EVENTS'
evselect table="filtered.fits:EVENTS"
evselect table=filtered.fits%EVENTS

Further, the following are all valid task calls on the command line that result in identical operations:

evselect updateexposure=T
evselect updateexposure=yes
evselect updateexposure='yes'
evselect updateexposure="yes"
However,

evselect -updateexposure=T
evselect -updateexposure=yes
evselect -updateexposure='yes'
evselect -updateexposure="yes"
evselect -updateexposure=T
evselect -updateexposure=yes
evselect -updateexposure='yes'
evselect -updateexposure="yes"

are not correct syntax.

One format is not ``more correct'' than another, and the choice of which to use is left to user preference. In this guide we adopt the simplest format, and use no dashes and only single quotation marks only when required, such in denoting a list or filter, e.g.,

evselect filtertype=expression expression='(X,Y) in CIRCLE(26920,26400,500)'

4.3.2 Filtering Logic

Filtering event files requires some command of the SAS logical language which consists of familiar arithmetic and Boolean operators and functions. A full description can be found at the XMM-Newton SOC website, and will be explained in this Guide as they are used.