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://xmm.esac.esa.int/sas/current/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://xmm.esac.esa.int/sas/current/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 §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_20090615_1801/setsas.csh Initializes SAS
source /full/path/to/xmmsas_20090615_1801/setsas.sh Alternate SAS initialization
SAS can now be used on the command line. To invoke the GUI, type:
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:
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.,
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: