NAME
meevelin - the main SAXDAS MECS EVEnt LINearization module
SYNOPSIS
meevelin [infiles=] <file_names>
[parameter=value ...]
DESCRIPTION
meevelin
transforms raw event MECS FITS files (type: "_rev") into linearized
forms (type: "_lev") in which several basic corrections have been applied
to the data. These are:
- The raw PHA values have been corrected for
temporal changes in the energy gain (based on continuous monitoring of
Fe calibration sources).
- 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).
- A basic event filtering has been performed to remove "non-scientific"
events from the data.
- The focal-plane coordinates of detected photons have been "linearized"
to account for intrinsic distortions that are inherent to the detector.
- 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 module foting.
_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
[2] for further details):
PI | - the Pulse Invariant of the event in units
of detector channels
|
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, meevelin
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 build-in linearization stages
of meevelin are described in more detail in the following sections.
EVENTS REMOVAL
This first processing step simply removes all calibration sources events
and those outside the detector's FOV. A fraction of the calibration surces
photons fall inside the FOV.
For this reason the code uses 3 different circular rejection regions,
which partly overlap : 1 for the FOV and 2 for the calibration sources. The region coordinates are
retrieved from two calibration files specified by the parameters
lincrdgainfile for
calibration sources regions and
opticscalfile for FOV region.
This task is enabled by the parameter rmevents
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 BL signals, and
be removed via a discrimination against appropriately chosen BL
thresholds. This is done by performing a standard
one-dimensional BL cut. The event-selection stage is controlled via the
command line parameter blsel;
the lower and upper
BL level are retrieved from file (parameter
blfile)
or alternatively read as parameters blmin,
blmax.
TEMPORAL GAIN CORRECTION
This correction (enabled via parameter tgain)
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 mecalcgain
and contained as column data in a HK FITS file of type _hkg. Thus,
meevelin
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 a given
value (decided when running mecalcgain, default=600 s)
and, therefore, they have
to be interpolated which can either be done by means of a
polynomial function
(of degree tgainpolymaxdeg)
or a cubic spline (controlled via command line
parameter tgainint).
Prior to 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., the
PHA value of each event i is modified according to
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
[4].
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
(main parameter sgain).
This is done with the aid of a pre-processed
spatial gain map file which, either, stems from the SAX/MECS calibration
database, or can be explicitly specified (see command line parameter
sgainfile).
The spatial gain map file contains
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.
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
has to be applied (parameter lincrd).
By default, meevelin
attempts to read the sets of coefficients to perform the
linearization from a FITS data file in the SAX/MECS calibration database.
Actually (SAXDAS v1.0.0) the query to calibration database is superseded
by taking a set of hard-coded coefficients (see command line parameter
lincrdfile).
The 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 number of arcsecs per pixel in the
image (see command line parameter
lincrdarcspxl,
default is 8 arcsec/pixel).
The center of the FOV will become the central pixel in the linearized
image. The transformations are weakly dependent on energy expressed in KeV,
and an additional calibration file (parameter
lincrdgainfile) is needed where the energy-channel relation is
stored.
DETECTOR TO SKY COORDINATE MAPPING
In this stage (parameter sky)
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
[2] and [7] 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.
The values of celestial coordinates of the reference point are controled by
the switch skypointing.
If this parameter is set to USER, it is possible to specify them
using the 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:
- 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.
- The actual pointing direction is corrected for the effect
of abberation and the current satellite roll angle is calculated.
- 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
MECS'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 (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.
PI EQUALIZATION
This stage is not a required step for the standard events linearization
and it is activated if equalize="yes".
It allows the user to rescale the PI values of the current instrument unit
according to
the energy-channels relation of MECS1 (of course the task is not performed
at all on MECS1). This is useful if one plans to sum the 3 MECS spectra.
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 to be a valid MECS 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.
- rmevents = no [boolean: yes|no]
- A boolean switch determining whether the
events removal stage shall be carried out.
- blsel = yes [boolean: yes|no]
- A boolean switch determining whether the standard
BL event selection shall be carried out.
- blfile = "CALDB" [string: name of existing BL thresholds file]
- The name of the file containing the burst length thresholds to be used
for events selection.
If set to CALDB, meevelin will retrieve the appropriate file from the
calibration database. If set to the empty string "" the parameters
blmin and blmax will be read instead.
- blmin = 35 [real: 0-256]
- BL lower threshold
- blmax = 55 [real: 0-256]
- BL upper threshold
- tgain = yes [boolean: yes|no]
- A boolean switch determining whether the
temporal gain correction shall be carried out.
- 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: "POLYNOMIAL"|"SPLINE"]
- This determines the gain interpolation method to be used. "POLYNOMIAL"
selects a polynomial fit while "SPLINE" signifies that the available gain
values should be interpolated using a cubic spline.
- tgainpolymaxdeg = 3 [real: 1-10]
- The maximum degree of interpolating polynomial.
- 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 = "" [string: name of existing gain map file]
- The name of a spatial gain map file to be used for performing the spatial
gain correction. If set to CALDB, meevelin will retrieve the appropriate file
from the calibration database.
- sgainfactor = 1 [real: 1-100]
- A multiplicative
constant used in the spatial energy gain correction.
- lincrd = yes [boolean: yes|no]
- A boolean switch determining whether the
coordinate linearization shall be carried out.
- lincrdfile = "CALDB" [string: name of existing FITS file]
- The name of a FITS file from which the coordinate linearization
coefficients ought to be read. If set to CALDB meevelin will
retrieve the appropriate file from the calibration database.
Actually (SAXDAS v1.0.0) meevelin takes default hard-coded values.
- lincrdgainfile = "CALDB" [string: name of existing FITS file]
- The name of a FITS file containing the energy-channels relation used
for the energy dependence in the linearization transformation.
If set to CALDB meevelin will
retrieve the appropriate file from the calibration database.
- lincrdarcspxl = 8 [real: > 0]
- This parameter controls the pixel size in linearized (DETX,
DETY) and sky (X, Y) images . When set to a value
different from zero, the original platescale will be changed to the value
specified by the user. Units are arcsecs/pixel. Default is 8, i.e. a lower
value in comparison to the instrumental value (20 arcsecs/pixel). This
affects also the size of the image which can be 256 or 512 pixels wide,
depending on which one fits better the chosen platescale.
- sky = yes [boolean: yes|no]
- A boolean switch determining whether the
detector-to-sky coordinate mapping shall be carried
out.
- opticscalfile = "" [string: name of existing FITS file]
- The name of the MECS-optics geometry calibration file to
use. If set to CALDB meevelin will retrieve the appropriate file from the
calibration database.
- skypointing = "MEANATT" [string: USER | MEANATT | KEYWORD]
- The method to be used for calculating the celestial coordinates
associated to the image reference pixel. Using MEANATT
meevelin computes the median of (Ra,Dec) from
the attitude data distribution. In this case the image will
be displayed off center by about 10 arcmins, the amount of the misalignment
between the telescopes axes and the Z star tracker direction.
KEYWORD forces meevelin to take the values from the
header keywords RA_OBJ, DEC_OBJ. USER allows
to specify the above values via the parameters skyranom and
skydecnom.
- skyranom = 0 [real: 0.-360.]
- The value of R.A. associated to the sky image reference pixel if
skypointing=USER.
- skydecnom = 0 [real: -90.-90.]
- The value of Dec. associated to the sky image reference pixel if
skypointing=USER.
- equalize = no [boolean: yes|no]
- A boolean switch determining whether the
PI equalization shall be carried out. Default is
no.
- caldb = yes [boolean: yes|no]
- If set to "yes" all calibration files needed by the various stages of
meevelin will be attempted to locate by querying the SAX/MECS
calibration database. This requires that
- the SAX/LECS calibration database is accessible from the machine on
which meevelin is running
- the standard FTOOLS task quzcif is available
- 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.
When setting one of the above parameters to a file name
remember also to set caldb=no.
- 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
- 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.
meevelin "kv183_rev.fits kv550_rev.fits" sky=no tgainint=spline
FURTHER DOCUMENTATION
- The SAX LEGSPC Data Analysis System -
Software User Manual,
U. Lammers, Doc. SAX/LEDA/0010
- Contents and structures of event
and HK files in the SAX/LEGSPC data analysis system,
U. Lammers
and M. Busetta, Doc. SAX/LEDA/0002
-
Representations of celestial coordinates in FITS,
E.W. Greisen and M. Calabretta, A&A, 1995
BUGS
SEE ALSO
A. Matteuzzi (alessio@barolo.sdc.asi.it)
U. Lammers (Uwe.Lammers@astro.estec.esa.nl)
This page is maintained by
Fabrizio Fiore and
Alessio Matteuzzi