NAME

evelin - the main SAX/LECS EVEnt LINearization module

SYNOPSIS

evelin [infiles=] <file_names> [parameter=value ...]

DESCRIPTION

evelin is the main linearization module of the SAX/LECS data analysis system. It transforms raw event list FITS files (type: rev) into a linearized form (type: lev) in which several basic corrections have been applied to the data. These are:
1. All events outside the detector's FOV have been removed.
2. The raw PHA values have been corrected for temporal changes in the energy gain (based on continuous monitoring of Fe calibration sources).
3. The PHA values are corrected for spatial variations in the energy gain across the detector's focal plane (based on spatial gain maps from calibration database).
4. A basic event filtering has been performed to remove "non-scientific" events from the data.
5. A BL-dependent correction has been applied to the already gain-corrected PHA values.
6. The focal-plane coordinates of detected photons have been "linearized" to account for intrinsic distortions that are inherent to the detector.
7. Instrumental dead-time effects have been taken into account.
8. The corrected focal-plane coordinates have been mapped onto sky coordinates (standard tangent-plane projection)

The default behavior is to perform all tasks in one run, although, each individual correction can be suppressed by setting a corresponding boolean command line switch. The program is able to deal with two different types of event files that are symbolized by the name extensions _rev and _lev. _rev is the default extension for a raw event file which is the primary output from the ingestor modules foting and teleing respectively. _lev stands for "linearized events" and this represents the primary output of evelin. The _lev type files differ from the raw version by five additional Bintable columns that have been added to the event extension. These are (see [1] for further details):

PI	- the Pulse Invariant of the event in units of detector channels
PIC	- the Pulse Invariant of the event corrected for penetration effects
DETX	- the linearized X-coordinate of the event
DETY	- the linearized Y-coordinate of the event
X	- sky-projected X coordinate of photon
Y	- sky-projected Y coordinate of photon

Thus, evelin accepts its own output again as input which is needed if one wants to do the aforementioned multi-step linearization process successively in more than one run. If the user requests a linearization step that has already been performed in a previous run, a warning message is issued and the request is ignored. The various linearization stages of evelin are described in more detail in the following sections.

EVENTS REMOVAL

This first processing step simply removes all events outside the detector's FOV. Note that this pertains also to the events from the calibration sources which ly in the outermost corners of the focal plane. The detector's FOV is defined as a circular region with a raw pixel radius of 100 (alterable via command line parameter fovradius) centered around the point where the optical axis intersects the focal plane (approx. raw coordinates: 132/125).

TEMPORAL GAIN CORRECTION

This correction accounts for temporal changes in the detector's energy gain as a consequence of changes in operating conditions, e.g. temperature, pressure etc. The actual time-dependent energy gain is calculated using the pipeline module calcgain and contained as column data in a HK FITS file of type _hkg. Thus, evelin first attempts to open a _hkg file corresponding to the current event list file and read the gain information from a Bintable column named GAIN_AVG (can be changed via command line parameter tgaincol). The time granularity of those data is always greater than 25s and, therefore, they have to be interpolated which can either be done by means of a linear regression function or a cubic spline (controlled via command line parameter tgainint). Prior to actually performing the temporal gain correction on the PHA values, the interpolation function together with the gain data can be plotted (see parameter tgainplot). After the plot the user is prompted for an acceptance confirmation. If this is answered positively, the actual correction is done, i.e., each event #i will be assigned a PI channel number according to the relation:

       PI_i = PHA_i / gain_t(t_i)

where PI is a new Bintable column in the event extension of the newly created output file. Since the PHA and PI values are integer quantities performing the above prescription as is leads to an artificial "integer quantization effect". In order to avoid this, a random value in the range [-0.5, 0.5] is added to each PHA value before it is divided by the actual gain factor. Further information about gain related issues can be found in [3].

SPATIAL GAIN CORRECTION

In addition to the time dependence, the energy gain is spatially not homogeneous, i.e., varies across the detector's focal plane. Hence, the energy channel of each photon has to be corrected according to its detection coordinates. This is done with the aid of a pre-processed spatial gain map file which, either, stems from the SAX/LECS calibration database, or can be explicitly specified (see command line parameter sgainfile). The spatial gain map file contains basically a two-dimensional array which, when indexed with raw X and Y coordinates, yields the spatial energy gain at that location. This is used to correct the PI values of each photon according to the simple prescription:

      PI_i = PI_i_old / (const * gain_s(x_i, y_i))

where PI_i_old is the already temporally corrected energy channel of photon #i and "const" is an alterable correction factor with default value 1 (see command line parameter sgainfactor). Similar to the temporal gain correction, a random value in the range [-0.5, 0.5] is added to the integer PI values before they get divided by the spatial gain factors. Further information about gain related issues can be found in [3].

EVENT SELECTION

Not all events that are detected inside the instrument's FOV are of actual interest for the further scientific analysis of the data. Examples are particle events originating from cosmic rays that have been absorbed in the gas cell or spurious, so-called double events that are detected on a line joining the two calibration sources. Those events can be identified through peculiarities in their Veto and BL signals, and be removed via a discrimination against appropriately chosen interval thresholds of those quantities. This is done by performing a standard one-dimensional Veto cut in combination with a two-dimensional selection in PI-BL space. The event-selection stage is controlled via several command line parameters, among which the most important one is blvselfract. It determines the fraction of photons that will be retained by the combined selection at all energies. More detailed information on the event selection can be found in [3].

BURST-LENGTH CORRECTION

Due to the driftless design of the LECS detector, X-rays that penetrate deep into the gas cell before the get photoelectrically absorbed give rise to events with lower PI and BL values than events of the same energy which are detected just beneath the cell entrance window. Analyses of ground calibration data have shown that the BL information can be used to correct for that effect, i.e., to effectively enhance the detector's spectral resolution. A corresponding algorithm has been developed which is used by evelin to derive a gain and BL-corrected Pulse Invariant Channel number (PIC channel) for each event. Information about the BL-correction algorithm together with related ground calibration results can be found in [4].

Please note: Although PIC spectra obtained from ground calibration measurements show the anticipated improvements with regard to the spectral resolution, early analyses of flight data do not seem to confirm this finding. It is clear that further investigations by the LECS team are required to clarify the situation. At present (01/97) observers are therfore discouraged from using the PIC data for spectral analyses.

COORDINATE LINEARIZATION

Due to intrinsic distortions inherent to the detection mechanism, the raw spatial event coordinates as yielded by the instrument's electronic unit do not directly reflect the physical location where the photon has hit the focal plane. To gain this information, a non-linear correction of the form

     C_i = a0_i + a1_i*x + a2_i*y + a3_i*x*y + a4_i*x^2 +
           a5_i*y^2 + a6_i*x^2*y + a7_i*x*y^2 + a8_i*x^3 +
           a9_i*y^3

has to be applied. Here, i is either x or y, C_{x/y} are the desired physical coordinates of the photon in the focal plane (measured from the center of the FOV), x/y are the raw detection coordinates referred to the center of the FOV, and a0_i to a9_i are constant coefficients. For more details on the transformation and related issues, see [3]. Per default, evelin attempts to read the two sets of a-coefficients from a corresponding FITS data file in the SAX/LECS calibration database. If this is not available the file of an alternative coordinate linearization file can be specified (see command line parameter lincrdfile). The above transformation gives the physical X and Y event coordinates measured in mm from the center of the FOV which will be used to derive "linearized" pixel coordinates. These will finally be stored as DETX and DETY table entries in the event extension of _lev files. Linearized coordinates run in each dimension from 0.0 to a maximal pixel value Max which depends on the actually chosen plate scale (see command line parameter lincrdplatescale). The point (0.0/0.0) is defined to refer to the corner in the focal plane with physical coordinates (0mm/0mm) and the point (Max/Max) represents the diagonally opposite corner at (32.79mm/32.79mm). Using the "intrinsic" plate scale of 7.8 pixels/mm (256x256 raw pixels on an active window area of 32.8x32.8 mm) the dimension of the linearized coordinate space will be [0.0-255.0] x [0.0-255.0]. Another example: A plate scale of 30 pixels/mm leads to an pixel range in X and Y of [0.0-30*32.79] = [0.0-984.0]. The center of the FOV will become the central pixel in the linearized image, i.e., in the last example the center of the FOV will be assigned the coordinates (492.0/492.0).

DEAD-TIME CALCULATION

In this processing step the instrumental dead-time correction factor Fd, i.e., 1 minus the fraction of the total observing time during which the instrument was insensitive to incoming X-rays, is calculated. The actual computation is carried out using the instrument's deadtime ratemeter counter which is tabulated in the HK file as a standard parameter with a 1s time granularity. The corresponding Bintable column name is DEADTIME_RATEMETER, see [1]. The value of Fd is then simply

     Fd = 1 - M(DEADTIME_RATEMETER)

where M(DEADTIME_RATEMETER) is the value of the dead-time ratemeter averaged over the time period covered by the observation. Fd will be stored in the event extension of the output file as value of a new header keyword DEADC. In addition, the standard deviation of Fd and the dead-time corrected observation time will be calculated (keyword names STDDEADC and LIVETIME/ EXPOSURE). The latter quantity is needed to allow the true X-ray source strength and variance to be determined.

DETECTOR TO SKY COORDINATE MAPPING

In this stage the program calculates for each event the pixel position within a two-dimensional sky image and saves this information in the X and Y table columns of the event extension. In addition, standard World-Coordinate-System (WCS) header keywords (see [1] and [5] for details) are added to the event extension header which enables corresponding FITS readers such as Ximage or the standard FTOOLS task xy2sky to compute for each event the actual R.A. and Dec. value. The generated image is a standard tangent plane projection of the sky with a X and Y pixel range corresponding to the dimensions of the linearized detector image. Other than in this, however, X and Y pixel values start at 1. The central pixel of the sky image shall be the projection's fixed-point, i.e., the point where the tangent plane touches the celestial sphere. Via a command line parameter skypointing) it can be chosen among the following three alternatives:

1. the current nominal pointing direction of the satellite
2. the mean pointing of the satellite during the observation
3. any fixed point in the sky given as a user-supplied R.A./Dec. coordinate pair
In the first case, the celestial coordinates of the reference point are taken as the values of the RA_OBJ and DEC_OBJ keywords from the primary FITS header. In the second case, they are calculated as the mean R.A. and Dec. values of the satellite's pointing axis from the attitude data in the HK file corresponding to the current event file. In case an arbitrary reference point is requested, the coordinates are specified via command line parameters skyranom and skydecnom.

Once the sky image reference point is known, the calculation of each event's sky coordinates is carried out in the following manner:

1. The satellite's attitude at the photon arrival time is determined. This is normally done by reading the attitude data from the Aspect extension in the HK file corresponding to the current event list file. Those data have a time granularity of 0.5s and the satellite's attitude at the requested time is calculated using a cubic-spline interpolation. It is possible to dispense with using the actual attitude data from the HK file and assume a fixed spacecraft attitude instead (see command line parameter skyfixedatt). This must then be given as set of 3-1-3 Euler angles in the celestial, earth-centered reference frame.
2. The actual pointing direction is corrected for the effect of abberation and the current satellite roll angle is calculated.
3. The event is projected onto the tangent plane using its linearized focal-plane coordinates and the quantities obtained in step 2. Hereby, the effect of a potential boresight-misalignment, is taken into account. This is done by means of a 3x3 rotation matrix to align the LECS's optical axis to the satellite's Z-axis, i.e., the current pointing direction. Per default the boresight-misalignment matrix is attempted to read from a corresponding file in the calibration database. This can be suppressed by specifying an alternative file or by forcing the program to use a hard-coded default matrix (see command line parameter opticscalfile).

The final sky image is north-oriented, i.e., the top of the image points towards the celestial north pole.

PARAMETERS

The following command line parameters are recognized by the program:

infiles = "" [string: list of existing event list files]

A blank or colon separated list of event files (of type _rev, or _lev) to be processed. Note that if blank is used as file name separator, the list has to be enclosed by "" in order to be considered as a single command line argument. If a file in infiles does not exist or is found not to be a valid LECS event file a warning message is issued and the processing continues with the next file in the list.



indirpath = "" [string: list of directory names]

A colon separated list of directories to seek for the specified input files. For each file given in infiles this is performed by first attempting to open the file as specified in infiles. If this fails, each directory component in indirpath is inspected for the location of the desired input file.



outdir = "=" [string: name of existing directory or "="]

The destination directory for the FITS output file. If "=" is specified for outdir (the default), the output file is written to the directory where the corresponding input file was found. Note that write access for outdir is needed.



clobber = no [boolean: yes|no]

In case of a raw event input file the name of the output file is simply derived by changing rev to lev, e.g. x_rev.fits becomes x_lev.fits. If a _lev file is to be processed the name is retained causing a name conflict. clobber = "yes" in this situation triggers that the input file will get overwritten by the new output file. If clobber is set to "no" an input file x_lev.fits will be renamed to x_lev.old.fits prior to creating the output file. In case a file x_lev.old.fits exists already from a previous run it will be lost.



fovradius = 0. [real: >=0.]

The radius in raw pixels of the circular region defining the detector's FOV. If it is given as 0. (the default), the actual value will be obtained from the LECS-optics geometry calibration file ([3]). The value will be close to 100 pixels.



rmevents = no [boolean: yes|no]

A boolean switch determining whether the events removal stage shall be carried out.



tgain = yes [boolean: yes|no]

A boolean switch determining whether the temporal gain correction shall be performed.



tgaincol = "GAIN_AVG" [string: valid HK parameter column name]

The name of the Bintable column in the HK file (type: hkg) containing the time-dependent gain values to be used for the temporal gain correction.



tgainint = "POLYNOMIAL" [string: "PLOYNOMIAL"|"SPLINE"]

This determines the gain interpolation method to be used. The value "POLYNOMIAL" selects a polynomial with a maximum degree specified via the tgainpolymaxdeg parameter. "SPLINE" signifies that the available gain values should be interpolated using a cubic spline.



tgainpolymaxdeg = 1 [integer: 0-10]

This parameters determines the maximum allowed degree of the polynomial which will be fitted to the gain data. The actual degree will be optimized by the utilized fitting algorithm. The default for this parameter is 1 which forces a linear interpolation of the gain data.



tgainplot = no [boolean: yes|no]

If set to "yes", a plot showing the interpolating gain function is produced and the program asks for acceptance before proceeding with the actual correction.



sgain = yes [boolean: yes|no]

A boolean switch determining whether the spatial gain correction shall be carried out.



sgainfile = "CALDB" [string: name of existing gain map file]

The name of a spatial gain map file to be used for performing the spatial gain correction. Assigning the special value "CALDB" to sgainfile causes evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file.



sgainfactor = 1 [real: 1-100]

A multiplicative constant used in the spatial energy gain correction.



blvsel = yes [boolean: yes|no]

A boolean switch determining whether the standard standard event selection shall be carried out.



blvseldovetocut = yes [boolean: yes|no]

If set to "no" the Veto selection part in the combined Veto/PI-BL cut will not be done.



blvselfract = 0.9 [real: 0.5-1.0]

This is the fraction of photons that shall be retained in the standard Veto/PI-BL event selection at all energies. Default is to retain 90% of the genuine X-ray events.



blvsele2pifile = "CALDB" [string: name of existing keV->PI conversion file]

This must be the name of an existing LECS calibration file of type CCNM001=KEV2PI used by the program to obtain coefficients which define the keV->PI conversion relation. This relation is needed during the event selection stage to convert an energy in keV to the corresponding PI channel number. Assigning the special value "CALDB" to blvsele2pifile causes evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If this fails, a hard-coded default relation will be used to convert energies to PI channel numbers.
For information on the structure and contents of the KEV2PI calibration file, please consult Chap. 23 in [2].



blvselcalfile = "CALDB" [string: name of existing BL-spectra calibration file]

This must be the name of an existing LECS calibration file of type CCNM001=BLSPEC needed by the event selection algorithm which is based on a combined VETO/BL cut. Assigning the special value "CALDB" to blvselcalfile will cause evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If the calibration file is not available the execution will be aborted.
For information on the structure and contents of the BLSPEC calibration file, please consult Chap. 25 in [2].



blcorr = yes [boolean: yes|no]

A boolean switch determining whether the BL correction stage shall be carried out.



blcorrestart = 3.0 [real: 0.1-10.]

The energy in keV below which no BL-correction shall be performed on the PI data.



blcorrblpifile = "CALDB" [string: name of existing BL-PI curve file]

This must be the name of an existing LECS calibration file of type CCNM001=BLPICORR which is needed by the BL-correction algorithm. Assigning the special value "CALDB" to blcorrblpifile will cause evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If this fail, execution will continue with hard-coded default values for the coefficients defining the BL-PI relation.
For information on the structure and contents of the BLPICORR calibration file, please consult Chap. 24 in [2].



lineshapefile = "CALDB" [string: name of existing lineshape parameter file]

This must be the name of an existing LECS calibration file of type CCNM001=LINESHAPE which contains the coefficients defining the shape of a spectral line as a function of energy. This information is needed by the BL-correction algorithm. Assigning the special value "CALDB" to lineshapefile will cause evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If this fail, execution will continue with hard-coded default values for all needed coefficients.
For information on the structure and contents of the LINESHAPE calibration file, please consult Chap. 22 in [2].



lincrd = yes [boolean: yes|no]

A boolean switch determining whether the coordinate linearization shall be carried out.



lincrdplatescale = "8.0s" [string: number followed by "m" or "s"]

This defines the actual plate scale for the coordinate linearization, i.e., the number of linearized pixels per mm on the focal plane. This parameter is supposed to be given as a number optionally followed by either of the letters "m" or "s". In the first case or without any suffix, the numeric value shall be interpreted a pixel-per-mm value, otherwise as arcsec/pixel. If 0 is assigned to this parameter the program will use the intrinsic value 7.8 pixels/mm (256 raw pixels on 32.8mm active entrance window length) which corresponds to a pixel size of 17.4". This will lead to a linearized pixel range of [0.0-255.0] in both directions (see above) and the X/Y sky image coordinates shall run from [1.0-256]. The default plate scale is 8"/pixel which will lead to a linearized pixel range of [0.0-511.0] and X/Y sky coordinates in the range [1-512].



lincrdcaldb = yes [boolean: yes|no]

If set to yes, the file containing the coefficients needed for the coordinate linearization is located by querying the SAX calibration database. In case this is not desired, lincrdcaldb = no signals that a set of default coefficients shall be used instead.



lincrdfile = "CALDB" [string: name of existing FITS file]

This must be the name of an existing LECS calibration file of type CCNM001=GMAP containing the coefficients which define the coordinate linearization transformation described above. Assigning the special value "CALDB" to lincrdfile causes evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If this fails, a set of hard-coded default values will be used.
For information on the structure and contents of the GMAP calibration file, please consult Chap. 20 in [2].



deadtime = yes [boolean: yes|no]

A boolean switch determining whether the dead-time calculation shall be carried out.



sky = yes [boolean: yes|no]

A boolean switch determining whether the detector-to-sky coordinate mapping shall be carried out.



skyfixedatt = no [[boolean: yes|no]

A boolean switch determining whether the spacecraft's attitude shall be assumed to be fixed during the observation. If set to "yes" the actual attitude must be specified as set of three 3-1-3 Euler angles in the celestial, earth-centered reference frame via command line parameters skyphi, skytheta, and skyphi.



skyphi = 0. [real: 0.-360.]

The first 3-1-3 Euler angle to specify the satellite's attitude if skyfixedatt is set to "yes".



skytheta = 0. [real: 0.-180.]

The second 3-1-3 Euler angle to specify the satellite's attitude if skyfixedatt is set to "yes".



skypsi = 0. [real: 0.-360.]

The third 3-1-3 Euler angle to specify the satellite's attitude if skyfixedatt is set to "yes".



skypointing = "KEYWORD" [string: "KEYWORD"|"MEANATT"|"USER"]

This determines the method by which the sky image reference point with the defined coordinates (128.5/128.5) will be chosen. "KEYWORD" signifies that the celestial coordinates of the reference point shall be taken as the values of the header keywords RA_OBJ and DEC_OBJ in the event file's primary header. "MEANATT" means that the coordinates will be computed as the mean values of R.A. and Dec. of the spacecraft's pointing axis during the observation. Finally, if "USER" is given as value of skypointing the celestial coordinates of the image reference point must be passed to the program via command line parameters skyranom and skydecnom respectively.



skyranom = 0. [real: 0.-360.]

The value of the R.A. of the sky image reference point if skypointing was chosen as "USER".



skydecnom = 0. [real: -90.-90.]

The value of the Dec. of the sky image reference point if skypointing was chosen as "USER".



opticsfile = "CALDB" [string: name of existing FITS file]

This must the name of an existing LECS calibration file of type CCNM001=OPTICSGEO read by evelin to obtain the following information:

1. 3x3 bore-sight misalignment matrix needed for the creation of sky images
2. detector rotation angle referred to the spacecraft's X/Y reference frame
3. focal plane coordinates of the center of the FOV
4. radius of the circle defining the FOV

Assigning the special value "CALDB" to opticsfile will cause evelin to attempt to interrogate the SAX/LECS calibration database for the location of this file. If this fails a set of hard-coded default values will be used for the above quantities.



caldb = yes [boolean: yes|no]

If set to "yes" all calibration files needed by the various stages of evelin will be attempted to locate by querying the SAX/LECS calibration database. This requires that

1. the SAX/LECS calibration database is accessible from the machine on which evelin is running
2. the standard FTOOLS task quzcif is available
3. the environment to use the calibration database has been properly set up (see general HEASARC calibration database documents)

Setting caldb equal to "yes" is equivalent to setting all of the above command line parameters ending in ...file equal to "CALDB"



verbosity = 2 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Verbosity level 3 results into detailed diagnostic messages. Default is level 2.



plotdev = "/XWIN" [string]

The default PGPLOT device. All devices supported by the FTOOLS PGPLOT library can be specified.



help = no [boolean: yes|no]

A boolean flag which, when set to yes triggers that the program prints out a brief on-screen description of all available command line parameters together with the current program version number and exits successfully.

EXAMPLES

1. Perform event linearization of the two raw event files kv183_rev.fits and kv550_rev.fits. Suppress the computation of sky coordinates, use cubic-spline interpolation for temporal gain values and show the resulting function before proceeding:

       evelin "kv183_rev.fits kv550_rev.fits" sky=no tgainint=spline tgainplot=yes
   

2. Perform event linearization of the file xxx_lev.fits except for the calculation of the total dead time. The input file shall be sought under /data/sax1/ and /data/sax2/ and program shall give maximum diagnostic messages as it proceeds through the various stages:

      evelin xxx_lev.fits indir=/data/sax1:/data/sax2 verb=3 deadtime=no
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010
2. SAX LECS calibration files: formats and contents,
   M. Busetta, F. Favata, G. Vacanti, U. Lammers, Doc. SAX/LEDA/0003
3. The Ground Calibration of the Low Energy Concentrator Spectrometer aboard SAX,
   G. Vacanti, Doc. SAX/LEDA/0015
4. The low-energy concentrator spectrometer on-board the SAX X-ray astronomy satellite,
   A.N. Parmar, et. al., A&A 1997
5. Representations of celestial coordinates in FITS,
   E.W. Greisen and M. Calabretta, A&A, 1995

BUGS

None known.

SEE ALSO

teleing, foting, calcgain