NAME

nuscreen -- Generate GTIs and use them together with event properties selection to screen NuSTAR event files.

USAGE

nuscreen infile gtiscreen evtscreen gtiexpr gradeepr statusexpr createattgti createinstrgti outdir mkffile hkfile outfile [parameter = < value >]

DESCRIPTION

'nuscreen' 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, iv) apply the dead time correction to the temporal keywords of the screened event files.

The GTIs are calculated considering two different set of parameters, one related to the satellite attitude and orbit (createattgti=yes) and the other related to instrument housekeepings (createinstrgti=yes). The GTI file is created by running the multi-mission task '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 files which are dependent on the observing mode selection provided in input through the parameter 'obsmode'. The supported observing modes are SCIENCE (01), OCCULTATION (02), SLEW (03), SAA (04), CALIBRATION (05) and SCIENCE_SC (06).

The user may supply attitude and/or instrument non standard criteria through the parameter 'gtiexpr' providing a boolean expression. 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.

'nuscreen' allows to screen the events previously flagged bad in the STATUS column (i.e. elimination of bad/hot pixels) 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 'gradeexpr' and 'statusexpr' parameters to 'DEFAULT'. Non standard screening criteria can be specified using the parameters 'gradeexpr' and 'statusexpr'. 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.gradeexpr=0-4 to select GRADE range between 0 and 4; gradeexpr=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. statusexpr="STATUS==b000000000x0xx000" to select only good events (see 'nuflagbad', 'nuhotpix' and 'nuflagevt' help files for the definition of the values in the STATUS column).

The parameters 'gtiexpr' and 'statusexpr' accept the expression directly from the command line or written into a text file and input by preceding the filename with '@' (e.g. statusexpr=@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.

'nuscreen' applies the dead time correction to the temporal keywords of the screened event files by running the 'nulivetime' task (see the 'nulivetime' help file for additional details).

PARAMETERS

infile [file name]
Name of the input event FITS file.

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 'statusexpr' and 'gradeexpr' 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'. If the paramater is set to 'NONE', the GTI are not calculated.

gradeexpr [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.

statusexpr [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'. If the paramater is set to 'NONE', the selection on the STATUS column is not set.

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.

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

(obsmode) [string]
Observing mode selection for GTI generation (SCIENCE=01,OCCULTATION=02,SLEW=03,SAA=04,CALIBRATION=05,SCIENCE_SC=06).

hkfile [file name]
Name of the input Housekeeping FITS File.

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

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

(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 'gradeexpr' and/or 'statusexpr' are set to 'DEFAULT'.

(depthcut = NOMINAL) [string]
Events depth cut screening (NONE,NOMINAL), used only if statusexpr=DEFAULT.

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

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

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

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

(cleancols = yes) [boolean]
If set to 'yes', the task deletes not required columns of the output L2 Event Files.

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

(clobber = no) [boolean]
If clobber=yes overwrite the output file.

(chatter = 3) [integer]
Chatter Level (min=0, max=5).

(history=yes) [boolean]
If set to 'yes', write history keywords to the output file.

EXAMPLES

  1. Generates the cleaned event file nu40060001001A01_cl.evt (DEFAULT name) and the GTI FITS file nu40060001001A01_gti.fits (DEFAULT name) using the screening expression to create the GTI written in the HKRANGE Calibration file and the events selection criteria defined in the EVTRANGE Calibration file. 

     > nuscreen obsmode=SCIENCE infile=nu40060001001A_uf.evt gtiscreen=yes evtscreen=yes gtiexpr=DEFAULT 
   gradeexpr=DEFAULT statusexpr=DEFAULT createattgti=yes createinstrgti=yes outdir=./outdir 
   hkfile=nu40060001001A_fpm.hk mkffile=nu40060001001A.mkf outfile=DEFAULT

    BUGS

    SEE ALSO

    LAST MODIFIED

    April 2013