Date of last modification: November 19, 1996

Description of programs and procedures
used during STAGE-I processing of SAX/WFC data

G.J.Wiersma (SRON Utrecht)

Revision: 1.0 (April 1996)

Distribution: 038-023


1 General
1.1 Abbreviations
1.2 FOT production
1.3 FOT structure for WFC's
1.4 FOT processing
1.5 Disk distributed FOT files
1.6 References

2 Standalone Scripts
2.1 Usage

3 General Functions / topics
3.1 Time assignment
3.1.1 Dates and times in files
3.1.2 External time referencing
3.2 Data cleaning
3.3 Attitude handling
3.3.1 Satellite and Instrument axes
3.4 Eventrate peak detection
3.5 Dead-time calculation
3.6 Detector gain

4. Concise Survey of Programs and files

5. Building the software

6. Calibrations

7. export of the software

8. HEAD considerations (TBD)


10. Simulation software

1.0 General

The data acquired during one Observing Period by the Wide Field Cameras (WFC1 and WFC2) of the SAX satellite will be received on so-called Final Observation Tapes (FOT) from the Science Data Centre (SDC). The specifications of the FOT is laid down in the "Mission Support Component FOT layout Document" (TPZ/GO.SDC-100/FOT-TN/SAX).

This document describes the first stage of the FOT data-processing for the WFCs. This includes the extraction of all science data and housekeeping data plus some general satellite information data into a set of FITS files. Using WFC instrument and satellite HK parameters filtering and cleaning of the event data is performed. This stage preceedes the next stage where the Scientific Analysis is done. (See document T.B.D.)

In the following it is assumed that there exists a top directory WFC_TOP that holds all relevant subdirectories. Some of the subdirectories may also a subdirectory of the FTOOLS structure (e.g. saxwfc). That is accomplished by the use of symbolic links. This dual approach is done to enable the flexible location of directories.

1.1 Abbreviations

  • FITS - Flexible Image Transport System (standard for file structure)
  • FOT - Final Observation Tape (delivered by the SDC)
  • GTI - Good Time Interval (used for selecting time periods)
  • HEA - High Energy Astrophysics
  • HEAD - HEA Data-handling
  • HK - Housekeeping
  • IFC - In-Flight Calibration (uses Radiation Sources)
  • NFI - Narrow Field Instrument (any of LECS, MECS, HP-GSPS or PDS)
  • NP - Nominal Pointing
  • NPI - Nominal Pointing Interval
  • OCC - Operations Control Centre (utilizes satellite links)
  • OP - Observing Period (consisting of one or more observations)
  • SAX - Astronomical X-ray Satellite
  • SDC - Science Data Centre
  • SPV - Sensor Performance Verification
  • WFC - Wide Field Camera

  • 1.2 FOT production

    The flightdata from the WFC instruments are telemetered to the ground and stored in the Science Data Centre (SDC). The telemetry consists of a stream of packets containing the data as produced by the instrument.

    The layout and contents of the packets for the WFCs are fully described in the SAX Wide Field Camera User Manual (SRON document SRU/SAX/PR-15 or ALENIA document SX-MA-AI-019 SAX USER'S MANUAL Volume 11)

    At the SDC this data is processed and results in the production of Final Observation Tapes (FOT) which are shipped to the requesters of the data either for the WFCs or for the Narrow Filed Cameras (NFI)

    Not only the data received when the satellite is locked on the target (Normal Observation) but also during the time it is slewing from the previous target (Initial Slew) and the time it is slewing to the next target (Final Slew) is stored on the FOT.

    Here we only discuss the FOT of the WFCs which contains all information of the Wide Field Camera (WFCs) recorded during one Observing Period (OP). Although during such a period a fixed part of the sky will be observed it is very likely to be split up in several Observations mostly resulting from instrument mode changes by commanding. This may occur as a reaction on earth eclipses and passes through radiation belts or otherwise. Each such Observation results in a specific set of data files. Such a set consists always of the following files:

  • a. Experiment Configuration datafile (EXCONF)

  • b. Instrument Housekeeping datafile (HKD000)

  • c. Science Housekeeping datafile (ENG000)

  • d. Science Event datafile from one of the following modes:

    - Normal Mode (DIR001)
    - High Time Resolution Mode (DIR002)
    - Background Analysis Mode (DIR003)
    - Diagnostic Reduced Mode (DIR004)
    - Diagnostic Extended Mode (DIR005)
    - Test Mode (TST000)

    In the SDC the telemetry packets of DIR001 and DIR002 and ENG000 are reformatted while the other modes are passed on as the were transmitted by the satellite.

    1.3. General structure of a FOT for WFCs

    The following FOT scheme is only for WFCs. The structure of a FOT for NFI the layout is similar but WFC and NFI will not be placed on the same FOT.

  • Structure of tape:

  • - General part
    - Science part

  • Contents of General part:

  • - Tape Directory
    - Ephemeris data file
    - Attitude data file
    - OBT-UTC conversion data file
    - IT-diagnostic data file
    - TCU-HK data file
    - (optionally Other Satellite HK data files)

  • Structure of Science part:

  • - Instrument file set 1 (WFC-1)
    - Instrument file set 2 (WFC-2)

  • Structure of Instrument file set:

  • - Instrument Directory
    - Initial Slew Observation set (1)
    - Initial Slew Observation set (n)
    - Normal Observation set (1)
    - Normal Observation set (n)
    - Final Slew Observation set (1)
    - .....
    - Final Slew Observation set (n)

  • Contents of Observation set:
    - Observation Directory
    - Experiment Configuration file
    - Instrument HK data file
    - Science HK data file
    - Science Event data file

    Directories are ASCII files that contain one line for each file or set of files that is described.

  • - The Tape Directory describes each file on the FOT
  • - The Instrument Directory describes each observation set of an instrument
  • - The Observation Directory describes each file in an observation set
  • It is possible that a FOT may comprise of more than one tape. As the distribution tapes may store 2 Megabytes splitting of FOTs is higly unlikely to occur.

    For a complete specification of the FOT refer to the "Mission Support Component FOT layout Document" (TPZ/GO.SDC-100/FOT-TN/SAX)

    1.4 FOT processing

    The first stage processing can be separated into the following phases:

  • - Copy the data from the FOT onto DISK files (script w_proc)
  • - Extract the general satellite data into FITS format files (program wfotfits)
  • - Extract WFC data to FITS format files plus time information (program wfotfits)
  • - Convert to physical values the housekeeping information and make selections for Good Time Intervals (GTIs) based on these values indicating correct instrument behaviour. (program whkproc)
  • - Calculate deadtime correction factors from the science rate meters (program whkproc)
  • - Make list of detected rate-peaks (program whkproc)
  • - Make selections for Good Time Intervals (GTIs) based on values that indicating correct instrument behaviour. (program wmakgti)
  • - Clean the event data by filtering out unwanted data based both on criteria of the eventdata itself and the GTIs as produced from housekeeping and auxiliary data. (wgtiflt)
  • - Extract the events from I In-Flight Calibration sources (program wgtiflt)
  • - Analyze the Ephemeris and calculate earth occultation date (program wattproc)
  • - Process the attitude data to provide the actual instrument pointing information and analyze possible attitude anomalies by establishing Nominal Pointings (program wattana)
  • - Correct the event positions on the detector in case pointing variations are found to be substantial. (program wshift)
  • - Create fluxfiles for the slew data (program wslew)
  • - Calculate the gain correction factors per time (program wgain)
  • - Plot and print observation statistics and relevant information on instrument behaviour (program wqplot)
  • All FITS file formats produced during the Stage-I processing are described in document T.B.D.

    1.5 Disk distributed FOT files

    In the past SDC has distributed FOT files both on tape and on DISK. In the later case the a naming scheme has been followied that is incompatible with the scheme that is used by the WFC software. For the purpose of name conversion a script is available to make symbolic linkfiles. This script is called 'w_vaxlink'. It will ask a for the FOTID string that has to be used and the number of the observing period of the normal pointing part

    Below is an example of resulting linkfiles for OP = 306 :

  • FOTID__0001.fot -> ./TAPEDIRTAPE_000000_00_0.DAT
  • FOTID__0002.fot -> ./EPHEMERIS_000000_00_0.DAT
  • FOTID__0003.fot -> ./ATTITUDE_000000_00_0.DAT
  • FOTID__0004.fot -> ./OBT_UTC_000000_00_0.DAT
  • FOTID__0005.fot -> ./W1INSTDIRTAPE_000000_00_0.DAT
  • FOTID__0006.fot -> ./W1OBSDIRTAPE_000000_01_N.DAT
  • FOTID__0007.fot -> ./W1EXCONF_00306_01_N.DAT
  • FOTID__0008.fot -> ./W1HKD000_00306_01_N.DAT
  • FOTID__0009.fot -> ./W1HKD000_00306_01_N.DAT
  • FOTID__0018.fot -> ./W1DIR001_00306_01_N.DAT

  • 1.6 References

  • "Mission Support Component FOT layout Document" (TPZ/GO.SDC-100/FOT-TN/SAX)
  • "SAX Users's manual" (Alenia SX-MA-AI-019) Chapter 11 (Wide Field Cameras)
  • "Definition of the Flexible Image Transport System (FITS)" NOST 100-1.0
  • "Users' Guide to FTOOLS" (HEASARC issue of Ftools)

    2.0 Stand-alone scripts

    To facilitate the processing of FOTs or groups of files belonging to one or more FOTs a number of scripts are available. These scripts invoke a chain of programs and take care of passing the correct filenames. They are also intended for standard batch processing of FOTs.

    For locating those scripts a separate 'etc' directory is available Scripts for running tools in a predefined way are available for UNIX based operating systems. Currently all scripts are using the C shell environment by invoking '/bin/csh'.

    All scripts recognize the following global shell variables or a subset if them. If not specified defaults are used.

    WFC_TOP topdirectory where the wfc software is located
    WFC_ETC directory where scripts and special input files are located.
    WFCCAL directory where calibration files are located
    FOT_TOP directory where the FOT files are located
    TAPE device name of the tape unit

    A detailed description of all switches and argument can be obtained by executing the relevant script with switch '-h'.

    This is the most general script to do complete or partial StageI processing. Typical switches are: '-fot' to copy files from tape to disk; '-fits' to process FOT data into FITS files; '-clean' to produce filtered files, '-shift' to do event positioning procesing, '-plot' to produce survey plots (in postscript). If reading from tape it invokes the 'dd' utility to copy the data from the FOT onto disk. This script is most suitable to be used when dispatching one of the following scripts

    w_fits Extract data from FOT or DISK by executing program 'wfotfits' Can easier be invoked via w_proc.

    Create cleaned event and housekeeping files by invoking the programs 'whkproc', 'wmakgti' and 'wgtiflt' In addition rate peaks are detectded and the attitude will be analyzed by programs 'watproc' and 'wattana' Can easier be invoked via w_proc.

    Produce positioned corrected event lists by invoking program 'wshift' Can easier be invoked via w_proc.

    Produce survey plots by invoking program 'wqplot' Can easier be invoked via w_proc.

    Produces a file of accumulated detector counts per timebin. It may be used to produce flux curves when the instrument is in slew mode.

    Process the diagnstic modes (DIR004 and DIR005) by the analysis software written for the Sensor Performance Verification.

    2.1 Usage

    The general format of the runline is like:

    ::: script_name [-switchname [argument]] ..... [-switchname [argument]]

    Arguments always have to include a specification of the FOT. For this the '-f FOTID' is used where the FOTID is the identifying string. Only in case the files are retrieved from the tape in the same call to w_proc will by default the identifying string extracted from the first line of the Tape Directory.

    Arguments not recognized by w_proc will be passed on to subsequently invoked scripts.

    Some general used switches used by all scripts are:

    -h Display a concise help on the available switches of the script. It will not show the switches of possible subsequently invoked scripts.

    -vv # Regulates the output volume. If 0 a minimal output will occur. If 1 it shows the programs that were active and some info on files produced. Larger value will pruduce more debugging info.

    -t @ Defines the directory where the input disk files are located In case of files first copied from

    -d @ defines the destination directory where all subsequent result files will be stored.


    Copy a FOT onto disk in directory 'FOTDIR' from default tape-unit

    ::: setenv FOT_TOP /disk2/fotdir
    ::: w_proc -fot

    Process a FOT from tape completely with standard options and save the output in a logfile

    ::: w_proc -fot -all -t FOTDIR > logfile

    To re-process a selected range (obs 3 thru 5) of observations and store results in different destination directory

    ::: w_proc -f FOT_ID -clean -t FOTDIR -d DESTDIR -n1 3 -n2 5

    To process all relevant files for SPV test. So all observations with modes DIR001, DIR004 and DIR005

    ::: w_spv -f FOT_ID -t FOTDIR 

    In the future these scripts will be made available under the HEAD system. This enables a window based invoking of the processing.

    2.2 General overview of programs

    - Program 'wfotfits' is used to read either directly from the FOT or from a copy of it on disk. It will extract all the relevant data to produce a number of FITS format files for further processing.

    - The data from the housekeeping files are cleaned and converted to physical values by program 'hkproc'. Besides that a dead-time correction file is produced derived from ratemeters in the science housekeeping, and in addition a ratepeak detection algorithm is performed and produces a file with bursts that are been found.

    - 'wmakgti' is a general program to create GTI files form any data in a FITS file. It is used to make GTI files from cleaned housekeeping data and ephmerides data. It uses input selectyion files that contain the conditions to mark the accepted times.

    - with program 'wmrggti' a group of GTI files can be merged into one

    - From the eventdata files (normal mode or high time res. mode) by program 'wgtiflt' the events not belonging to the GTIs are filtered. Also it filters out and stored the events coming from the Inflight Calibration sources. The latter data is used for the gain correction calculation.

    - The attitude data is updated with additional data about observation mode and auxilliary information about earth centre position by program 'watproc' The resulting file will be used for analizing the camera attitude.

    - The attitude data is analyzed by program 'wattana' in order to produce clusters with one Nominal Pointing to be used later for events repositioning.

    - By program 'wshift' the detector positions of Normal Mode eventdata is shifted to correct for misalignments from the Nominal Pointing. It produces a NPI fiel to assign the evens to a Nominal Pointing.

    - The gain of the detector is analyzed by program 'wgain' from the events emiited from the In-Flight Calibration Sources.

    - Program 'wqplot' produces a general plot per observation showing the eventrates, the gain and some instrument meters. Additionally it can produce listings of issued commands and specific status flags.

    In order to enable the tracing back of the data flow the parameters that control the processing options will be stored in all resulting files. These parameters will be stored as keywords into the Primary Header of an FITS output file.

    The following general parameters are the same for all of these programs.

    a. verbsty=integer

    The number controls the volume of the output to STDOUT The higher number the more information about the processing is given. If 0 there will be minimal output; only signalling the starting end the stopping of the program and warnings will be output plus additional information on fatel errors that may occur. b. title=string Option to insert user defined text as a parameter keyword into the fileheader c. blockio=boolean If 'no' use is made of block reads or writes to or from the file. The advantage is much faster I/O times than when using the standard ftools/fitsio routines. The drawback is that files created in that way may not be compatible with those on different com[puter systems and that adding columns in a file needs modifying all the programs that read or write such a file. d. calfile1=string Most programs make use of instrument dependent values. calfile2=string For each camera these values are stored and grouped in a separate Fits calibration file.

    2.3 Parameter passing by the ftools convention

    A program is invoked in the following form

    => program-name par-value1 ... par-value# [option1] [option2] ... [option#]
    where option can either be [option-name] or [option-name=value] where values may be either a string (with or without quotes), an integer, a real, a boolean (only yes or no are accepted)

    Parameters are position dependent, but can be placed anywhere in the runline by the [parname=par-value] construct.

    resulting filename conventions

    layout: ffffff_%%%%w$@zz$.xxxx (= one letter per field)


    ffffff = Any alpha-numeric string, but normally the FOTnumber of the tape consisting of 6 letters <br> %%%% = observation sequence number as unique within one FOT. '0000' for general FOT data <br> w# = wfc camera id (either w1 or w2) '__' for general FOT data <br> @ = observation mode (either s = slew or p = pointing)<br> No distinction for 'initial' or 'final' slew and not relevant for generakl FOT data.<br> zz$ = instrument/derived contents hs$ = housekeeping science hi$ = housekeeping instrument rn$ = rate normal rh$ = rate high ba$ = background analysis dr$ = diagnostic reduced de$ = diagnostic extended rp$ = pseudo-events ib$ = packet block info rc$ = calibration source events pk$ = peak rates dt$ = dead times gn$ = gain values for general files '%%%%w#@zz$' will be any of the following 0000__eph0 = ephemeris data 0000__att0 = attitude data 0000__utc0 = OBT tp UTC converison date 0000__obs0 = observation survey file 0000w#hit0 = IT housekeeping data additional files rn$_gti = GTIs for valid NM event data rh$_gti = GTIs for valid HTR event data hi0_gti = GTIs for valid Ins. HK event data hs0_gti = GTIs for valid Sci. HK event data

    It is not advisable to run Stage-II processes on raw data file ($ = 0) However it is possible to pass cleaned and filtered files to it ($ = 1) as well as position corrected files ($ = 2)

    A full description of all files, their naming and contents can be fiound in document (TBD) "Description of SAX/WFC files produced by Stage-I"

    Programs and I/O

    For an exhaustive description of parameters use the ftools help function. E.g. fhelp wfotfits.


    - reads FOT files from disk - optionally reads files directly from tape - produces data files in FITS format - make observations table indicating mode and start/stop times - converts all times to UTC according to OBT_UTC data - produce Good Time Intervals of DIR001 and DIR002 data These GTIs only reflect the time that data was actually received. - produces info packet blocks - optionally store pseudo-events separately In Normal Mode every eight seconds a set of these occur. (tape/disk) FOT | V -------- wfotfits -------- | |--> *__att0* [attitude data] |--> *__eph0* [ephemerides data] |--> *__utc0* [OBT-UTC table] |--> *__obs0* [observations table] |--> *w#hit0* [IT diagnostic ITHKD000] |--> *w#@hi0* [instrument housekeeping HKD000] |--> *w#@hs0* [science housekeeping ENG000] |--> *w#@rn0* [normal rate data DIR001] |--> *w#@rh0* [high rate data DIR002] |--> *w#@ba0* [background analysis data DIR003] |--> *w#@dr0* [reduced diagnostic data DIR004] |--> *w#@de0* [extended diagnostic data DIR005] |--> *w#@gti* [Good Time Interval files] |--> *w#@ib0* [block info] |--> *w#@rp0* [pseudo-event data] (optional) |--> *w#@rn0.gti [GTI file] |--> *w#@rh0.gti [GTI file] |--> *w#obs0.txt (observation survey text] - - During one observation no mode change should take place. In case this might occur the remainder of the file is skipped' whkproc: - reads housekeeping files and discards invalid records - converts temperature monitors to physical values - converts voltage monitors to physical values - Does a burstpeak hunt on science ratemeters - Produces deadtime values per second from science ratemeters *w#@hi0* --->| *w#@hs0* --->| V ------- whkproc ------- | |---> *w#@hi1* [cleaned + converted Ins-HK data] |---> *w#@hs1* [cleaned Sci-HK data] |---> *w#@dt1* [deadtime data] |---> *w#@pk1* [ratepeak data] -


    - produces Good-Time-Interval tables from selection criteria (GTI) *w#@hi1* --->| *w#@hs1* --->| ihk_sel ---->| shk_sel ---->| eph_sel ---->| V ------- wmakgti ------- | |---> *w#@hi1.gti TEMPORARY |---> *w#@hs1.gti TEMPORARY -


    - merges several GTI files into one - The reulting GTI files will be used to calculate the integrated time (ONTIME) that cleaned data was received. *__eph0_gti* --->| *w#@rn0_gti* --->| *w#@rh0_gti* --->| *w#@hi1_gti* --->| *w#@hs1_gti* --->| V ------- wmrggti ------- | |---> *w#@gti* -


    - filters events files according the GTI file - removes pseudo-events - extracts events belonging to the In-Flight Calibration sources (IFC) from Normal Mode events. *w#@rn0* ------>| *w#@rh0* ------>| *w#@rn0.gti --->| *w#@rh0.gti --->| V ------- wgtiflt ------- | |---> *w#@rn1* [filtered Normal Rate events] |---> *w#@rc1* [IFC events] |---> *w#@rh1* [filtered High Rate events] -


    - Make separate attitude file for each camera - Add Earth Centre in WFC coordinates (x,y,z) - Add observation mode information to attitude data *__att0* --->| *__eph0* --->| *__obs0* --->| V ------- watproc ------- | |---> *w1att1* [augmented attitude data] |---> *w2att1* [augmented attitude data] -


    - Analyzes one or more attitude files - Produce one list of nominal-pointing sets (NP) from actual pointings *w#att1* --->| V ------- wattana -------- | |---> *__pnt1* [pointings table] -


    - Shift the event positions according to the NP-sets - Group the events per NP *w#@rn1* --->| *__pnt1* --->| V ------- wshift ------- | |---> *w#@rn2* [event file for stage-II] -


    - Compute *w#@rc1* --->| *__obs0* --->| V ------- watproc ------- | |---> *w#@gn2* [augmented attitude data] -


    - produce per time bin number of events and actual pointing *w#srn1* --->| *w#srh1* --->| *w#att1* --->| V ------- wslew ------- | |--> *w#ssn2* [event file for stage-II] |--> *w#ssh2* [event file for stage-II] -


    - Produce plots with instrument/eventrate/attitude behaviour *w#@hi1* --->| *w#@hs1* --->| *w#@gn2* --->| *w#pnt2* --->| *__obs0* --->| V ------- wqplot ------- | |---> * [PostScript plotfile] -

    Transfer of files to STAGE-II processing

    - Produce sky images and light-curves *w#@rn2* --->| *w#@rh2* --->| *w#@dt1* --->| *w#@pk1* --->| *w#@gn1* --->| *w#att1* ---<| *__obs0* --->| V -------- Stage-II --------

    3. General topics

    This chapter addresses a number of issues and methods used Of mentioned program only the generallfunction is described. For details on the options for running these programs refer to the individual help texts


    When the instrument sends a packet to the telemetry it will always contain a time stamp. This timestamp is derived from the spacecraft clock pulse. The resolution of the spacecraft clock is 2^-16 seconds. (= 15 microsec.) In the WFC's, however, the highest used resolution is 2^-12 (1/4096) seconds. The time resolutions are: DIR001 Normal mode 2^-11 = 488 microsec. DIR002 High Time Resolution mode 2^-12 = 244 microsec. DIR003 Background Analysis mode 2^-10 = 977 microsec. DIR004 Diagnostic Reduced mode 2^-12 = 244 microsec. DIR005 Diagnostic Extended mode 2^-12 = 244 microsec. All other modes have a time resolution of 1 second only. In the FITS files produced by Stage-I times can occur as keyworods in headers and as columns in the rows of the data part. As a general rule in Stage-I all times of the eventfiles are the clock times in 2^-12 ticks. This does not reflect the actual time resolution. All times in the headers are in MJD

    3.1.1 Dates and times in files

    Times in FITS files may be represented in several ways: a. Directly as a Modified Julian Day number and fraction (MJD) It will always be represented in Double Precision (REAL*8) format. allowing a precision of 15.95 significant decimal digits. With an MJD daynumber being around 50000.0 this allows a maximam resolution of about 10^-6 seconds (1 microsecond). The time column will have the name 'TIME' in this case b. Indirectly as an integral number of time-units relative to a certain reference date. In Stage-I processing all of these timea will be scaled to units of 2^-12 (= 2.44140625E-04) seconds and be stored in Integer (Integer*4) format. The reference time is given as in Modified Julian Days as with (a.). FITS files that have such a time-columns will contain the following keywords: MJDREF / MJD of S/C clock = zero T_SCALE / scale factor of times (seconds) The time column will be nemaed WFC_TIME / Space Craft clock time of the WFC So if the given relative time is TIME_WFC then the actual times in MJDs will be: MJDREF + (TIME_WFC * T_SCALE / 86400) c. A combination of a. and b. If only MJDREF is specified in the priamary header time in MJD will be MJDREF + TIME IF T_SCALE is also specified time on MJD will be: MJDREF + TIME * T_SCALE / 86400. d. Instrument On-Board time ticks. One tick is defined as 2^-16 second. These ticks will be stored only for the start or end of observations. Relevant keywords are SCSEQBEG= spacecraft clock begin (ticks) SCSEQEND= spacecraft clock end (ticks) e. As time periods they will be stored in seconds Used in headers with keywords: TELAPSE (elapse time from start to end in seconds) ONTIME (Total uncorrected integrated time ion seconds) f. In Calendar days and times are stored in character string keywords and have the form 'dd/mm/yy' (all numerics) and 'hh:mm:ss' or 'hh:mm:ss.sss' Used keywords are DATE-OBS, TIME-OBS, DATE-END and TIME-END.

    3.1.2 External time referencing

    Neither the science data nor the housekeeping data coming from the instrument contains actual date and time stamps. Only the On-Board Time in units of 2^-16 ticks are available and stored in the telemetry packets. In order to enable the matching of these tick-times to actual dates a special reference file will be present on each FOT containing an OBT to UTC conversion table. This file is used to calculate a reference time (MJDREF) for each new observation. To obtain the reference date the instrument time is matched with the latest OBT that is preceeding the instrument time (ticks) so that the reference can be calculated as follows: if SCSEQBEG contains the ticks of the first event and OBT is the closest time in the OBT_UTC files, then MJDREF = UTC - OBT / ( 2^-16 * 86400) where UTC is the time corresponding to the OBT value The following problems are provided for: a. In case the time is falling outside the provided conversion OBTs a warning is issued. Then depending which is closest to the instrumemnt time either the first or the last OBT is taken to calculate the reference data (MJDREF). b. The OBT counter may scroll though zero during the observation. This will happen every 2^16 (65535) seconds or 18.2 hours. This can be easily solved as during one Observing Period the starttimes within one observation must not occur before the endtimes of previous observations. Only the first one will take the earliest OBT match.


    Cleaning of data files is used here a very broad meaning. During this cleaning stage the following functions are performed: - conversion of instrument housekeeping values to physical units for all temeratures, voltages. - Testing and rejecting all data that have obvious defects like a-sequential times, monitoring meters out of limits or unstable High Voltage after instrument state switching. - extracting calibration (IFC events) data from science data. - filtering instrument monitoring data (Pseudo-events) from science data. The Housekeeping files are cleaned by program 'whkproc' which does the value conversions and the bad time rejections. The resulting data files are used for making Good Time Interval files by program 'wmakgti', which uses a selection criteria file containing the conditions for accepting good data. Presently on three different data streams GTI files are selected. a. Selection criteria on Instrument Housekeeping which are laid down in an expression file (wfc_sel_ins) containing one single line b. Selection criteria on Science Housekeeping which are laid down in an expression file (wfc_sel_sci) containing one single line c. Selection criteria on Ephemeris which are laid down in an expression file (wfc_sel_eph) containing one single line. Program 'wmakgti' can read the selection criteria either as a parameter argument or as a line contained ia a textfile. Merging of all or a set of GTI files is done by program 'wmrggti'. Here is flow of the cleaning with standard processing: FOT | V ========== wfotfits ========== | | |-->FOTID1_%%%%w#@hi0 --------------------------------------- | | |-->FOTID1_%%%%w#@hs0 --------------- | | | | |-->FOTID1_0000__eph0 V V | | ========= ========= | | whkproc whkproc | | ========= ========= | | | | | | V V | | FOTID1_%%%%w#hi1 FOTID1_%%%%w#hs1 | | | | | V V V | ========= ========= ========= | wmakgti wmakgti wmakgti | ========= ========= ========= | | | | | V V V | FOTID1_0000__eph0gti FOTID1_%%%%w#hi1gti FOTID1_%%%%w#hs1gti | | | | | |--------------------- | ------------------- | | | | | | | V V V | V ========= | V wmrggti | V ========= | | | V | FOTID1_%%%%w#gti | | |-->FOTID1_%%%%w#@r@0 ----------- | | | | | V V V ========= V wgtiflt V ========= | \ | ---->FOTID1_%%%%w#@ic1 ----- V | FOTID1_%%%%w#@r@1 V | ============= V gain ============ calculation shift ============= processing ============ (where FOTID_%%%%w#@r$0 = Any camera (w1 or w2) and either normal or slew observing mode (pr or sr) and either Normal mode (rn) or Hight Time Resolution mode (rh).


    Reconstruction of the sky from the detector image can only be done if during the recording of the photons the pointing of the instrument is within narrow bounds. The satellite is guaranteed to maintain its pointing stability within an error of 1 arcminute and the absolute pointing error is guaranteed to be exact within 3 arcminutes. For the WFC having a field of view of about 40 degrees the error in absolute pointing is not very critical. In order to prepare for larger instability than expected or allowed the following three programs have been implemented: a. Program 'watproc' copies the raw attitude file for each instrument separately and adds information about Observing Mode (Normal/Slew) plus the position of the Earth w.r.t. the camera. From the Ephemeris data that gives the location of the satellite is calculated the centre of the Earth in the camara coordinates km in X, Y and Z). b. Program 'wattana' analyzes the attitude data and establishes a number of clusters so that actual pointings belonging to one cluster are within the permitted maximum limits from the center or nominal pointing of that group. Such a nominal pointing is characterized by Right Ascension, Declination and North Angle. For each of these a maximum range can be specified, both for Normal Pointing or Slewing Operational Mode. The result will be a file that contaions the list of all calculated Nominal Pointings. In the case of ideal stability it shall of course have only one. It is envisaged to run this analysis standardly over the complete Observing Period (one FOT). c. Program 'wshift' will shift the position of each individual photon event over the detector to the position that is would have had if the detector had positioned to a reference pointing. The reference pointing will be the closest from a set of Nominal Pointings as calculated by 'wattana'. As the shift is done of a part of the Observation Period only a subset of the Nominal Pointings will be used. A file containing the Time Intervals per Nominal Pointing is produced in order to enable the separate processing the of photon events of one Nominal Pointing at a time as is required by the correlation programs of Stage-II proceswsing which can operate only on one accumulated detector image. The layout of such a Nominal Pointing Interval (NPI) file is identical to those of the Good Time Interval (GTI) files, but with an extra column containing the number of the Nominal Pointing. If only one NP is calculated and the range of the photon detector positions is very small it is possible to skip the shifting of the events altogether and pass the event datafile directly to Stage-II processing. Here is flow of the standard attitude processing of one single FOT: FOT | V ========== wfotfits ========== | | |-->FOTID1_0000__att0 ------ | | |-->FOTID1_0000__obs0 ---- | | | | |-->FOTID1_0000__eph0 -- | | | | | | | V V V | ========= | watproc | ========= | | | | | |-->FOTID1_0000w1att1 ----------->>> | | | |-->FOTID1_0000w2att1 ----+------>>> | | | | | - | V | | ========= | | wattana | | ========= | { | | | V | | FOTID1_0000w2pnt1 |-->FOTID1_####w2prn0 -- | | | | | | | | | ---- | V ----- | | ============ | | V filter | | V processing | | V ============ | | | V V V ======== FOTID1_%%%%w2prn1 -------> wshift | ======== | | | | | --------------- | | | | V V | FOTID1_%%%%w2prn2 FOTID1_%%%%w2npi2 | | | | | | | V | | ============ | -------------> Stage-II <----------- processing ============ Here is flow of the attitude processing of several FOTs (having same target): FOT | V ========== wfotfits ========== | | | | |-->FOTID1_0000__att0 ------ | | | | | | |-->FOTID1_0000__obs0 ---- | | | | | | | V |-->FOTID1_0000__eph0 -- | | | FOTID3_0000w#att1 | | | | V | | V V V FOTID2_0000w#att1 | | ========= | | | watproc | | | ========= | | | | -------------- | | | | | | |-->FOTID1_0000w1att1 --->>> | | | | | | | |-->FOTID1_0000w2att1 -------- | | | | | | | | | - | V V V | | ========= | | wattana | | ========= | | | | | V | | MERGED_0000__pnt1 |-->FOTID1_####w2prn0 -- | | | | | | | | | ----------- | V ----- | | ============ | | V filter | | V processing | | V ============ | | | V V V ======== FOTID1_%%%%w2prn1 ------> wshift | ======== | | | | | --------------- | | | | V V | FOTID1_%%%%w2prn2 FOTID1_%%%%w2npi2 | | | | | | | V | | ============ | -----------> Stage-II <---------- processing ============


    The orientation of the satellite determines the orientation of each individual camera with respect to the sky. The sky coordinate of the sighting axis (Z-axis) of an instrument is called its pointing. Use is made of the following right-handed coordinate system: +Y +X | | | | |_____+X === |_____+Y / / / / +Z <= towards eye of reader => -Z In this system the North-Angle is defined as the the angle to turn anti-clockwise the +X onto the plane through the North Pole and the Z while having the +Z axis (= sky pointing) in your back. Note, that in this definition the NA will be undefined if +Z points exactly at any of the two poles. For the instruments the following definitions are in force: for each camera: Z = the heart axis through the instrument with the detector at -Z and +Z at the mask side pointing to the observed sky Y = the side of the detector perpendicular to the groundplate with the groundplate at -Y and the other side of the instrument at +Y X = the side of the detector parallel at and closest to the instrument groundplate with +X going left when looking from outside the instrument to the backside of the detector WFC-1: X = - SAT Z Y = - SAT X Z = - SAT Y = instrument pointing WFC-2: X = SAT Z Y = - SAT X Z = + SAT Y = instrument pointing (checked 19/11/1996) As each axis is given by its Right Ascension and its Declination the following pointing relations exist: WFC1: SAX: ----- ----- ra_x = RA_Z dec_x = DEC_Z ra_y = 180 + RA_X dec_y = - DEC_X ra_z = 180 + RA_Y = RA_PNT dec_z = - RAS_Y = DEC_PNT and WFC2: SAX: ----- ----- ra_x = 180 + RA_Z dec_x = - DEC_Z ra_y = 180 + RA_X dec_y = - DEC_X ra_z = RA_Y = RA_PNT dec_z = DEC_Y = DEC_PNT It is envisaged that the instrument alingment on the satellite is not exact. So the difference between the nominal and the actual pointing of each instrument is defined by the following three parameters: THETA the angle between the nominal Y-axis and the actual Z-axis minus 90. (nomally 0 degrees) PHI the angle between the plane going through nominal Y-axis and the nominal Z-axis and the one going through the nominal Y-axis and the actual Z-axis (nomally 0 degrees) turning clockwise with +Y in the back ROLL the angle between the plane going through nominal Z-axis and the nominal Y-axis and the one going through the nominal Z-axis and the actual Y-axis (nomally 0 degrees) These values will be stored and updated in the detector calibration file (wfc#.det) as part of the data extension named 'align'.


    R.A., Dec. and Roll are taken from file 'w2instdir_000000_00_0.dat' WFC2 pointing axis is the same as the Satellite +Y axis. RA_WFC1 = 180 + R.A. , DEC_WFC1 = -1 * Dec. , NA_WFC1 = 270 - Roll RA_WFC2 = R.A. , DEC_WFC2 = Dec. , NA_WFC2 = Roll - 90 always valid: NA_WFC1 + NA_WFC2 = 180 modulo 360


    Valid for an imaging instrument with its own X and Y axes The angle to turn the +X axis of the SKY-IMAGE anti-clockwise towards the North Pole, with the observer looking to the sky and having the detector behind his back. if Zsat = -Xwfc1 = North then NAwfc1 = 180 and roll = 90 if Xsat = -Ywfc1 = North then NAwfc1 = 270 and roll = 0 if Ysat = -Zwfc1 = North then NAwfc1 = undefined and roll = undefined if Zsat = Xwfc2 = North then NAwfc2 = 0 and roll = 90 if Xsat = -Ywfc2 = North then NAwfc2 = 270 and roll = 0 if Ysat = Zwfc2 = North then NAwfc2 = undefined and roll = undefined From the above it can be seen that NAwfc1 = 270 - ROLL(sat) NAwfc2 = ROLL(sat) - 90 NOTE: In a previous definition the X-axis of the instrument was taken to be the X-axis of the DETECTOR. For orientation of the sky-image, however, the X-axis of the IMAGE is pointing in the opposite direction. So, Xwfc(sky) = -Xwfc(det)


    In order to enable the correction of photon fluxes a file is produced containing the deadtimes per specified period (minimum 1 second). The calculation is performed by program 'whkproc' from the Science Housekeeping data. The MAIN trigger ratemeter counts the number of events which triggers the low level discriminator of the Main A nnode section of detector. The LOGIC trigger ratemeter counts the number of events which pass the first validation check in the Digital Frontend and triggers the Event Processor to transfer the event data into the Event Processor. During the transfer process the ratemeter is stopped and also if for any reason buffers temporarily cannot be sent to the telemetry. This allows the calculation of the dead-time of the instrumant. Both meters are reset to zero every second. Therefore the deadtime = ( RATE_MAIN - RATE_LOGIC ) / RATE_MAIN and the actual_flux = measured_flux / ( 1 - deadtime ) The deadtime is stored in a FITS file together with the time in Modified Julian Day plus the accumulation or binning time in seconds


    Finding peaks in the detector countrate is performed by program 'whkproc'. Per detected peak a row is stored in a FITS file. The information stored is risetime and falltime of the peak, the countrate at the peak maximum, and the total counts of the peak above the running average. The algorithm for finding a peak is based on the count rate of the input event processor. This countrate is available every second in the Science Housekeeping data. The FITS keyword for the column containing these values is 'RATE_EVENT'. At any point the counts of a fixed number of seconds (currently 50) are buffered and used to find a peak. A peak is accepted if the distance to the falltime of a previous peak is at least a predetermined number of seconds (presently 3) and if for at most a fixed number of succesive counts (presently 24) counts are above the buffer average by at least a fixed number (presently 100)


    For establishing the detector gain or spectral response use is made of the events that are produced by the In-Flight Calibration radiation sources as detected during the Normal Mode operation of the WFCs. Extracting the IFC events is done by program 'wgtiflt'. There are nine Fe-55 radiation sources of which eight are emitting about 0.2 photons per second and 1 producing 10 photons per second plus one Cd-109 soiurce emitting about 1 photon per second. The detector positions and boxes from where the photon events are taken are stored and updated in the detector calibration file (wfc#.det) as part of the data extension named 'califc'. Calculating the detector gain is done by program 'wgain'. Per specified number of seconds the spectrum of the energy bands are accumulated and analyzed for finding peaks in two different regions covering respectively the Fe-55 (channels 7 thru 19) and Cd-109 (channels 24-31). The channel peaks are converted to KeV to compare with the nominal energy peaks at 5.98 and 22.6 KeV respectively. The channel to energy conversion values are stored and updated in the detector calibration file (wfc#.det) as part of the data extension named 'phakev'.

    Questions and comments can be addressed to

    This page is maintained by Hans Muller (SAX/SDC - SRON)