'ahscreen' script screens science event files by applying an expression that filters on specified columns in the file, and/or by applying a GTI file (generally, the GTI created by the 'ahgtigen' task).
The input specified by the 'infile' parameter is an event file or list of event files (the name of the text file with the list, preceded by "@"). If multiple input files are specified, they are merged prior to screening. A single output file with filename given by the 'outfile' parameter is created. Any extensions that are not EVENTS are not copied to the final output file. The user may filter on a single GTI file or a list of GTI files by setting the 'gtifile' parameter (in the latter case by preceding the name of the list text file with "@").
If GTI is being filtered it must be specified in the gtifile parameter including any GTI attached to the input event file(s). In the case where a GTI file list is input and mergegti=NONE, the input GTI are nevertheless combined using AND. Otherwise the GTI from a list are combined according to whether 'mergegti' is AND or OR. If 'mergegti=AND' or 'mergegti=OR', the final GTI for the output file is attached and applied to the output file. If 'mergegti=NONE' and an output GTI file is created based on the outfile parameter but not attached to the output event file. If there is no input GTI file or GTI extension, no GTI screening is done.
Following the GTI screening, the filtering proceeds by applying a filtering expression on columns present in the event data file. Users may specify an expression via the 'expr' parameter or use a pre-existing CALDB filtering expression stored in the label file specified by the 'selectfile' parameter. The label file is a FITS file containing several expressions, each with a label that identifies the filtering details (the screening expression, and the type of file the expression is applied to) used to screen events and create the GTI. A user-input label file may also be used via the 'selectfile' parameter. A single label, or any combination of labels in the form of a comma-separated list may then be specified using the 'label' parameter.
Users may update the timing keywords (EXPOSURE, TSTART, TSTOP, etc.) using the 'upkeyword' parameter, and other keywords may be copied from the first input file onto the final file using the 'cpkeyword' parameter.
There are three types of error codes returned from ahscreen: 1. Fatal : Error during ahscreen 2. Non-Fatal : No exposure after merging GTI 3. Non-Fatal : All events filtered during screening
The final output file is a single, filtered event file with fewer rows than the input file.
1. Run ahscreen with a simple screening expression.
ahscreen infile=sxs.evt outfile=sxs_cl.evt expr="ITYPE<5"
2. Run ahscreen with the event file CALDB expression labeled by PIXELALL.
ahscreen infile=sxs.evt outfile=sxs_cl.evt expr=NONE selectfile=CALDB label=PIXELALL
3. Run ahscreen with the event file CALDB expression labeled by PIXELALL, and an input GTI file to be merged with the input file GTI.
ahscreen infile=sxs.evt outfile=sxs_cl.evt gtifile=ahgengti.gti expr=NONE selectfile=CALDB label=PIXELALL mergegti=AND