sefilter HEADAS help file

NAME

sefilter -- help user generate RXTE event bitmask filter expressions

USAGE

         sefilter -h (for help) -c (for chatty behavior - this option 
                                    will update the user of everything
                                    found in the file and generally provide
                                    useful information.)

DESCRIPTION

sefilter is a script that helps the user generate an expression that is fed into SEBITMASK and then will examine the result of that run to determine if the file can be directly input into SEEXTRCT for filtering, or if it needs to be input to FSELECT to generate an SE FITS file ready for input into SEEXTRCT.

This FTOOL script queries the user for an input science event fits file, and reads the data descriptor contained in that file. This information is parsed and examined to determine which type of information in contained in the nX bit pattern within the file. If the types are supported then the number of bits is examined to determine the maximum value that can be expressed, and the user is supplied with this information and can select which values he is interested in.

For instance say that data descriptors contains the expression D[0:4]{3} from this the code will know that this expression can take on values from 0 --> 7 (4+2+1)=7, although the information in the []s show that only 0 --> 4 are meaningful. The user will be asked if they want to filter on this "token". If the response is "Yes" than you will be prompted to enter a string of values of the form 0,1,2 or 0-2, or 0-2, 4. From this information the script will generate an expression. For the first the expression generated will be

     (D[0:4] == 0 || D[0:4] == 1 || D[0:4] == 2)

for the second the exprssion will be

     (D[0:4] <= 2)

and for the last

     (D[0:4] >= 2 || D[0:4] == 4)

Of these three expressions ONLY the second would be a candidate for SEEXTRCT to preform the filtering, the others MUST be input to FSELECT for pre-filtering. The reason for this is that SEEXTRCT does NOT support ORed values, and the parentheses have to be striped since that may show a heirarchy for comparison, which SEEXTRCT does NOT support. Note that the first (0,1,2) and second (0-2) expressions give the same information, yet only the second gives and expression capable of being filtered by SEEXTRCT. This is because it is assumed that the USER is inputting the information in the most efficient way. If that is not the case, then he will have to wait a LONG time for FSELECT to pre-filter the file.

So what CAN SEEXTRCT filter? Any expression that can be expressed purely as a list of ANDed comparisons, e.g., D[0:4] <= 0 && E[CAL] == 1 && E[VXH] == 0 && Z[] >= 2 && Z[] <= 24. This will be translated into a series of non-heirarchy, ANDed comparisons that SEEXTRCT can filter. So what is the best way to ensure that the bitmask expression generated can be filtered by SEEXTRCT? The code will tell you if this bitmask can be processed by SEEXTRCT and give you the option to do so, or you can simply examine the filter for yourself.

PARAMETERS

infile [filename or @filename (only the first file is used)]

The name of the input XTE science event FITS file that is to be operated upon, or a file of filenames of which only the first is used since it is assumed that ALL of the other contain EXACTLY the same data descriptor.

column_name [column_name - Event in all standard SE files)

This is the column name EXACTLY as given in the file that is to have the above FILTER expression applied to it. Under normal circumstances this should be given as "Event".

bitfile [filename]

The name of the output file that will contain the bitmask expression that was generated from the constructed "filter" expression. This will change from SE file to SE file since the data is stored as and nX bit pattern that varies according to the data descriptor.

filter [created by this script]

This script reads the data descriptor stored in the input file and queries the user for what is wanted, and from those responses builds up a filter expression that is expressed in standard C notation, e.g.,

             (E[CAL]  ==  1  &  (D[0:4]==0  |  D[0:4]==1) & E[VXH,VXL] == 3)

Note that this programs is NOT to be used for selecting CHANNELS since each detector channel may be different from from each file channel. SEEXTRCT handles this correctly, so for channel and time filtering use SEEXTRCT, otherwise your results may be complete garbage!!!! YOU HAVE BEEN WARNED!

outfile [filename]

The name of the SE FITS file that is to be created that contains all of the information that matched you filtering criteria. *This is ONLY output if FSELECT is run. If SEEXTRCT is run, than the outroot+extenlc(pha) files are the output.

EXAMPLES

                      1. sefilter

NOTES:

BUGS

Please report problems to xtehelp@athena.gsfc.nasa.gov. Provide a detailed description of the problem and an e-mail address at which you can be reached if further information is required. Before reporting a bug please check your .PAR file. At the moment all comparisons are CASE SENSITIVE.