6. Preparing the Data for Processing

Throughout this document, data from the HEASARC archive are used to illustrate how to run tasks for each instrument on XMM-Newton; new users are encouraged to use these sample data, though it should be noted that any data from the relevant instrument and science mode will do. Information about the example datasets are in Table 6.1.

Table 6.1: Example datasets used in this Guide.

Instrument	Chapter	ObsID	Object
EPIC (Imaging mode)	7	0123700101	Lockman Hole
EPIC-PN (Timing mode)	8	0843840201	Holmberg II
EPIC-MOS (Timing mode)	9	0070740101	Mkn 841
RGS	10	0134720401	Capella
OM (Image mode)	11.2	0123700101	Lockman Hole
OM (Fast mode)	11.3	0411081601	Mkn 421
OM (Grism mode)	11.4	0125320801	BPM 16274

A number of SAS tasks, including those which rerun the pipeline, require an up-to-date list of calibration files (the CIF file) and extended Observation Data File (ODF) summary file. These are obtained by running the tasks cifbuild and odfingest, respectively. Because of these dependencies, it is strongly recommended that users run these tasks, whether they plan to rerun the pipeline or not. Since these tasks are very straightforward to run, we will just call them from the command line and save the SAS GUI for more interesting tasks.

First, gunzip the all gzipped files in the ODF directory. If necessary, rename all files in the ODF directory to upper case. This can be done using the script provided by the NASA/GSFC XMM-Newton GOF.

 gunzip ODF/*.gz

6.1 cifbuild

Many SAS tasks require calibration information from the Calibration Access Layer (CAL). Relevant files are accessed from the set of Current Calibration File (CCF) data using a CCF Index File (CIF). A CIF is included in the pipeline products (*CALIND*), but if the CCF has been updated it can be recreated by the user by simply typing

 cd ODF

 cifbuild

The task cifdiff can be used to compare the new CIF with the old:

 cifdiff calindex1set=ccf.cif calindex2set=CALIND.FIT

where

 calindex1set - name of the first file to be compared, in this case the output from
$$ the current run of cifbuild

 calindex2set - name of the second file to be compared, in this case the (renamed)
$$ pipepine product file

If the CAL has changed, it is a good idea to repipeline the data using the new CIF. To help determine whether it is reasonable to repipeline the data, the CCF release notes should be examined (see §2.5). CCF files can be downloaded directly from the SOC website see (see §5.2).

To use the updated CIF file in further processing, you will need to reset the environment variable SAS_CCF:

 setenv SAS_CCF /full/path/to/ODF/ccf.cif

6.2 odfingest

The task odfingest extends the Observation Data File (ODF) summary file with data extracted from the instrument housekeeping data files and the calibration database. It is only necessary to run it once on any dataset, and will cause problems if it is run a second time. If for some reason odfingest must be rerun, you must first delete the earlier file it produced. This file largely follows the naming convention described in §3.2.4, but has SUM.SAS appended to it. After running odfingest, you will need to reset the environment variable SAS_ODF to its output file. To run odfingest and reset the environment variable, simply type:

 odfingest

 setenv SAS_ODF /full/path/to/ODF/full_name_of_*SUM.SAS

The user will likely find it useful to alias these environment variable resets in their login shell (.cshrc, .bashrc, etc.).

The rest of this guide consists of step-by-step examples of how to reprocess and analyze data for the EPIC, RGS, and OM; the chapters for each instrument, and which way that SAS is used (on the command line or through a graphical user interface) are listed in Table 6.1. At the start of each chapter, it is assumed that the user has downloaded the data, initialized SAS, and set the environment variables, as listed in 5.3. It is also assumed that the CIF file is up-to-date, the *SUM.SAS file exists, and the appropriate environment variables were reset as needed.

It should also be noted that sometimes, the task calls on the command line are long - too long to comfortably put in one line of text on a printed page. In those cases, we will use a “\” sign to indicate that the command is continued on the next line. When actually using the command, it should be on all one line.

6.3 Welcome to the SAS GUI

Many first time users will probably find the GUI more useful than the command line. To invoke it, simply type

 sas &

A window will appear with two panels. The upper one will contain task names, what group they belong to (such as utility, epic, timing, calibration, etc.) and a short description of each. The lower one will contain information about environment variables, and as tasks are invoked, feedback from the tasks. The interface is shown in Fig. 6.1. Remember that tasks place output files in whatever directory you happened to be in when the SAS GUI was called, so either open and close the GUI in the directory where you want the output or move the files to the directory they should be in.

A type of file called the event file is crucial to almost all tasks that SAS runs. If using the GUI, you have the option to either type in the name of the event file in the appropriate box, or browse your computer and select it. Note that if you use the browse option, you will also have to select the “EVENTS” extension, or SAS will not know the correct data to use! For this reason, we recommend simply typing in the name of the file; if you do, you can include the EVENTS extension if you wish, but there is no need to: simply typing e.g. m1.fits will work just as well as m1.fits:EVENTS.

Figure 6.1: The SAS GUI. To locate and invoke a task one need only start typing the task name, and when it is highlighted, press carriage return. Alternatively, double-click on the task name.