NAME

xrtflagpix - Flags events for bad pixels and calibration source location.

USAGE

xrtflagpix infile outfile [parameter = ]

DESCRIPTION

'xrtflagpix' flags events occurring in bad pixels and bad column locations, events associated with the corner calibration sources and, depending on the CCD temperature, events on pixels located on the burned spots region (42 columns and 54 rows whose lower left corner is RAWX=307, RAWY=256). Only event files from the Swift XRT modes with positional information, Photon Counting (PC) and Windowed Timing (WT) are processed. Note that, for the WT mode only bad columns are defined and therefore flagged. Moreover, for PC Mode data, events whose central pixel in the 3x3 neighborhood has a PHA value (PHAS[1]) below a certain threshold are flagged. If the parameter 'thrfile' is set to CALDB, 'xrtflagpix' reads the threshold value stored in the calibration database file. By setting 'thrfile' to NONE, the task allows the user to set this threshold using the parameter 'phas1thr'.

'xrtflapix' allows for three different input files that identify bad pixels. These are:

  1. the Bad Pixels calibration file which includes the most up to date information about known bad pixels,
  2. the on-board Bad Pixels Table that includes the list of bad pixels used on-board for that observation and
  3. a user supplied list of bad pixels (this file has to be of the same format as the CALDB bad pixels file).

In the PC mode, events are flagged bad if any of the 3x3 neighborhood pixels are recognized as saturated by the on-board computer. For this mode the user must provide in input also the Housekeeping Header Packet file (parameter 'hdfile') to consider the bad pixels flagged on-board which are not present in the on-ground Bad Pixels CALDB files.
In the WT mode a column is flagged also if at least one of its nearby columns is bad.

The CCD has four calibration sources located at the corners of the detector. Events coming from these positions are flagged to allow for their identification during the screening. Also the events outside of the field of view of the instrument (FOV) are flagged. The locations of the calibration sources and the geometry of the FOV are read from a CALDB file specified through the parameter 'srcfile'.

The user has an option to choose which bad pixel list to use. All events are checked and flagged using the information obtained from the input bad pixels files. The bad pixels files contain a column 'TIME' including the mission elapsed time at which the pixel is first considered as bad. The task reads the 'TIME' column and, for a given observation, considers only the pixels identified as bad before the observation start date. The event flag is stored as a 16 bit binary number in the column STATUS. The flag, recorded in the column STATUS, indicates if the event is considered good or bad. If the event is bad the flag indicates why (for example dead or hot pixel) and also the origin of the information (e.g. if the bad pixel was stored in the CALDB file or the on-board Bad Pixels Table). The keyword XRTFLAG is added in the output file by the task.

The list of flags is the following:

Events STATUS flags
  • b0000000000000000 Good event
  • b0000000000000001 Event falls in a bad pixel from CALDB
  • b0000000000000010 Event falls in a bad pixel from on-board Bad Pixels Table
  • b0000000000000100 Event falls in a pixel at the location of the burned spots
  • b0000000000001000 Event falls in hot bad pixel
  • b0000000000010000 Event falls in a user bad pixel
  • b0000000000100000 Event falls in flickering bad pixels (PC) or due to trailing charge release (WT)
  • b0000000001000000 Event falls in a saturated pixel of the current observation
  • b0000000010000000 Event has a neighbor hot or flickering
  • b0000000100000000 Event falls in a bad column
  • b0000001000000000 Event has PHAS[1] < Event Threshold
  • b0000010000000000 Event has a neighbor bad from bad pixels list
  • b0000100000000000 Event out of FOV or out of detector boundaries
  • b0001000000000000 Event from calibration source 1
  • b0010000000000000 Event from calibration source 2
  • b0100000000000000 Event from calibration source 3
  • b1000000000000000 Event from calibration source 4

    • Each event will be associated with a value that is a combination of more than one of the STATUS flags listed above. For example, if an event falls in a single pixel marked as bad in the calibration bad pixels file and also in the on-board Bad Pixels Table, the event flag will be: b0000000000100011.
    If the parameter 'overstatus' is set to 'yes' (default) the STATUS column is overwritten. To update the STATUS column, without erasing the values of the previous 'xrtflagpix' run, the user must set to 'no' the 'overstatus' parameter.

    All bad pixels are stored in an extension of the output file. If this already exists and the parameter 'overstatus' is set to 'no', the extension is updated with new bad pixels. If requested by the user the bad pixel table is written in a separate output file. The bad pixels extension or output file contains the following columns: RAWX and RAWY give the raw coordinates of the pixel; Amp including the amplifier number; TYPE which identifies whether it is a single pixel (1), a column (2) or a row (3).For columns and rows of bad pixels, RAWX and RAWY indicate the start pixel and YEXTENT the length of the set of consecutive bad pixels included in the bad pixels file; BADFLAG stores a 16 bit binary number which indicates the origin of the bad pixel with the following meaning:

    Bad pixels BADFLAG flags
  • b0000000000000001 Bad pixels from CALDB
  • b0000000000000010 Bad pixels from on-board Bad Pixels Table
  • b0000000000000100 Pixels at the location of the burned spots
  • b0000000000010000 Bad pixels in the file provided by the user

    • PARAMETERS

    infile [file name]
    Name of the input event FITS file. Unix-compressed files are allowed, except when the outfile is set to NONE and the input file is overwritten.

    outfile [file name]
    Name of the output event FITS file. The value 'NONE' will cause the input file to be overwritten.

    hdfile [file name]
    Name of the input Housekeeping Header Packets FITS file (only for PC mode).

    (srcfile=CALDB) [file name]
    Name of the file containing the location of the calibration sources and the field of view geometry definition. This file is included in CALDB. If set to NONE, events associated to the calibration sources are not flagged.

    (bpfile=CALDB) [file name]
    Name of the input bad pixels file. The bad pixels file is read from Calibration Database if 'CALDB' is input. Type NONE if you don't want to consider this input.

    (userbpfile=NONE) [file name]
    Name of the bad pixel file provided by the user. The default is 'NONE',i.e., no user-provided file is considered.

    (bptable=CALDB) [file name]
    Name of the on-board bad pixels file. If CALDB is input, the on-board bad pixels file stored in the CALDB is read. If NONE is input, this parameter is ignored.

    thrfile [file name]
    Name of the input file containing PHAS[1] threshold values as a function of the CCD substrate voltage. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the threshold value must be input via the parameter 'phas1thr'.

    (phas1thr = 80)
    PHAS[1] threshold (min=0, max=4095) for the central pixel of a 3x3 neighborhood (only for Photon Counting Mode). Events below the threshold will be flagged. This parameter is used only if 'thrfile' is set to NONE.

    (maxtemp = 0.0)
    Temperature threshold above which burned spots region will be flagged (only for Photon Counting mode).

    (outbpfile=DEFAULT) [file name]
    Name of the output bad pixels file. If outbpfile=DEFAULT, the standard naming convention is used for the output file. If outbpfile=NONE, no output file is created.

    (overstatus=yes) [boolean]
    If overstatus=yes the STATUS column and the BADPIX extension are overwritten. If overstatus=no, the STATUS column and the BADPIX extension are updated with the new bad pixels.

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

    (clobber = no) [boolean]
    If clobber=yes, the output event file and bad pixels output file will be overwritten if files with the same names exist.

    (history = yes) [boolean]
    Write parameter values in HISTORY block.

    EXAMPLES

    1. Flag the events of the input event file sw00111622000xwtw2po_uf.evt considering the bad columns listed in the CALDB bad pixels file and in a user provided file named 'ubpfile.fits'. fill the STATUS column in the output file named 'sw00111622000xwtw2po_flag.evt'; write all the bad pixels used to flag events in the third extension of the output event file and in a separate output bad pixels file 'outbp.fits'. 

         xrtflagpix infile=sw00111622000xwtw2po_uf.evt
   outfile=sw00111622000xwtw2po_flag.evt 
   userbpfile=ubpfile.fits outbpfile=outbp.fits
    2. Flag the events considering the bad pixels included in the CALDB Bad pixels file flag events with a PHAS[1] value below the threshold of 90 DN input by the user; overwrite the input event file and use the standard naming convention for the output bad pixels file. 
         xrtflagpix infile=sw00111622000xpcw4po_uf.evt bpfile=CALDB 
   userbpfile=NONE outbpfile=DEFAULT outfile=NONE  thrfile=NONE phas1thr=90

    BUGS

    SEE ALSO

    LAST MODIFIED

    October 2008