.help sebitmask  4.0 April 97 ftools.xte
.ih
NAME
sebitmask -- Reads a science event (SE) FITS file and takes as input a
boolean expression from the user to produce a bit-mask that can be
used by FSELECT. This code is a front-end to produce a file to be used
by FSELECT. This code is best when used by running the script
SESELECT.C or SESELECT.PL which will prompt the user for input and
then run SEBITMASK and FSELECT to produce and output file.
.ih
USAGE
sebitbask infile, filter, mtoken, column, bitfile, help, dryrun, clobber
.ih
DESCRIPTION
This task acts as a front end for FSELECT and will take as input a
boolean expression specifying the criteria for data to be
acceptable and will produce a file that can can input into FSELECT to
produce a file which contains data which meets that criteria. This
code is best when run by the PERL script SESELECT.PL which will run
SEBITMASK and FSELECT in succession.
.ih
PARAMETERS
.ls infile [string - file name of a SE data file]
The name of the input SE FITS file (and extension number in square
brackets or with a + sign in front).
.le
.ls filter [string - boolean expression or @filename]
The expression to be used to specify acceptable data using the
information in the SE FITS file. For example if the KEYWORD in the SE
FITS file (TEVTBn) is S[Zero2]{2},D[0:4]{3},E[VPR]{1},
E[VXH,VXL]{2},E[CAL]{1},E[X3R,X3L,X2R,X2L,X1R,X1L]{6},E[VLE]{1},
C[0:255]{8} an acceptable input might be:
(E[CAL] == 1 & (D[0:4]==0 | D[0:4]==1) & E[VXH,VXL] == 3).
This will also accept @filename in which filename contains an
acceptable expression to be filtered on. DO NOT USE FSELECT TO FILTER
ON CHANNEL VALUES!!! While FSELECT is perfectly capable of doing so,
it would use the RELATIVE CHANNEL value since it cannot read the
TEVTBn keyword. Use SEEXTRCT to filter on channel values and
time. Also SEEXTRCT has recently had added a BITMASK filtering option,
but you MUST use SEFILTER to create the BITMASK as SEEXTRCT cannot to
advanced filtering, but only crude filtering. Nevertheless, this
should be sufficient for 99 percent of everything that the average
user wants to do. But DO NOT attempt to create a bitmask file by hand,
use SEFILTER. (See SEEXTRCT's bitfile option, and SEFILTER for more
information.)
.le
.ls mtoken [string which MUST have a specific format!]
Since the TEVTBn keyword contains several bit-field descriptions and
each is delimitated by the value of the M-token, this has been
separated into a separate parameter and should not be included into
the "filter" expression as it will not be used for its desired
intention. You MUST enter this as M[N]{m}. Thus possible values and
translations are: 
  M[1]{1} -> 1,        (i.e., the first bit MUST be a 1)
M[127]{8} -> 01111111, (i.e. You have 8 bits, which must equal 127)
  M[1]{8} -> 00000001, (i.e. You have 8 bits, which must equal 1)
  M[2]{8} -> 00000010, (i.e. You have 8 bits, which must equal 2)
  M[4]{8} -> 00000100, (i.e. You have 8 bits, which must equal 4)
 
***M[0]{1} is NOT shown, but is special.***
If you set M[0]{1} you will get all other values except M[1]{1}!
No other filtering is allowed if this is the case as EACH field has
different meanings for each bit placement.
.le
.ls column [string]
The name of the column in the FITS file that the FILTER expression is
to apply to. This is ALWAYS "Event" for an XTE SE data file. 
.le
.ls bitfile [string - filename]
This is the name of the output file that will contain the generated
bitmask expression that is to be input into FSELECT using the @filename
capability at the "expr" parameter. (Or MAY be suitable to be input
into SEEXTRCT as "filename" at the bitfile prompt. See SEEXTRCT and
SEFILTER for more information.)
.le
.ls help [logical - yes or no]
This tells SEBITMASK to write out a HELP file explaining the 5 major
tokens used in SE files, there are the M-token (partially explained
above), the Z-token (this is VERY SPECIAL and SEFILTER should be used
for all files containing Z-tokens), the D-token, the E-token, and the
C-token. Just set this parameter to "yes" and you will get a detailed
output explaining each of these. Use SEFILTER to be "walked" through
your creation of a bitmask file. 
.le
.ls dryrun [logical - yes or no]
Prints out information on what is stored in the TEVTBn keyword for
this file and gives each part delimited by the differing
M-tokens. Basically use this to see that things are working properly
and that the code is parsing the DDL properly. We have run into cases
in the past where things were changed up-stream without being notified
of these changes, and they have caused the processing software
problem. This is to allow the user to diagnose this problem and to let
us know if that is the case for his particular file. 
.le
.ls clobber = yes [boolean]
Tells if existing output files are to be overwritten. 
.le
.ih
EXAMPLES
1. Create a bitmask that can be input to FSELECT. In the example input
given in "filter" we would have an output file (if the input column to
be searched was Event) which contains:
(Event == bxxxxxxxx1xxxxxxxxxxxxxxx && 
 (Event == bxx000xxxxxxxxxxxxxxxxxxx || 
 Event == bxx001xxxxxxxxxxxxxxxxxxx ) && 
 Event == bxxxxxx11xxxxxxxxxxxxxxxx && 
 Event <= bxxxxxxxxxxxxxxxx01100100 )         
.nf
sebitbask infile, filter, mtoken, column, bitfile, help, dryrun, clobber
.fi
.ih    
NOTES:
.ih
BUGS
.ls SEBITMASK_V4.0.
	Sebitmask is relatively stable at this point; however, we are
continuing to work on better ways for the average user to make use of
this powerful tool in their data analysis. At present seselect and
sefilter are the only tools available. In the future GUI's will be
available which make the derivation of bitmasks more intuitive. 
.le
.ls Please report problems to xtehelp@athena.gsfc.nasa.gov.
.le
.ih
SEE ALSO
FSELECT SESELECT
.endhelp

