NAME

nuflagbad -- Flag events for bad pixels in NuSTAR event files

USAGE

nuflagbad infile outfile dispixfile [parameter = < value >]

DESCRIPTION

'nuflagbad' flags events occurring in bad pixels of the detectors of NuSTAR. The task allows for three different input files that identify bad pixels. These are:

  1. the on-ground Bad Pixel Calibration File which includes the most up to date information about known stable bad pixels;
  2. the Disabled Pixel File which includes the list of pixels disabled by on-board processing for the current observation;
  3. a user supplied Bad Pixel File (with the same format as the on-ground CALDB bad pixel file).

The on-ground Bad Pixel CALDB File contains for each pixel a column 'TIME' including the mission elapsed time at which the pixel is first recognized as bad. The Disabled Pixel File stores the list of pixels disabled by the on-board software which, for the current observation, monitors the behaviour of each detector pixel in discrete time intervals. The Disabled Pixel File also stores, for each disabled pixel, the corresponding time interval in the columns 'TIME' and 'TIME_STOP'.

All events are checked and flagged using the information obtained from the input bad pixel files. The user has an option to choose which bad pixel file to use. For the on-ground Bad Pixel CALDB File the task reads the 'TIME' column and, for a given observation, considers only the pixels identified as bad at the observation start date. In the case of the Disabled Pixel File, the pixels are flagged as bad by the task only during the time interval between the values of the columns 'TIME' and 'TIME_STOP'.

To flag events, the 'nuflagbad' module adds a new column, named 'STATUS', to the event file. The format of this column is a 16-bit binary number. The value of the 'STATUS' column specifies the quality of the flagging (i.e. if the event falls on a stable bad pixel from the on-ground CALDB File or on an on-board disabled pixel).

The task also flags events if any of the 8 neighborhood pixels falls on a bad pixel or outside the detector boundaries (i.e. the event is located on a detector edge). The position of these neighbor pixels is stored in a new column 'BADPOS' added by the task. The format of this column is a 8-bit binary number.

A specific keyword named 'NUFLAG' is added in the output file by the task.

The list of flags in the 'STATUS' column is the following:

Events STATUS flags
  • b0000000000000000 Good event
  • b0000000000000001 Event falls in a bad pixel from on-ground CALDB Bad Pixel File
  • b0000000000000010 Event falls in a bad pixel from on-board disabled pixel
  • b0000000000000100 Event falls in a bad pixel from user bad pixel file
  • b0000000000001000 Event has a neighbor bad from bad/disabled/user pixel list
  • b0000000000010000 Event falls in a detector edge pixel

    • The list of bad pixels is stored in four distinct new extensions, named 'BADPIX', one for each of the four detectors. Optionally, if requested by the user through the parameter 'outbpfile', the bad pixels list is also written in a separate output file.

    The bad pixel extensions contain the positional and temporal information and a 16-bit binary number column, named 'BADFLAG', indicating the class of the bad pixel with the following meaning:

    Bad pixels BADFLAG flags
  • b0000000000000001 Bad pixel from on-ground CALDB Bad Pixel File
  • b0000000000000010 Disabled pixel from on-board software
  • b0000000000000100 Bad pixel in the file provided by the user

    • PARAMETERS

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

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

    dispixfile [file name]
    Name of the input on-board disabled pixel file or NONE for none.

    (bpfile=CALDB) [filename]
    Name of the input on-ground bad pixel file or CALDB or NONE for none.

    (userbpfile=NONE) [filename]
    Name of the user bad pixel file or NONE for none.

    (outbpfile=DEFAULT) [filename]
    Name of the output Bad Pixel file or DEFAULT to use standard name or NONE for none.

    (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 the events of the input event file 'nu40060001001A_uf.evt' considering the bad pixels listed in the on-ground CALDB Bad Pixel File and in the Disabled Pixel File named 'nu40060001001A_dspx.fits'. The list of bad pixels are stored in the 'BADPIX' extensions of the output event file ('nu40060001001A_out.evt') and in the output bad pixel fits file named 'nu40060001001A_bp.fits'. 

      >  nuflagbad infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt
   dispixfile=nu40060001001A_dspx.fits outbpfile=nu40060001001A_bp.fits
    2. Flag the events of the input event file 'nu40060001001A_uf.evt' considering the bad pixels listed in the on-ground CALDB Bad Pixel File, in the Disabled Pixel File named 'nu40060001001A_dspx.fits' and in a user provided file named 'userbadpix.fits'.The list of bad pixels are stored in the 'BADPIX' extensions of the output event file ('nu40060001001A_out.evt'). 
      >  nuflagbad infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt
   dispixfile=nu40060001001A_dspx.fits userbpfile=userbadpix.fits outbpfile=NONE

      BUGS

      SEE ALSO

      LAST MODIFIED

      March 2012