NAME

USAGE

DESCRIPTION

'searchflickpix' is a mission-independent task that reads an input event file to search for flickering pixels, which are pixels that exhibit anomalous pulse height over a short period of time (usually less than an observation) and are caused by radiation damage on a semiconductor detector. The tool outputs a file containing events affected by the detected flickering pixels in the first 'EVENTS' extension. If the parameter 'cleanimg=yes', then the converse is recorded, the clean events not affected by flickering pixels. In the second 'PIXELS' extension, the location of each flickering pixel is recorded, along with the number of counts, duration, and average pulse height of the flickering pixel. This task is based on the ftool 'cleansis', originally developed for the ASCA SIS, but it is significantly altered from the original tool to have more universality and flexibility. It is a mission-independent tool, but is meant to be used for event data from CCD-type detectors, like ASCA SIS and Suzaku XIS.

The main routine for flickering pixel detection is a two-stage process, similar to that in the ASCA task 'cleansis'. This procedure is performed separately for each detector chip as specified by the 'chipcol', 'firstchip', and 'lastchip' parameters. After the event file is read, event counts in each pixel are compared to the mean counts in the full chip, and the pixels where the Poisson probability (calculated using 'impfac') exceeds the threshold given by the 'logprob1' parameter are flagged. The pixel locations for this comparison are defined by the 'xcol' and 'ycol' parameters. Next, the counts in each pixel are compared to the pixels in a surrounding box of size ('cellsize' x 'cellsize'), and anomalous pixels are flagged similarly to the first step but with anothor Poisson probability parameter, 'logprob2'. If the surrounding pixels yield no counts, a zero background threshold specified by the parameter 'bthresh' is applied instead. This second Poisson search is repeated if 'iterate=yes'. Last, if 'flagedge=yes', pixels along the chip edges are flagged as flickering pixels for the full duration of the observation.

The input events can be filtered several ways before the flickering pixel search is done. By changing 'chanmin' and 'chanmax', a pulse-height filter (>= chanmin && $lt;= chanmax) is applied to the events used for the flickering pixel search. These parameters are ignored if 'chancol=NONE'. Similarly, spatial filters can be applied with 'xmin', 'xmax', 'ymin', and 'ymax'. The default parameter settings uses the TLMIN and TLMAX header keywords corresponding to the appropriate column, effectively applying no filter. A grade filter may be applied using the 'gradecol' and 'grade' parameters. Finally, the 'n_division' parameter may be used to divide the observation into equally-spaced time bins and search each duration separately. This is useful to search for short-duration flickering pixels that might not be flagged in a long observation with high background signal.

The parameter 'cellsize' must be an odd integer or zero, and it is recommended to be about 1/4 of the PSF size, or 7 pixels for SXI. If 'cellsize=0', a simple counts-per-pixel cutoff is applied, so any pixels in the chip image containing more than 'bthresh' counts are flagged as flickering. The recommended value for 'logprob1' is log10(1/chipsize), where 'chipsize' is the total number of pixels in a single detector chip. This is about -5.6 for SXI. For these values, 'bthresh=3' 3 is recommended, although a lower threshold may be set based on the expected background rate.

After the flickering pixels are determined, and as an update from cleansis, this tool calculates and outputs to the 'PIXELS' extension a time duration (or START and STOP) when the flickering events are observed for each detected pixel. This function is disabled when the parameter 'timecol=NONE'. In most cases, START and STOP might be identical to TSTART (observation start time) and TSTOP (observation stop time), respectively. However, given that flickering pixels are not persistent but repeat on timescale ranging from hours to days, the duration can be shorter than the entire observation time, especially for a long-exposure observation. If the parameter 'duration=yes', a detailed duration search is performed for to determine how long each flickering pixel is actually flickering. This information is output as the FRACTION column in the 'PIXEL' extenstion, and it is the fraction of time the pixel flickers between START and STOP. The time-averaged pulse height in each plickering pixel is also output to the 'PIXELS' extension unless the parameter 'chancol=NONE'.

PARAMETERS

infile [filename]

Input event file. The 'EVENTS' extension must be present.

outfile [filename]

Output event file.

(timecol = TIME) [string]

Time column (or NONE). This column provides the time information used to determine first and last times when flickering events occurr in each detected flickering pixel, outputing 'START' and 'STOP' columns in the 'PIXELS' extension. If set to NONE, this time dependence is disabled.

(chipcol = CCD_ID) [string]

Chip column (or NONE). If set to NONE, then all events are searched together for flickering pixels. Otherwise, events are searched separately by 'chipcol' grouping. For an instrument with one physical detector per event list, the parameter should be set to NONE; for instruments with multiple detectors in a single events list, the proper column name should be specified.

(xcol = ACTX) [string]

X coordinate column.

(ycol = ACTY) [string]

Y coordinate column.

(chancol = PI) [string]

Pulse height column (or NONE). The tool calculates the average pulse height values of the flickering events for each detected pixel, and outputs this as the 'chancol' (e.g., 'PI') column in the 'PIXELS' extension. If set to NONE, this feature is disabled and the column is not output.

(gradecol = GRADE) [string]

Event grade column (or NONE). If this name is specified, only events with specific grade(s) given in the 'grade' parameter are used in accumulating the chip image for flickering pixel search. If set to NONE, all grades are used, and the 'grade' parameter is ignored.

(grade = 0) [string]

Event grade(s) for clean (or ALL). This should be a list of grade values to use in accumulating the chip image for the flickering pixel search. Values should be comma-separated, and ranges can be specified by a dash. For example, 'grade=0,2,3,4,6' and 'grade=0,2-4,6' are equivalent. If set to ALL, all grades are used. This is the same result as setting 'gradecol=NONE', and if that is specified, the setting of the grade parameter is ignored.

(n_division = 1) [integer]

Divide total observation time into the given number.

(cleanimg = no) [boolean]

If set to yes, the cleaned (non-flickering) events are output instead of the flickering events (yes/[no]).

cellsize [integer]

Poisson clean cell size (odd integer > 1). This is given in units of pixels, and it must be an odd integer greater than 1 to use that size. If set to 0, this invokes the simple counts-per-pixel cutoff.

impfac [real]

Impact factor for gamma function. This is used for the Poisson search, and in 'cleansis' it has been a fixed value of 320.

logprob1 [real]

The LOG (base 10) of the Poisson probability threshold for the first-step flickering pixel search (using the entire chip). It must be negative. If 'cellsize=0', this parameter is ignored.

logprob2 [real]

The LOG (base 10) of the Poisson probability threshold for the second-step flickering pixel search (comparing to the surrounding pixels). It must be negative. If 'cellsize=0', this parameter is ignored.

(iterate = yes) [boolean]

If set to yes, iterate the second step Poisson clean ([yes]/no).

(flagedge = no) [boolean]

If set to yes, pixels along the chip edge are flagged as flickering for the entire duration of the observation (yes/[no]).

bthresh [integer]

Zero background cutoff threshold, applied when the local mean background level is zero. Check this number against the actual background count rate. If 'cellsize=0', this parameter gives the fixed count cutoff threshold.

(duration = no) [boolean]

If set to yes, a detailed search for flickering duration is performed (yes/[no]).

(sigma = 3.0) [real]

Significance level for flickering duration.

(firstchip = TLMIN) [string]

Minimum value for the 'chipcol' column. If set to TLMIN, the task searches for the header keyword TLMIN of 'chipcol' and uses that value. If set to NONE, this parameter is ignored.

(lastchip = TLMAX) [string]

Maximum value for the 'chipcol' column. If set to TLMAX, the task searches for the header keyword TLMAX of 'chipcol' and uses that value. If set to NONE, this parameter is ignored.

(xmin = TLMIN) [string]

Minimum value for the 'xcol' column. If set to TLMIN, the task searches for the header keyword TLMIN of the related column, and uses that value.

(xmax = TLMAX) [string]

Maximum value for the 'xcol' column. If set to TLMAX, the task searches for the header keyword TLMAX of the related column, and uses that value.

(ymin = TLMIN) [string]

Minimum value for the 'ycol' column. If set to TLMIN, the task searches for the header keyword TLMIN of the related column, and uses that value.

(ymax = TLMAX) [string]

Maximum value for the 'ycol' column. If set to TLMAX, the task searches for the header keyword TLMAX of the related column, and uses that value.

(chanmin = TLMIN) [string]

Minimum value for 'chancol' to use in accumulating the chip image for flickering pixel search. If set to TLMIN, the task searches for the header keyword TLMIN of the related column, and uses that value. If 'chancol=NONE', this parameter is ignored.

(chanmax = TLMAX) [string]

Maximum value for 'chancol' to use in accumulating the chip image for flickering pixel search. If set to TLMAX, the task searches for the header keyword TLMAX of the related column, and uses that value. If 'chancol=NONE', this parameter is ignored.

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string]

Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]

Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]

Records tool parameters in HISTORY if set to yes ([yes]/no).

(mode = ql) [string ql|hl|q]

Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

1. Detect flickering pixels from an SXI event file using a 5x5 background cell amd a 3 count-zero background threshold. The output file contains the "flickering pixels" (not cleaned events, as was output by cleansis) in the 'EVENTS' extension.

   searchflickpix infile="input.evt" outfile="output_flickering.evt" \
        cellsize=7 impfrac=320 logprob1=-5.6 logprob2=-5.6 bthresh=3
   

2. Same as above, but write out the cleaned (non-flickering) event list in the output file.

   searchflickpix infile="input.evt" outfile="output_clean.evt" \
        cellsize=7 impfrac=320 logprob1=-5.6 logprob2=-5.6 bthresh=3 cleanimg=yes
   

3. Same as example 1, but a Suzaku XIS event file is used as input. Each XIS event file contains data from one CCD, but with a larger chip size (1024x1024).

   searchflickpix infile="input_xis.evt" outfile="output_flickering.evt" \
        cellsize=5 impfrac=320 logprob1=-6.0 logprob2=-6.0 bthresh=3 \
        chipcol=NONE xcol=DETX ycol=DETY
   

4. Clean an event file to global fixed threshold of 20 counts per pixel. Exclude PHA values greater than 1200.

   searchflickpix infile="input.evt" outfile="output_clean.evt" \
        cellsize=0 impfrac=320 logprob1=-6.0 logprob2=-6.0 bthresh=20 \
        chancol=PHA chanmin=0 chanmax=1200 cleanimg=yes
   

SEE ALSO

cleansis, sxiflagpix

LAST MODIFIED