NAME

nuflagevt -- Flag events according to various cuts criteria in NuSTAR event files

USAGE

nuflagevt infile outfile [parameter = < value >]

DESCRIPTION

'nuflagevt' flags events according to various properties. First, the events are flagged on the base of their depth of interaction in the NuSTAR detectors. The depth cut profiles are read from the input CALDB file 'depthcutfile' which stores, for each pixel of the detectors, three energy depth cut channels 'E1', 'E2' and 'E3' as a function of the event energy.

For each event, 'nuflagevt' selects the CALDB 'E1', 'E2' and 'E3' values corresponding to its position on the detector and energy ('RAWX', 'RAWY' and 'PI' columns on the input event file) and flags it according to the following criteria:

  • SURRPI <= E1 (if E2,E3 > 0)
  • E2 < SURRPI <= E1 (if E2,E3 < 0)
  • SURRPI <= E3 (if E2,E3 < 0)

    • where 'SURRPI' is read from the input event file and stores the sum of the energies of the untriggered surrounding pixels, i.e. the pixels in the 3x3 array which are below the software threshold.

    Next, the task flags events according to the values of the 'PRIOR', 'RESET', 'PREPHAS[5]', and 'PI' columns of the input event file. The following criteria are used to flag the events:

  • "Baseline cut":

    (BASELINE < BASELINE1 and PI < PI_BASELINE) or (BASELINE > BASELINE2)

  • "Prior/reset cut" (FPMA only):

    (PRIOR2 < PRIOR < PRIOR3 and PI < PI_PRIOR) or
    (RESET2 < RESET < RESET3 and PI1_RESET < PI < PI2_RESET)

  • "Prior cut":

    PRIOR < PRIOR1

  • "Reset cut":

    RESET < RESET1

  • "Energy cut":

    PI < 0 or PI > 4095

    where the threshold values BASELINE1, PI_BASELINE, BASELINE2, PRIOR1, PRIOR2, PRIOR3, PI_PRIOR, RESET1, RESET2, RESET3, PI1_RESET, PI2_RESET are read from the input CALDB file 'evtcutfile'.

    To flag events, the 'nuflagevt' module updates the 'STATUS' column of the event file (see 'nuflagbad' help file). The format of this column is a 16-bit binary number specifying the quality of the flagging.

    The value of the 'STATUS' column used by 'nuflagevt' is the following:

    Events STATUS flags
  • b0000000010000000 Event fails depth cut
  • b0000000100000000 Event fails baseline cut
  • b0000001000000000 Event fails prior/reset cut
  • b0000010000000000 Event fails prior cut
  • b0000100000000000 Event fails reset cut
  • b0001000000000000 Event with PI out of range

    • This information can be used to filter the event files allowing to reduce the instrumental background.

    PARAMETERS

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

    outfile [file name]
    Name of output FITS event file.

    (depthcutfile=CALDB) [filename]
    Name of the input depth cut file or CALDB.

    (evtcutfile=CALDB) [filename]
    Name of the input event cut file or CALDB.

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

    (history=yes) [boolean]
    If set to yes, write parameter values and other information in HISTORY blocks.

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

    EXAMPLES

    1. Flag events in the NuSTAR event file named nu40060001001A_uf.evt. The 'STATUS' column of the output event file 'nu40060001001A_out.evt' is updated accordingly. 

      >  nuflagevt infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt

      BUGS

      SEE ALSO

      LAST MODIFIED

      September 2012