NAME

USAGE

DESCRIPTION

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

PARAMETERS

infile [filename]

Name of input event file or text file with list of files, preceded by "@" if multiple input files.

outfile [filename]

Name of output event file.

(gtifile) [filename]

Name of input gti file or text file with list of files preceded by "@" if multiple input files.

expr [string]

User-input expression applied to input file used to create GTI.

(selectfile = NONE) [filename]

Name of the select file or user input label file with labels and expressions. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information.

(label = NONE) [string]

Labels to read from label file specified by 'selectfile'. To input multiple labels, use a comma-separated list.

(mergegti = NONE) [string]

Attach GTI to event file and merge GTI mode (OR or AND) used in combining GTI files. If mergegti is set to NONE then an output GTI file is created and merging is done using an AND.

(cpkeyword = NONE) [string]

List of keywords to copy from input files, or ALL or NONE.

(upkeyword = yes) [boolean]

Update timing keywords from input file(s) in output file ([yes]/no).

(leapsecfile = REFDATA) [string]

Name of the leap second file. If the parameter is set to CALDB, the file is read from the calibration database; if REFDATA, the file is read from the REFDATA area.

(outexpr) [string]

Final expression used to create GTI. Output parameter only.

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string]

Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]

Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]

Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]

Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

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

SEE ALSO

LAST MODIFIED