NAME

xrtscreen -- Generate GTI and use them together with other criteria to screen the data.

USAGE

xrtscreen gtiexpr exprgrade expr infile outdir createattgti createinstrgti gtiscreen evtscreen mkffile outfile [parameter=]

DESCRIPTION

'xrtscreen' allows to i) generate a GTI file based on attitude and/or instrument HK parameters, ii) screen the data using these GTIs, iii) screen events using a GRADE filter and/or a selection on the STATUS column. 'xrtscreen' supports all the XRT science modes and requires in input the Level 1 (or 1a) event or image file and the filter file (output of 'xrtfilter').

The GTIs are calculated considering two different set of parameters, one related to the satellite attitude and ephemeris (createattgti=yes) and the other related to instrument housekeepings (createinstrgti=yes). The GTI file is created via 'maketime' and contains the time intervals where events are considered good for science data analysis. Setting the input parameter 'gtiexpr' to 'DEFAULT' and 'hkrangefile' to 'CALDB', the attitude and instrument HK parameters screening expressions are built using the standard criteria contained in the HKRANGE Calibration file. If parameter 'obsmodescreen' is set to 'yes' (default) the task adds to the GTI generation expression the selection based on the observation mode (POINTING, SETTLING or SLEW) using the columns 'SETTLED' 'TEN_ARCMIN' and 'SAFEHOLD' of the input filter file.
The user may supply attitude and/or instrument non standard criteria through the parameter 'gtiexpr' providing a boolean expression (e.g. gtiexpr="CCDTemp>=-102&&CCDTemp<=-50"). The calculated GTIs are used to screen the events by setting the parameter 'gtiscreen' to 'yes'. A GTI file provided by the user is also accepted in input through the 'usrgtifile' parameter.

For Photon Counting mode, the task also excludes from the GTIs the CCD frames containing events with RAWX/RAWY coordinates out of nominal range.

'xrtscreen' allows to screen the events previously flagged bad in the STATUS column (i.e. elimination of bad pixels and calibration sources) and/or to apply a grade selection by setting the 'evtscreen' parameter to 'yes'. The standard screening criteria for GRADE and STATUS are defined in the EVTRANGE Calibration file and to use these the user should set the parameter 'evtrangefile' to CALDB and 'exprgrade' and 'expr' parameters to 'DEFAULT'.
Non standard screening criteria can be specified using the parameters 'exprgrade' and 'expr'. The first is for the selection on the GRADE column and the values can be input as a range or a single number (e.g.exprgrade=0-5 to select GRADE range between 0 and 5; exprgrade=0 to select only GRADE equal to 0). These inputs are used with the 'filter grade' command in 'xelect'. The second is for the selection on the STATUS column and the value should be input as a boolean expression, e.g. expr="STATUS==b0" to select only good events (see 'xrtflagpix' help for the definition of the values in the STATUS column).

The parameters 'gtiexpr' and 'expr' accept the expression directly from the command line or written into a text file and input by preceding the filename with '@' (e.g. expr=@file.txt). The expression in the file can be arbitrarily complex and can extend over multiple lines of the file. Lines that begin with 2 slash characters (//) are ignored and can be used to add comments.

If all the screening parameters are set to 'yes', the output events file contains only good events and the GTI extension is updated.

PARAMETERS

gtiexpr [string]
Expression to generate attitude and/or instrument HK GTIs. If set to 'DEFAULT', the boolean expression is constructed using the information in the file specified with the parameter 'hkrangefile'. A text file containing the expression can be specified by preceding the filename with '@', such as '@file.txt' If the paramater is set to 'NONE', the GTI are not calculated.

exprgrade [string]
Expression to select the column 'GRADE' in the input event file input as a single value or a range. If set to 'DEFAULT', the string is constructed using the information in the file specified with the parameter 'evtrangefile'. If the paramater is set to 'NONE', the GRADE selection is not set.

expr [string]
Expression to select events using the STATUS column in the input event file. If set to 'DEFAULT', the expression is contructed using the information in the file specified with the parameter 'evtrangefile'. A text file containing the expression can be specified by preceding the filename with '@', such as '@file.txt' If the paramater is set to 'NONE', the selection on the STATUS column is not set.

infile [file name]
Name of the input FITS event file. Unix-compressed files are allowed.

outdir [string]
Name of the output directory for products.

(clobber=no) [boolean]
If set to 'yes', the task overwrites existing output files.

(chatter = 3) [integer]
Verbosity Level from 0 to 5.

(history=yes) [boolean]
If set to 'yes', the task writes history keywords in the output files.

createattgti [boolean]
If set to 'yes', the GTI file includes good time intervals based on attitude parameters.

createinstrgti [boolean]
If set to 'yes', the GTI file includes good time intervals based on instrument HK parameters.

gtiscreen [boolean]
If set to 'yes', the event file is screened for attitude and/or instrument HK GTIs generated using the parameter 'gtiexpr'.

evtscreen [boolean]
If set to 'yes' the event file is screened for the expressions specified in the 'expr' and 'exprgrade' parameters.

obsmodescreen [boolean]
If set to 'yes' the task adds to the GTI generation expression the selection based on the observation mode (POINTING, SETTLING or SLEW).

acsscreen [boolean]
Used when 'obsmodescreen' set to 'yes', if set to 'yes' the selection based on the observation mode (POINTING, SETTLING or SLEW) screen for events with ACS flags in non standard pointing configuration.

mkffile [file name]
Name of the input filter file.

(gtifile = DEFAULT) [file name]
Name of the output GTI file. If set to 'DEFAULT', the standard naming convention is assumed for the filename.

(usrgtifile = NONE) [file name]
Name of the user input GTI file. A text file containing a list of GTI files can be specified by preceding the filename with '@'. If set to 'NONE' (default), this parameter is ignored.

(hkrangefile = CALDB) [file name]
HKRANGE Calibration File Name. If set to 'CALDB' (default), the attitude and instrument HK allowed ranges are from a file in the Calibration Database. This parameter is used only if 'gtiexpr' is set to 'DEFAULT'.

(timecol = TIME) [string]
Name of the TIME column in the input event file.

outfile [file name]
Name of the output screened event file. If set to 'DEFAULT',the standard naming convention is assumed for the filename.

(gtiext = GTI) [string]
Name of the GTI extension in the event file.

(evtrangefile = CALDB) [string]
Name of the input EVTRANGE Calibration File Name. If set to 'CALDB' (default), the event selection expression is contructed from the values stored in a CALDB file. This parameter is used only if 'exprgrade' and/or 'expr' are set to 'DEFAULT'.

(cleanup =yes) [boolean]
If set to 'yes', the task deletes temporary files.

EXAMPLES

  1. Produce the cleaned event file sw00052100007xwtw2po_cl.evt (DEFAULT name) and the GTI FITS file sw00052100007xwtw2po_clgti.fits (DEFAULT name) using the screening expression to create the GTI written in the HKRANGE Calibration file. The expression to screen for grades is supplied (exprgrade=0) and the elimination of bad pixels and calibration sources is not requested (expr=none). 

    xrtscreen gtiscreen=yes  evtscreen=yes gtiexpr=DEFAULT 
createattgti=yes createinstrgti=yes exprgrade=0 expr=NONE 
infile=sw00052100007xwtw2po_ufre.evt outdir=./
mkffile=sw00052100007s.mkf outfile=DEFAULT

BUGS

SEE ALSO

LAST MODIFIED

January 2016