The Science Analysis Software (SAS, http://xmm.vilspa.esa.es/external/xmm_sw_cal/sas_frame.shtml), 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.vilspa.esa.es/external/xmm_sw_cal/sas_frame.shtml
(note that the final ``/'' is
often required for SOC pages). 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.vilspa.esa.es/sas/7.1.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://xmm.vilspa.esa.es/external/xmm_sw_cal/calib/index.shtml). The calibration page also has links to the CCF release notes. In addition, background event files and canned spectral response files can be found under http://xmm.vilspa.esa.es/external/xmm_sw_cal/calib/epic_files.shtml.
There are a few parameters which need to be set for the proper operation of SAS. Many are taken care of by the initialization script, but it doesn't hurt to repeat them. The commands should, of course, be modified to be appropriate for your specific setup.
setenv SAS_DIR /path/to/xmmsas_yyyymmdd_hhmmsource
Sets the SAS directory path
source $SAS_DIR/sas-setup.csh Initializes SAS
$SAS_DIR/sas-setup.sh Alternate SAS initialization
setenv SAS_ODF /path/to/odf_data Sets the directory path to the ODF data, it is
probably a good idea to have this be the
full path.
setenv SAS_CCFPATH /path/to/CCF Sets the directory path to the CCF data
setenv SAS_CCF $SAS_ODF/ccf.cif Sets the Calibration Index File (CIF) path and
file name (note that the CIF file is normally
part of an event list, so SAS_CCF can also
be pointed at the list, this should probably
be the full path as well
setenv SAS_VERBOSITY 3 Sets the verbosity, 1 => little, 10 => lot
setenv SAS_SUPPRESS_WARNING 3 Sets the warning level, 1 => little, 10 => lot
sas & Invokes the SAS GUI, SAS tasks can also be run
on the command line
NOTE: To verify the SAS-specific settings, use the task sasversion (alternatively, the command env | grep SAS can be used).
SAS need not be run in the directory where the data are stored (for example, it will be possible to run off of the data CDs when the file names are changed to be upper case). To do so only requires that the setenv SAS_CCF $SAS_ODF/ccf.cif be reset to the directory string for the working directory, see § 4.5.1. This can also be done using the SAS Preferences GUI (found under the ``File'' menu). From the command line invocation of tasks the input and output directories, when relevant, can be set as parameters (e.g., see command line input for odfingest, § 4.5.2).
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 most tasks from the command line. In many cases parameters where the default values are acceptable are not included in the command list, which can be done in practice as well. If the GUI interface is being used then simply set the parameters there.
The MPE Analysis Guide, http://wave.xray.mpe.mpg.de/xmm/data_analysis 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 browseer 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.
NOTE: 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
WARNING: Before running the following tasks make sure that the ODF file names are all upper case.
NOTE: Run these tasks.
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 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.vilspa.esa.es/external/xmm_sw_cal/calib/index.shtml) should be examined.
CCF files can be downloaded directly from the SOC web site (see § 4.2)
WARNING: 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.
To run cifbuild and cifdiff on the command line use:
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.
To run odfingest on the command line use: