sebitmask HEADAS help file

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.

USAGE

        sebitbask infile, filter, mtoken, column, bitfile, help, dryrun, clobber

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.

PARAMETERS

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).

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.)

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.

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.

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.)

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.

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.

clobber = yes [boolean]

Tells if existing output files are to be overwritten.

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 )         
     
     sebitbask infile, filter, mtoken, column, bitfile, help, dryrun, clobber

NOTES:

BUGS

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.

Please report problems to xtehelp@athena.gsfc.nasa.gov.