SAS Thread - startup - XMM-Newton

SAS Start-up

Procedure

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

1. Where in my system have I installed the SAS software?
2. Where in my system have I stored the Calibration files?
3. Where have I placed the XMM-Newton Observation data that I want to process?
4. Which directory am I going to use to work with SAS?

Please take good note of the answers.

Let us assume that you have installed SAS in /some_dir/xmmsas_20230412_1735, you have downloaded all the Calibration files in /ccf, you have downloaded your favorite XMM-Newton Observation data files to the subdirectory /home/user/xmm_obs, under a subdirectory named 0099280201 (the XMM-Newton Observation Data File Identifier or ODF ID) and you are going to work in /home/user/my_work.

Therefore, the answers to the above four questions are,

1. SAS software installation dir: /some_dir/xmmsas_20230412_1735
2. XMM-Newton Calibration files (CCF): /ccf
3. XMM-Newton Observation files: /home/user/xmm_obs/0099280201
4. Your working directory: /home/user/my_work

Let us begin!

InitialiSation of HEADAS
 

Some SAS tasks require Heasoft to be accessible. Thus, before any work with SAS can start, you must prepare Heasoft so that it can be used. That process is known as 'initialisation' and normally it involves the definition of some environment variables and the execution of some shell scripts.

Let HEADAS be the environment variable containing the directory where you have installed the Heasoft software. HEADAS typicaly is located at /usr/local/heasoft-M.N.P/architecture, where M.N.P is the version identification number and architecture is an alias used to avoid remembering the name of a particular installation directory, e.g. x86_64-pc-linux-gnu-libc2.27.

The following sequence of csh/tcsh commands allow us to initialise Heasoft,

   setenv HEADAS /usr/local/heasoft-M.N.P/architecture
   source $HEADAS/headas-init.csh

The equivalent commands for the sh/bash shell are,

   export HEADAS=/usr/local/heasoft-M.N.P/architecture
   . $HEADAS/headas-init.sh

You may define a shell alias named heainit, such as,

   alias heainit "source $HEADAS/headas-init.csh" (csh/tcsh)
   alias heainit="source $HEADAS/headas-init.sh" (sh/bash)

which will allow you to initialise Heasoft by simply invoking such alias,

   heainit

InitialiSation of SAS
 

To use SAS you need to initialise it which, as before, involves the definition of a shell environment variable and the execution of a shell script.

The environment variable is named SAS_DIR, and must point to the directory identified in the first question above, /some_dir/xmmsas_20230412_1735.

SAS_DIR is defined depending on the shell you are using, by typing,

   setenv SAS_DIR /some_dir/xmmsas_20230412_1735 (csh/tcsh)
   export SAS_DIR=/some_dir/xmmsas_20230412_1735 (sh/bash)

Again, depending on your shell, you have to initialise the SAS software by issuing one of the following commands,

   source $SAS_DIR/setsas.csh (csh/tcsh)
   . $SAS_DIR/setsas.sh (sh/bash)

Once this is done, you can already begin to use any SAS task.

RUNNING sasversion
 

A useful SAS command you can try first is sasversion. This tasks provides a sort of about SAS, and also, a test of SAS readiness. If such command is able to run successfully, SAS is ready to be used.

Run now sasversion.

   sasversion

You should get the following output,

  SAS release: xmmsas_20230412_1735-21.0.0
  Compiled on: Wed Apr 26 21:03:55 CET 2023
  Compiled by: sasbuild@sasbld03n.iuser.lan
  Platform   : Ubuntu18.04

  SAS-related environment variables that are set:

  SAS_DIR = /some_dir/xmmsas_20230412_1735
  SAS_PATH = /some_dir/xmmsas_20230412_1735

As you can see, besides the information on the specific SAS release (in this example xmmsas_20230412_1735-21.0.0, also known as SAS 21.0.0), you obtain as well information about the OS where the software was built, here Ubuntu18.04. This is very 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 like SAS_CCFPATH, SAS_ODF and SAS_CCF if they are already defined. This will be done in the next steps.

The Calibration Files
 

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

According to answer 2 above, the CCFs are in /ccf. You must tell SAS where to find them. As before, we must define an environment variable, now named SAS_CCFPATH,

   setenv SAS_CCFPATH /ccf (csh/tcsh)
   export SAS_CCFPATH=/ccf (sh/bash)

Should you have other CCFs in other directories, you can add these directories to the previous definition. For example, imagine you have some test CCFs in /ccf/test. Then you could define SAS_CCFPATH as,

   setenv SAS_CCFPATH /ccf/test:/ccf (csh/tcsh)
   export SAS_CCFPATH=/ccf/test:/ccf (sh/bash)

Should you have two CCFs with the same name placed in both directories, /ccf/test and /ccf, SAS will use first those in /ccf/test.

The Observation Data Files
 

XMM-Newton observation data are provided in the form of a bundle of files known as Observation Data Files (aka ODF). The file components of such ODF include information on a single XMM-Newton observation, its different exposures, their modes and filters, etc.

Now you must tell SAS where to find the ODF you want to process. As usual, you must define it through a shell environment variable,

   setenv SAS_ODF /home/user/xmm_obs/0099280201 (csh/tcsh)
   export SAS_ODF=/home/user/xmm_obs/0099280201 (sh/bash)

Note: please check that the ODF files are directly available through SAS_ODF path. When you download an observation from the XMM-Newton archive (XSA), the ODF files are located in a sub-folder that should be properly untarred before starting this process.

PRODUCING THE CALIBRATION INDEX FILE (CIF)
 

To be able to process your ODF data set, SAS needs to identify which CCF files have to be used among all the files available. This is known as generating the Calibration Index File or CIF file. SAS has a specific task to do it, named cifbuild. This task will access the ODF and look in SAS_CCFPATH for all the CCFs required by your observation. As output, cifbuild will generate a file named ccf.cif, in the directory where you have run the task.

Now change to the directory which you answered in your last question, /home/user/my_work and simply execute cifbuild without any options,

   cifbuild

As a result, a ccf.cif file will be created in your working directory.

The ccf.cif file is in FITS format and can be examined with any FITS viewer, as for example the Heasoft FTOOL named fv. You may inspect the file to see the list of all the CCFs required to process your ODF without any reference to SAS_CCFPATH (by default cifbuild uses the input parameter withccfpath=no).

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

   setenv SAS_CCF `pwd`/ccf.cif (csh/tcsh)
   export SAS_CCF=`pwd`/ccf.cif (sh/bash)

The prefix command `pwd` for ccf.cif, allows us to define SAS_CCF as an absolute path to the location of the ccf.cif file. This is recommended.

PRODUCING THE SUMMARY FILE
 

Within the file components of any XMM-Newton ODF set, there is a file which summarizes all the observational information involved. Such file (with extension ASC) must be updated before processing the data with SAS.

To do the job, SAS provides the task odfingest which you must execute to collect information from all the components in the ODF and produce what we know as SAS summary file (*SUM.SAS).

Without changing directory, simply run the task odfingest without arguments,

   odfingest

It might take some time to finish, depending on how large the ODF is. The task produces the summary file in your working directory.

To conclude, you must re-define the SAS_ODF variable to point to the new summary file,

   setenv SAS_ODF `pwd`/`ls -1 *SUM.SAS` (csh/tcsh)
   export SAS_ODF=`pwd`/`ls -1 *SUM.SAS` (sh/bash)

As in the ccf.cif, we recommend to define the location of the summary file by means of an absolute path, thus the use of prefix command `pwd`.

The SAS summary file is a text file (ASCII format), so you can edit it with any available text editor. We recommend you explore it and search 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/xmm_obs/0099280201

which must coincide with the answer to your third question.

Now you are ready to process your data with SAS!