SAS Start-up

Introduction

The SAS Start-up thread provides a detailed explanation on how to get started with SAS. In particular it shows how to initialize the SAS, how to tell the SAS software which calibration files to use with a given XMM-Newton Observation, and how to get the data ready to be processed by any SAS task.

Expected Outcome

The ability to process any XMM-Newton observation with any SAS task.

SAS Tasks to be Used

Prerequisites

It is assumed that SAS has been installed properly, according to the explanations given in the current SAS installation pages. Before SAS is initialized, the HEASOFT software must be already initialized (see SAS Watchout).

Useful Links

Caveats

Last Reviewed: 4 June 2019, for SAS v18.0

Last Updated: 23 October 2014

 


Procedure
 

Before you start, you need to know the locations of the following things:

  1. Where do I have installed the SAS software in my system?
  2. Where do I have placed the Calibration files?
  3. Where do I have placed the XMM observation data I want to process?

It is important as well to choose a working place outside any of the places listed above.

Let us assume you are working in /home/user/my_work and have downloaded your favorite XMM-Newton observation data files in /home/user/sasdata/MY_OBS, where MY_OBS identifies a specific XMM-Newton observation, e.g. 0099280201.
 

Initialization of SAS
 

As soon as you know where in your system the SAS software is installed, you need to initialize it. To do that, you must define the SAS_DIR environment variable pointing to such location.

Let us assume that you have SAS installed properly in

   /some_dir/xmmsas_20100423_1801

We recommend to install the SAS in a publicly accessible directory, even if you are working on your own laptop computer. A suitable place could be for example /usr/local. We strongly recommend that you do not install the SAS under your own home directory.

Now, please define SAS_DIR as follows

   setenv SAS_DIR /some_dir/xmmsas_20100423_1801

Notice that the previous shell commands are written according to the c-shell/tcsh syntax. For the sake of clarity, we will keep using the c-shell/tcsh syntax for the remaining of the thread.

Inmediately after, initialize the SAS software by means of the following command

   source $SAS_DIR/setsas.csh

For the sh/bash shells, the syntax for these commands is as follows

   export SAS_DIR=/some_dir/xmmsas_20100423_1801
   . $SAS_DIR/setsas.sh (the dot is the equivalent to the c-shell "source" command)

Once this is done, you may already start entering SAS commands.

At this moment, one useful SAS command you may enter is sasversion, which besides testing the SAS command input readiness, it provides a sort of "About SAS" equivalent.

Depending on the OS version of the SAS installed, the sasversion command should produce an output similar to the following

   sasversion

  sasversion:- XMM-Newton SAS release and build information:

  SAS release: xmmsas_20100423_1803-10.0.0
  Compiled on: Fri Apr 23 18:33:01 GMT 2010
  Compiled by: sasbuild@xmac01.net4.lan
  Platform : Darwin-10.3.0 32

  SAS-related environment variables that are set:

  SAS_DIR = /some_dir/xmmsas_20100423_1803
  SAS_PATH = /some_dir/xmmsas_20100423_1803


As you may observe, in addition to the information on the specific SAS release (in this example it is xmmsas_20100423_1803-10.0.0, also known as SAS 10.0.0), you obtain also information on the OS where the software was built. This is useful in case you need to contact the SAS HelpDesk to report on any possible problem.

Notice that you get as well information on the current definitions of SAS_DIR and SAS_PATH. You can get similar information on other SAS environment variables as SAS_CCFPATH, SAS_ODF and SAS_CCF, as soon as you have defined them.


The Calibration Files
 

Our next step is to tell SAS where in the system you have placed the calibration data files or Current Calibration Files (CCF), as they are named.

As previously, we recommend that you put these files in a public directory in your system. Let us assume this place is /ccf. Then you must tell SAS by means of the SAS_CCFPATH environment variable where these calibration file are as follows

   setenv SAS_CCFPATH /ccf
 

The Observation Data Files
 

Last but not least, you need to tell SAS where to find the data you want to process. As we have seen at the beginning of the thread, you have your favorite observation in

   /home/user/sasdata/MY_OBS

XMM-Newton data are provided in the form of a bundle of files known as Observation Data Files (aka ODF). The components of an ODF contain information for a single XMM-Newton observation, on the different exposures and instruments that were used, their exposure modes and filters, etc.

To be able to process a specific ODF data set, you need first to identify which CCF files, among all available, will be used by it. Such task must be done by generating a Calibration Index File or CIF file, which will inform SAS on what specific CCF files have to use for each instrument and observation composing your ODF.

To generate such CIF file, please define first the SAS_ODF environment variable as follows

   setenv SAS_ODF /home/user/sasdata/MY_OBS

Then, execute the cifbuild SAS command

   cifbuild

without options. The output will be the CIF file with filename ccf.cif, in your working directory /home/user/my_work.

The ccf.cif is a FITS file which can be examined with any FITS viewer, as for example the fv from HEASOFT. It contains references to all the CCF files which are required by your ODF set, without specifying where such set is located (the default option is withccfpath=no).

Once the CIF file is done, you must set the SAS_CCF variable pointing to it, as follows

   setenv SAS_CCF ccf.cif

Within the file components of any XMM-Newton ODF set, there is a file which summarizes all the observational information involved. Such file, whose filename contains SUM.ASC, have to be updated before processing the data with SAS.

To help in such task, you must execute the SAS command odfingest, which will take such information from all the ODF components and produce a proper detailed summary file *SUM.SAS, as follows:

   odfingest

This task may take some time to finish, depending on how large is the ODF set. Once done, you must re-define the SAS_ODF variable to point to the new summary file, as follows

   setenv SAS_ODF `ls -1 *SUM.SAS`

The SAS summary file is an ASCII formatted file. We recommend you explore this file with any text editor and look for the value assigned to the PATH tag, right at the beginning of the file. If everything has been done as indicated previously, such value should be

   PATH /home/user/sasdata/MY_OBS

Now the data is ready to be processed by SAS.
 


 

Caveats

To work with SAS, please do not use the same directory where you store your ODF. As much as possible, work always in a different directory where you can create the specific CIF and summary files for your observation.