Guidebook for WFC Scientific Data Analysis

R. Jager, SRON-Utrecht

Version 1.1, 20-01-1997

1. Introduction

This document is a first attempt to provide a guideline for the data analysis of the Wide Field Cameras onboard SAX. Details about the WFC software can be found in the SAX-WFC Software User Manual (SRON/SAX/DA-002).
Detailed installation instructions as well as a description of the supported hardware platforms and necessary additional software tools are provided in the Installation Manual (SRON/SAX/DA-001).
Information about the latest software release can be found in the Release Notes (SRON/SAX/DA-004). A description of the instrument is written in a paper submitted to Astronomy and Astrophysics (A&A 1997). More information about instrument and software may be found on the SAX-SDC and SRON webpages.

2. Instrument modes

The WFC's can be used in two scientific modes: the imaging Normal Mode and the non-imaging High Time Resolution Mode.
At present the software and the document concentrates on the NM which is the default instrument mode and will be used most of the time.
It is important to realize that the Wide Field Cameras are coded mask instruments . This means that sky images can only be produced on ground. This is performed by means of the cross correlation technique making use of cleaning by Iterative Removal of Sources.

3. Data reduction

The data from the SAX Wide Field Cameras that you are going to analyse arrive on a Final Observation Tape (FOT) with a format that you have requested.
On this FOT you will find all data from your observation of both Wide Field Cameras, although only one of them probably has performed the observation, together with satellite housekeeping data like attitude data, satellite ephemeride data, time conversion data etc.
The WFC analysis software will enable you to read the FOT, filter the events, reconstruct the celestial image and produce spectra and lightcurves for each source in the Field of View. Also a simple spectral fitting program is included.

The data analysis takes place in different stages: stage I, stage II and stage III. In short, stage I produces cleaned eventlists and housekeeping files, stage II produces images, spectra and lightcurves in user defined energy and time windows as well as source lists. In stage III the user can perform his or her preferred spectral or temporal analysis.
To ease the use of the software and to enable a semi-automatic data analysis pipeline several C-shell scripts can be employed. These scripts can be found in $WFC_TOP/etc.

The overall data analysis script is called w_run. It's only parameters are: the Observation Period Identifier (OP-ID), the location of the directory where the FOT will be unpacked, the directory where the eventfiles are put and the Wide Field Camera whose data is going to be analysed.  The resulting images, sourcelists, spectra and lightcurves will be put in the directory from which the scripts are run, the result directory.

Directories /fitsdir and /fotdir must have sufficient space, analysis of an observation may need up to one Gigabyte of (temporary) diskspace. By typing w_run without parameters, the use of the parameters will be displayed.  
w_run calls the scripts w_stageI, w_stageII and w_stageIII, these scripts can of course also be executed separately. The stage II and III scripts typically contain user defineable parameters, for this reason it is advisable to copy them in the users working directory and edit them to your own liking.

This script reads the FOT files and converts them to filtered eventfiles together with a host of additional files. It is meant to be run highly non-interactive, in general it will not be necessary to tweak the parameters your self but it can be done.
A description of the result files can be found in the usermanual. The naming convention is also described there. Among the most important files are the overall Good Time Interval file (*0000*gti) which is constructed on the basis of the applied filter criteria, the Life Time Fraction file (*pdt1.fits) which contains the instrument lifetime fraction for each second and the gain file (*gn1.fits) that is derived from the inflight calibration sources response.
The GTI file is automatically used by the w_stageII script that has to be run after w_stageI. The LTF and gain files are not yet automatically applied.

This script needs as a minimum input the filtered eventlists from w_stageI plus the GTI and LTF files. The user can choose the energy bands and the time windows for which the analysis has to be done. There are several programs that are sequentially executed, the default script contains parameters that allow a standard analysis. Please refer to the Software User Manual for a description of the parameters that allow full control. The following programs are run in sequence:

The analysis of the scientific products can be in principle performed with FTOOLS and XANADU package. At this moment the programs wresp and wfit are included. Wresp produces a detector response matrix while wfit performs simple spectral fitting. An interface to the XSPEC program will be available in the very near future.
A FITS viewing program named FITSVIEW for IDL can be made available, this enables easy viewing and interacting with all FITS files that are produced by the WFC software. Selections in the spectral and temporal domain can be made and used as input parameters for the w_stageII programs.