NAME

calcgain - CALCulate time-dependent energy GAIN of Fe calibration sources and monitor background count rate

SYNOPSIS

calcgain [infile=] <rev_filename> [parameter=value ...]

DESCRIPTION

The calcgain task calculates the time-dependent energy gain of the two fixed iron calibration sources inside the SAX/LECS and, in addition, monitors the background count rate outside the detector's FOV. The program needs as input a raw event list file that comprises all calibration source events. The computed quantities are stored as Bintable columns in a new HK file of type _hkg whose structure closely resembles the _hkp type (see Chapter 2 in [1] for details). The nomial flow of operations in calcgain is the following:
1. Read a SAX/LECS raw events FITS file and select all events originating from the two Fe calibration sources. This selection is performed with the aid of two spatial windows whose position and size can be specified via command line parameters (see below).
   
   
2. Divide the total exposure time (= arrival time of last minus arrival time of first photon) into N equal intervals and subsequently, for each interval center, accumulate a PHA spectrum over a time period T. This step will generate for each calibration source a set of N spectra (counts vs. PHA channel number) which will be used to define the time-dependent gain g^j(t_i) := PHA_i^j/PHA_nom^j. g^j(t_i) shall designate the gain at time t_i (i=1,...,N) for calibration source #j, PHA_i^j is the centroid of the Gaussian curve that has been fitted to the accumulated spectrum #i for source #j, and PHA_nom^j is the nominal peak position (in PHA channels) of the Fe line for source #j. In case of poor statistics, i.e., if an accumulated spectrum is found to contain less than 25 counts, calcgain will not attempt to perform a Gaussian fit but set all gain related quantities (see below) to the value INDEF.
   
   
3. Create a new HK FITS file with the name extension _hkg.fits. The content of this file is identical to the HK file of type hkp (created with eng2phys) that corresponds to the event input file except that 13 columns have been added to the HK parameter extension. These are:
   • PHA1, PHA2 - centroid of Gaussian fitted to PHA spectra of calibration source #1/#2
   • FWHM1, FWHM2 - Full-Width-Half-Maximum value of fitted Gaussians for sources #1/#2
   • CHISQ1, CHISQ2 - reduced Chi^2 values of Gaussian fits
   • GAIN1, GAIN2 - gain values as defined above for calibration sources #1 and #2
   • GAIN12 - the ratio GAIN1/GAIN2
   • GAIN_AVG - the average of GAIN1 and GAIN2
   • CHISQAVG - reduced Chi^2 value corresponding to GAIN_AVG
   • BCKGND1, BCKGND2 - the average background count rate evaluated through event accumulation in two spatial windows outside the FOV.

   The HK parameter table contains a HK record for each second, however, changes in the energy gain will typically occur on timescales larger than 1s. Thus, for the sake of efficiency the default time granularity for the gain computation is set to a larger value Tg and filling-up the new HK table columns is done by repeated usage of the respective actual values. The effective value for Tg - in other words the above number N of time intervals - can be specified through a command line parameter granularity.

The primary output of calcgain, i.e., the gain related columns in the newly created HK file will be used by the evelin task to apply the temporal gain correction to scientific event list data.

PARAMETERS

The following command line parameters are recognized by the program:

infile = "" [string: name of existing _rev file]

The raw events FITS input file which shall be processed. This file must contain calibration source event data, otherwise, the energy gain cannot be calculated. In such a case, all gain related HK table columns will bet set to the value INDEF.



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

This must be the name of an existing directory in which the resulting new HK file of type _hkg shall be created. If outdir is given as "=" (the default) the effective value will be the directory name of the respective event list input file. In other words, the _hkg file will be created in the directory of the input file.



granularity = 25 [real: >= 1]

This parameter determines the granularity of the gain computations in s. Note that the actually used value will slightly differ from the one specified in order to get an integer number of equal time intervals. Lower values than 1s - the HK parameter time granularity - are not accepted. Default is 25s.



winsize = 50 [real: >= 10]

Size in s of the time window which is used for accumulating spectra. Note that with a given calibration source strength of approx. 25 cnts/s, winsize values lower than 10s would lead to very poor event statistics and possibly meaningless Gaussian-fits. Default is 50s.



fitfun = "S" [string: S|D]

A switch to control the type of Gaussian fit function to use. "D" stands for a double Gaussian of the form

     f(x) = p1 * exp(-(x-p2)^2/p3^2) + p4 * exp(-(x-const*p2)^2/p3^2)

where the constant is the ratio of the energies of the two Mn lines the calibration source iron line consists of. Specifying "S" as value for fitfun forces p4 to be zero, i.e., a simple Gaussian will be used.



fittol = 1.E-8 [real: > 0]

This parameter controls the abandoning criterion of the spectral fitting algorithm (modified Levenberg-Marquard) used by calcgain. fittol should not be assigned values greater than 1.E-7.



xmin1/xmin2 = 1/211 [integer: 0-255]

X coordinate of lower left corners of spatial windows used to select events from calibration sources #1 and #2 respectively.



ymin1/ymin2 = 207/1 [integer: 0-255]

Y coordinate of lower left corners of spatial windows used to select events from calibration sources #1 and #2 respectively.



xsize1/xsize2 = 44/40 [integer: 1-256]

Pixel sizes in X direction of calibration source windows #1 and #2.



ysize1/ysize2 = 44/40 [integer: 1-256]

Pixel sizes in Y direction of calibration source windows #1 and #2.



xbmin1/xbmin2 = 1/180 [integer: 0-255]

X coordinate of lower left corners of background monitor windows #1 and #2.



ybmin1/ybmin2 = 1/180 [integer: 0-255]

Y coordinate of lower left corners of background monitor windows #1 and #2.



xbsize1/xbsize2 = 75/75 [integer: 1-256]

Pixel sizes in X direction of background monitor windows #1 and #2.



ybsize1/ybsize2 = 75/75 [integer: 1-256]

Pixel sizes in Y direction of background monitor windows #1 and #2.



fe1_peak_pha = 410 [integer: 350-450]

The nominal Fe line peak position of calibration source #1 in PHA channels. Default is 410.



fe2_peak_pha = 410 [integer: 350-450]

The nominal Fe line peak position of calibration source #2 in PHA channels. Default is 410.



hkgfile = yes [boolean: yes|no]

A switch to control the creation of a new HK FITS file containing the calculated quantities, e.g., energy gain and background count rates. If hkgfile is set to "no", the generation of the hkg file is suppressed and the essential information will merely be printed on the screen.



plotspec = "0,1" [string of the form "integer,integer"]

If plotspec is assigned a value "i,j" this will generate a series of plots showing each i'th accumulated PHA spectrum starting with spectrum #j. Together with the raw data the fitted Gaussian function will be shown in each plot as well. Example: The assignment plotspec=10,3 will create a series of plots with the fitted spectra #3, #13, #23, etc. The value 0 for i will suppress any plotting output which is the default behavior. This spectra-plotting feature enables a simple visual control of the quality of the Gaussian fits.



plotdev = "/XWIN" [string: name of valid PGPLOT device]

A string determining a plot device on which a requested spectral plot (see above) shall be created. All devices supported by the FTOOLS PGPLOT library can be specified.



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.



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. Calculate the energy gain from the raw events file kv626_rev.fits with a time granularity of 100s and a time window size of 200s; program verbosity level is 1:

       calcgain kv626_rev.fits gran=100 win=200 verb=1
   

2. Calculate the energy gain from the raw events file xxx_rev.fits using the default granularity and accumulation window size. The output HK file shall be named yyy_hkg.fits and each 20th fitted spectrum shall be plotted on the default plotting device:

       calcgain xxx_rev.fits hkgfile=yyy_rev.fits splotspec=20,1
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010

BUGS

None known.

SEE ALSO

eng2phys, evelin