4. Setting Up and Running SAS

The Science Analysis Software (SAS, https://www.cosmos.esa.int/web/xmm-newton/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. Until 2012, the Pipeline Processing System (PPS), which is comprised of a superset of the SAS suite and Perl scripts, was run at Leicester University (http://xmmssc-www.star.le.ac.uk/SAS/) to create the basic data products provided to the Guest Observer from the satellite ancillary and science data. At present, the SOC and the NASA/GSFC GOF are responsible for SAS maintanance and updates.

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 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, as can SRON's SPEX software https://www.sron.nl/astrophysics-spexl.

4.1 Installation

The primary guide for the installation of SAS can be found through the SOC at
https://www.cosmos.esa.int/web/xmm-newton/sas-installation. SAS is only distributed as binaries, not as source code, for several flavors of Linux and macOS. It also has a Docker installation, users may find the easiest option to deal with. 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 https://www.cosmos.esa.int/web/xmm-newton/sas-requirements.

4.2 Calibration Data

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
(https://www.cosmos.esa.int/web/xmm-newton/current-calibration-files). In addition, canned spectral response files can be found under
https://www.cosmos.esa.int/web/xmm-newton/calibration.

4.3 SAS Environmental Parameters and Invocation

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

or

source /full/path/to/xmmsas_20090615_1801/setsas.sh       Alternate SAS initialization

At this point, SAS can be used on the command line or GUI; an introduction to the GUI can be found in §5.3. 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.

4.3.1 SAS Helpful Hints

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.

4.4 SAS Syntax and Logic

4.4.1 Command Line Syntax

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 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.

4.4.2 Table Syntax

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.

4.4.3 Filtering Logic

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

Briefly, here are some commonly used terms:

Table 4.1: Commonly Used Filtering Logic

Symbol	Meaning
&&	and
!	not
$\vert\vert$	or
==	equal
!=	not equal
&&!	and not
$<$	less than
$<=$	less than or equal
$>$	greater than
$>=$	greater than or equal
in	in