The Science Analysis Software (SAS, http://xmm.esac.esa.int/sas/), developed by the Survey Science Centre (SSC) and Science Operations Centre (SOC), is a suite of about 125 programs and scripts that perform data reduction, extraction, and some analysis of XMM-Newton data. The Pipeline Processing System (PPS), comprised of a superset of the SAS suite and Perl scripts, is run at Leicester University (http://xmmssc-www.star.le.ac.uk/) to create the basic data products provided to the Guest Observer from the satellite ancillary and science data. SAS is not designed for higher level scientific analysis such as spectral fitting and temporal analysis, but does provide for the creation of detector response files and barycentric corrected event timing information. SAS includes extensive EPIC and OM source-detection software. The SAS product files conform to OGIP FITS standards so any high-level analysis package used in high-energy astrophysics should theoretically be capable of processing XMM-Newton data. For example, the HEASoft package, http://heasarc.gsfc.nasa.gov/docs/corp/software.html, of the High Energy Astrophysics Science Archive Research Center (HEASARC, http://heasarc.gsfc.nasa.gov/) at NASA/GSFC and the CIAO package (http://asc.harvard.edu/ciao/) of the Chandra X-ray Observatory Center (http://chandra.harvard.edu/) can both be used with XMM-Newton data files.
The primary guide for the installation of SAS can be found through
the SOC at
http://xmm2.esac.esa.int/sas/8.0.0/installation/.
Because of the complexity of the
SAS installation, it is strongly
recommended that users download and install the binary executables
rather than compiling SAS from source code (which also necessitates the
purchase of commercial software). It should also be noted
that ``optional'' components, while not needed for running SAS
tasks from the command-line, are critical to running SAS from
the GUI. These optional components are listed at the SOC page
http://xmm2.esac.esa.int/sas/8.0.0/requirements/.
XMM-Newton data reduction and analysis requires extensive calibration data which must be available under a Current Calibration File (CCF) directory. Information on the CCF and instructions for downloading/mirroring the files can be found under the SOC XMM-Newton Calibration page (http://xmm2.esac.esa.int/external/xmm_sw_cal/calib/index.shtml) links to the CCF release notes. In addition, background event files and canned spectral response files can be found under http://xmm2.esac.esa.int/external/xmm_sw_cal/background/index.shtml.
There are a few parameters which need to be set for the proper operation of SAS. Two are taken care of by the initialization script, SAS_DIR and SAS_PATH. These both set the SAS directory path. The remaining parameters, listed below, still need to be set. (The commands should, of course, be modified to be appropriate for your specific setup.)
setenv SAS_CCFPATH /full/path/to/CCF Sets the directory path to the CCF data
setenv SAS_ODF /full/path/to/ODF Sets the directory path to the ODF data
setenv SAS_CCF /full/path/to/ODF/ccf.cif Sets the Calibration Index File (CIF) path
and file name
Please note that SAS_CCF can also be set after the creation of the ccf.cif file with cifbuild (see §4.5.1). Also, while not necessary to run SAS, the following parameters are useful to know about and should be set.
setenv SAS_VERBOSITY 3 Sets the verbosity, 1 => little, 10 => lot
setenv SAS_SUPPRESS_WARNING 3 Sets the warning level, 1 => little, 10 => lot
setenv SAS_IMAGEVIEWER ds9 Sets the default image viewer; in this case,
it is ds9, but should be set to whatever
the user prefers.)
Finally, SAS is invoked by sourcing the script that came with the SAS package:
source /full/path/to/xmmsas_20080701_1801/setsas.csh Initializes SAS
or
source /full/path/to/xmmsas_20080701_1801/setsas.sh Alternate SAS initialization
SAS can now be used on the command line. To invoke the GUI, type:
sas &
To verify the SAS-specific settings, type env | grep SAS.
It is strongly recommended that users include these environmental settings and make an alias to the initialization script in their login shell file (.cshrc, .bashrc, etc.)! It will save a lot of typing and lower the potential for frustration.
SAS tasks can be run equally well from the command line and from the SAS GUI. In this document we will demonstrate the use of some of the more commonly used tasks from both the GUI and command line, although in some instances, we only give command line examples. In these cases, the GUI can still be used - the user need only set the parameters there.
The MPE Analysis Guide, http://www.mpe.mpg.de/xray/wave/xmm/cookbook/preparation/change.php demonstrates many of the common tasks using GUIs.
Command lines can often be quite long with a variety of parameters. To avoid considerable typing when creating command scripts a feature of the GUI interface can be of assistance. When invoking a task through the GUI a copy of the full command appears in the dialog box, from where it can then be cut and pasted.
There are several useful features of the command-line interface that users should be aware of. 1) If the dialog parameter is included in the command line, the task GUI will pop up with all parameters in the command line preset. This allows the use of the GUI interfaces at the task level without having to go through the main SAS GUI. 2) If the manpage parameter is included in the command line, the task documentation will pop up in a web browser window. 3) In addition, the command sashelp doc=sas_task will pop up a web browser window with the documentation for the task sas_task as well.
The command documentation (i.e., the pages brought up by sashelp doc=sas_task or sas_task manpage) has an Errors section. Common warning messages produced by the tasks and their meanings are listed here. This feature is very useful.
There is some flexibility in command line syntax in SAS. The following are all valid task calls on the command line that result in identical operations:
rgsproc withsrc=F
rgsproc withsrc=no
rgsproc withsrc='no'
rgsproc withsrc="no"
rgsproc -withsrc=no
rgsproc -withsrc='no'
rgsproc -withsrc="no"
However,
rgsproc -withsrc=F
rgsproc -withsrc=no
rgsproc -withsrc='no'
rgsproc -withsrc="no"
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 ABC guide we adopt the simplest format, and use no dashes and only single quotation marks only when required, e.g.,
rgsproc withsrc=no orders='1 2 3'
where, in this case, the quotes provide the task with a list.
When a task requires the use of a table within a file there are also several valid syntaxes, e.g.,
xmmselect table=filtered.fits:EVENTS
xmmselect table="filtered.fits:EVENTS"
xmmselect table=filtered.fits%EVENTS
do an identical operation in opening the EVENTS table inside the file filtered.fits.
Filtering event files requires some command of the SAS logical language which consists of familiar arithmetic and Boolean operators and functions. These, and their syntax, are described within the on-line documentation supplied with the software. Pull up the help document using:
sashelp doc=selectlib
The rest of this guide consists of step-by-step examples of how to reprocess and analyze data for the EPIC (§5), RGS (§6), and OM (§7). At the start of each chapter, it is assumed that the user has just downloaded their data, and has not yet initialized SAS; thus, all chapters begin with the invocation of SAS and the setting of some environment parameters, as listed in 4.3. Before running any of the tasks in the following chapters, make sure that the ODF file names are all upper case!
Two tasks, cifbuild and odfingest, are necessary if the user wants to re-pipeline the data, regardless of which instrument they came from. Given their centrality to SAS reprocessing, it is worth knowing a little more about them and their output files; this is discussed further below. Examples of how to use cifbuild and odfingest are given in §5.1, §6.1, and §7.2, for the EPIC, RGS, and OM instruments, respectively.
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 but if the CCF has been updated it can be recreated by the user. In practice, it is perhaps easiest to determine whether the CCF has been updated by recreating the CIF using the SAS task cifbuild (default output name ccf.cif) and then using the SAS task cifdiff to compare the new CIF with the old. If the CAL has changed the user may want to reprocess the data using the new CIF (e.g., see § 5.1). To help determine whether it is reasonable to reprocess the data, the CCF release notes (http://xmm.esac.esa.int/external/xmm_calibration/) should be examined.
CCF files can be downloaded directly from the SOC web site (see § 4.2)
The CIF file contains a list of files to be used in the calibration/processing of your data. The task cifbuild looks at the CCF directory and builds the CIF file accordingly. If the data are processed with two different CIF files (e.g., because they were generated at different times, with different files under the CCF directory) you can end up with different results (although most often not significantly different). Note that the pipeline product *CALIND* is the CIF file used for the pipeline processing.
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 required for reprocessing the ODF data with the pipeline tasks as well as for many other tasks.