NAME

USAGE

DESCRIPTION

The ahscreen Perl 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, the files are merged prior to screening. One or two output files are created. The first is the output (screened) event file, with file name given by the 'outfile' parameter. The second file is an optional GTI file, and it is created when the parameter 'mergegti' is set to NONE. In this case, the combined input GTI are not attached to the output events file, but instead the GTI are written to a separate file (merged using an AND operation), the name of which is equal to the root name of 'outfile', with extension .gti. In the case that the parameter 'mergegti' is set to AND or OR, the input GTI are merged with the logical operator specified by 'mergegti' and appended in an additional extension in the output events file.

Note that any extensions in the input files that are not named EVENTS are not copied to the final output events 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 are being used for filtering, the GTI must be specified in the 'gtifile' parameter, including any GTI attached to the input event file(s). If there is no input GTI file or GTI extension, no GTI screening is performed.

Following the GTI screening, the filtering proceeds by applying a filtering expression on columns present in the event 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. Other keywords may be copied from the first input file into the final file using the 'cpkeyword' parameter.

   1. Fatal     : Error during ahscreen
   2. Non-Fatal : Zero exposure time after merging GTI
   3. Non-Fatal : All events were rejected during screening, based on the filtering criteria

The final output is a single, filtered event file with fewer rows than the input file, and a GTI file if 'mergegti=NONE'.

PARAMETERS

infile [filename]

Name of input event file or text file with list of files (preceded by "@" if this is a list of multiple input files).

outfile [string]

Name of output event file. If 'mergegti=NONE', the name of the output GTI file is constructed from the root name of 'outfile', with a .gti extension appended.

(gtifile = NONE) [string NONE|file name]

Name of input GTI file or text file with list of files (preceded by "@" if this is a list of multiple input files).

expr = NONE [string NONE|expression]

Expression applied in screening of input file 'infile', in addition to any specified in 'selectfile'. If set to NONE, no additional screening is applied.

(selectfile = NONE) [filename NONE|CALDB|file name]

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.

(label = NONE) [string]

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

(mergegti = NONE) [string AND|OR|NONE]

Attach GTI to the event file and merge GTI using OR or AND modes. If 'mergegti' is set to NONE, an output GTI file is created and merging is performed using AND. The name of this output GTI file is constructed from the root name of 'outfile', with a .gti extension appended.

(cpkeyword = NONE) [string ALL|NONE|keyword list]

List of keywords to copy from the first input file.

(upkeyword = yes) [boolean yes|no]

Determines whether to update timing keywords from the input file(s) in the output file.

(leapsecfile = REFDATA) [filename REFDATA|CALDB|file name]

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

(outexpr) [string]

Final expression used to create GTI; output parameter only.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]

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 DEFAULT|NONE|file name]

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

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records task parameters in HISTORY.

EXAMPLES

1. Run ahscreen on a XRISM Resolve event file for OBSID 100050020, with a simple screening expression to filter out any events that are not high, medium, or low resolution primaries or secondaries.

   ahscreen infile=xa100050020rsl_p0px1010_uf.evt outfile=xa100050020rsl_p0px1010_cl.evt expr="ITYPE<5"

2. Run ahscreen on a XRISM Resolve event file for OBSID 100050020, with a CalDB selection expression labeled by PIXELALL.

   ahscreen infile=xa100050020rsl_p0px1010_uf.evt outfile=xa100050020rsl_p0px1010_cl.evt expr=NONE selectfile=CALDB label=PIXELALL

3. Run ahscreen on a XRISM Resolve event file for OBSID 100050020, with a CalDB expression labeled by PIXELALL, and an input GTI file to be merged with the input file GTI.

   ahscreen infile=xa100050020rsl_p0px1010_uf.evt outfile=xa100050020rsl_p0px1010_cl.evt gtifile=xa100050020_gen.gti \
      expr=NONE selectfile=CALDB label=PIXELALL mergegti=AND

SEE ALSO

LAST MODIFIED