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 sasversion cifbuild odfingest Prerequisites It is assumed that SAS has been installed properly, according to the explanations given in the current SAS installation pages. Useful Links SAS web pages SAS download page SAS external software requirements Latest SAS on-line documentation SAS Threads Caveats

---

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.

Last Updated: 16 April 2010

---

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.

---