.help decodeevt Aug98 ftools.xte
.ih
NAME
decodeevt -- Decodes event keywords in XTE Science Event files
.ih
USAGE
decodeevt infile outfile
.ih
DESCRIPTION
This task decodes event keywords in an input XTE Science Event file,
and generates more user-friendly column names.  The task should work
with any RXTE PCA event mode data set, excluding specialized
"Alpha", "2LLD", and "VLE" event types.  The task also decodes data
files of GoodXenon (or GoodXenonWithPropane) type that have been 
reassembled by the xenon2fits task (in 'X' mode).

The task outputs data in one of two formats, depending on the user's
choice.  The default mode is outformat='A'.  In this mode, the task
creates an output file with separate columns for TIME, CHANNEL,
PCUID, ANODE, and PROPANE. If no PCUID information (integer: 0-4) is
available in the input file, the values in the output column are set
to -999. If no ANODE information (string: "X1R"/"X3L" etc) is
available, the column contains INDEFs. If no PROPANE information (bit
0/1) is available, this column is not written to the output file.
Although this output file format is the default for backward 
compatibility purposes, the format is not particularly suitable for
subsequent processing with standard tools.

The second mode is outformat='OGIP'.  This mode represents an event
format this is more compatible with OGIP-standard tools.  However, in
this mode, the binary "Event" column is retained for compatibility
with 'seextrct'. Thus, it should be possible to filter the data using
fselect or xselect and then make a light curve or spectrum with
'seextrct' without using a bitmask filter.  The output columns in this
mode are TIME, Event, PCUID, ANODEID, and PHA.  The PCUID column
contains the PCU detector number (0-4).  If the corresponding data is
not available for a given input data mode, then PCUID, ANODEID or PHA
may be set to a NULL value.

The ANODEID column contains information about which anode (layer) was
hit.  The possible values and anode identifiers for ANODEID are: 10
(X1L), 11 (X1R), 20 (X2L), 21 (X2R), 30 (X3L), 31 (X3R), 40 (VPR =
Propane).  In other words, the "tens" digit contains layer number and
the "ones" digit contains left (=0) or right (=1) chain. 

Finally, the PHA column contains the bin number for this event mode.

IMPORTANT NOTE: In mode 'O'GIP, the PHA bin number corresponds to the
bin number assigned by the on-board rebinning logic.  For many event
modes, there are only 16, 32, 64 or 128 bins, which have been reduced
from the native 249 bins recorded by the sampling electronics.  Users
should take care to do filtering of the PHA in this rebinned space.
.ih
PARAMETERS
.ls infile [string - file name]
The name of input Science Event file.
.le
.ls outfile [string - file name]
The name of output file.
.le
.ls outformat [string - output format]
Format of output file, either "OGIP" for OGIP-style event file or 
"A" for non-standard output.  Default is "A" for compatibility.
.le
.ls (clobber = no) [boolean]
If "yes", an existing file with the same
name as the requested output file will be overwritten.
.ih
EXAMPLES
1.  Decode a Science Event file using DECODEEVT.
.nf
decodeevt infile=mySEfile outfile=myoutfile
.fi
.ih    
NOTES:
This tool supercedes the old, obselete SEEXPD.
.ih
BUGS
Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
.endhelp
