acis_find_afterglow

Synopsis

Identify cosmic-ray afterglows and hot pixels for TIMED mode observations

acis_find_afterglow  infile outfile badpixfile maskfile statfile
[expnowindow] [probthresh] [cntthresh] [regwidth] [nfpixreg] [nfrepeat]
[tolerance] [runhotpix] [clobber] [verbose]

Description

A cosmic-ray "afterglow" is produced when a large amount of charge is produced as the result of an interaction with a charged particle. Most of the charge is clocked off of the CCD in a single frame. However, a small amount can be captured in charge traps, which release the charge relatively slowly. As a result, a sequence of events can appear in a single pixel over a few to a few dozen frames for timed-exposure mode data sets. The events need not occur in consecutive frames. There can be gaps of a few frames with no events for the pixel. In general, the amount of charge released per frame declines with time. However, the trend need not be monotonic, especially near the end of an afterglow.

The tool acis_find_afterglow searches for afterglows using a short, sliding time window (see the parameter expnowindow). If there is a statistically significant excess of events compared to the expected number of background events, then the excess is identified as an afterglow unless the excess seems to be associated with a source that is periodically dithered across the pixel (see the parameter probthresh). The algorithm used to estimate the nominal number of background events (see the parameters regwidth, nfpixreg, and nfrepeat) is designed to avoid contamination by bright sources. Essentially all of the afterglows that have four or more events are identified by acis_find_afterglow.

The tool acis_find_afterglow also searches for hot pixels using an algorithm that is similar to the afterglow-identification algorithm except that the time window used is the entire duration of an observation. Events associated with afterglows are ignored during the search for hot pixels.

The tool destreak should be used to process the input event data file before acis_find_afterglow is executed. The output file produced by acis_find_afterglow includes newly-identified afterglows and hot pixels as well as the bad pixels and columns in the badpixfile. The output file should be processed with acis_build_badpix to ensure (1) that pixels adjacent to newly-identified afterglows and hot pixels are handled properly and (2) that the list of bad pixels is in the proper order. Thereafter, the thread "Reprocessing Data to Create a New Level=2 Event File" should be followed to process the event data using the output of acis_build_badpix.

Although afterglows have been observed in continuous-clocking mode data sets, acis_find_afterglow and the other afterglow identification tools do not search for afterglows in such data sets.

NOTE: This tool superseded acis_detect_afterglow in CIAO 4.4.

Example

acis_find_afterglow infile="acisf00732_000N002_evt1.fits"
outfile="732_new_bpix.fits" badpixfile="acisf00732_000N002_bpix1.fits"
maskfile="acisf00732_000N002_msk1.fits"
statfile="acisf00732_000N002_stat1.fits"

This example shows the default use of acis_find_afterglow. The event data file acisf00732_000N002_evt1.fits is searched for afterglows and hot pixels. Pixels identified as bad in the file acisf00732_000N002_bpix1.fits and pixels identified as inactive in the file acisf00732_000N002_msk1.fits are excluded from the search. Information about newly-identified afterglows and hot pixels and about the bad pixels and columns in the file acisf00732_000N002_bpix1.fits is written to the output file 732_new_bpix.fits.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

The name(s) of the input event data file(s) (e.g. acisf00732_000N002_evt1.fits). Such files must be TIMED, not CONTINUOUS, mode event data files. While acis_find_afterglow can read Level 0, Level 1, and Level 2 files, users are urged to use Level 1 files because these files contain all of the events. Events that have "bad" GRADEs or that have one or more STATUS bit set are excluded from Level 2 files. The infile should be processed with the tool destreak before using acis_find_afterglow. Otherwise, pixels associated with horizontal streaks on ACIS-S4 might be misidentified as hot pixels.

Parameter=outfile (file required filetype=output)

The name of the output bad-pixel file. For each bad region, this file includes information about the SHAPE of the region (a "point" or "rectangle"), the COMPONENT identification number of the region (regions are numbered sequentially), the CHIPX and CHIPY coordinates of the region, the beginning (TIME) and ending (TIME_STOP) times during which the region is bad (e.g. the beginning and ending times of the afterglow or observation), and the STATUS of the region (a bit-encoded description of the reason(s) the pixel is identified as bad (see acis_build_badpix). The outfile includes newly-identified afterglows and hot pixels as well as the bad pixels and columns in the input badpixfile. The tool acis_build_badpix should be run on the outfile to ensure that pixels adjacent to the newly-identified pixels are handled properly and that the list of bad pixels and columns is properly sorted. Thereafter, follow the thread "Reprocessing Data to Create a New Level=2 Event File."

Parameter=badpixfile (file required filetype=input)

The name of the input bad-pixel file (e.g. acisf00732_000N002_bpix1.fits). If the badpixfile is the output of acis_build_badpix, instead of a bad-pixel file from the CALDB, then the file will include pixels with anomalous bias values or bias-parity errors and pixels affected by the FEP0 problem. Such pixels, other known bad pixels and columns, and pixels along the mid-chip node boundary are excluded from the search for afterglows and hot pixels. The events associated with afterglows are also excluded during the search for hot pixels. The information in the badpixfile is copied to the outfile in addition to information about newly-identified afterglows or hot pixels.

Parameter=maskfile (file required filetype=input)

The name of the input mask file (e.g. acisf00732_000N002_msk1.fits). This file defines the "active" region(s) of the CCD(s) used for the observation. Typically only the outer edge of a CCD is inactive. If a pixel is inactive, it is excluded from the search for afterglows and hot pixels.

Parameter=statfile (file required filetype=input)

The name of the input exposure statistics file (e.g. acisf00732_000N002_stat1.fits). This file includes information that is used to compute the times associated with the beginning and end of the interval during which a pixel is hot or affected by an afterglow (i.e. the values of TIME and TIME_STOP, respectively).

Parameter=expnowindow (integer not required default=10 min=1 max=100)

For a potential afterglow, this parameter specifies the maximum number of frames from one event in an afterglow to the next. For example, if expnowindow=1, then the events in an afterglow must occur in consecutive frames (i.e. there can be no "frame gaps"). The afterglow-detection efficiency is sensitive to the value of expnowindow, particularly for values less than 5.

Parameter=probthresh (real not required default=1e-3 min=1e-10 max=0.1)

This parameter specifies the minimum statistical significance of a potential afterglow or hot pixel. That is, the post-trials probability (see below) that a potential afterglow or hot pixel has occurred by chance must be less than the value of probthresh. The one, two and three sigma confidence limits correspond to probthresh=0.159, 0.0228 and 0.00135, respectively. The default value of probthresh (0.001 or the 99.9% confidence level) corresponds to the 3.09 sigma limit. The afterglow and hot-pixel detection efficiencies are sensitive to the value of probthresh, particularly for values much less than 0.0001.

The parameter probthresh is also used to specify the maximum statistical significance that an afterglow or hot pixel is associated with a bright source. Specifically, if the region immediately surrounding a potential afterglow or hot pixel (see the parameter regwidth) has an excess number of events and if the post-trials probability that this excess has occurred by chance is less than probthresh, then the potential afterglow or hot pixel is assumed to be associated with X-rays from an astrophysical source and the potential afterglow or hot pixel is not written to the outfile.

Note that the pre-trials probability P is the Poisson probability of obtaining at least N events if the number of events expected is M. Here N is the number of events associated with a potential afterglow or hot pixel and M is the number of background events expected during the afterglow or on the hot pixel. The post-trials probability P' = 1 - (1-P)^N', the binomial probability of obtaining one or more afterglow or hot pixel with a pre-trials probability of P or less given N' independent searches. For hot pixels, N' is the number of pixels that are searched to see if they are hot. For afterglows, N' is number of pixels searched multiplied by the number of sliding time windows used during the search.

Parameter=cntthresh (integer not required default=4 min=2 max=10)

This parameter specifies the minimum number of events in an afterglow. The afterglow-detection efficiency is very sensitive to the value of cntthresh.

Parameter=regwidth (integer not required default=7 min=3 max=255)

This parameter specifies the the pixels that are used to determine whether or not the events in a potential afterglow or hot pixel are associated with an astrophysical source instead of with charged particles or instrumental quirks (see the parameter probthresh). The default value of seven means that the forty-eight pixels in a 7 pixel x 7 pixel region surrounding the pixel in question are used. Since the region is symmetric about the pixel that may be hot or that may have an afterglow, the value of regwidth must be odd. If a pixel in the region is inactive, on a different node, or known to be bad, then the data for that pixel are not used. The afterglow and hot-pixel detection efficiencies are sensitive to the value of regwidth, particularly for values larger than about 15.

Parameter=nfpixreg (integer not required default=32 min=16 max=256)

The nominal number of background events per pixel (i.e. the fluence) is computed separately for each node of each CCD. The fluence for a given node represents an "average" of the fluences of several smaller regions on the node (see the parameter nfrepeat). The parameter nfpixreg specifies the size of the regions. To ensure that the size of a node is integer multiple of nfpixreg, nfpixreg may only be 16, 32, 64, 128, or 256. The afterglow and hot-pixel detection efficiencies are insensitive to the value of nfpixreg.

Parameter=nfrepeat (integer not required default=10 min=1 max=30)

The "average" fluence for a node is computed as follows. The number of events per pixel for each nfpixreg x nfpixreg sized region is calculated (see the parameter nfpixreg). Note that pixels that are inactive or known to be bad are excluded from the calculation. The subset of the fluences that are less than two times the mean of the fluences is used to obtain an initial estimate of the fluence F for the node. This initial estimate is the median of the subset of fluences. The root mean square (RMS) is calculated using the same subset of fluences. The initial estimate is refined by performing an additional N iterations. During each iteration, a subset of the full set of fluences is selected. The subset includes those fluences that are within two RMSs of the previous estimate of F. The median fluence F and the RMS are recomputed using the new subset of fluences. The value of F from the Nth iteration is used as the estimate of the fluence for the node. The parameter nfrepeat specifies the number of additional iterations N. The afterglow and hot-pixel detection efficiencies are insensitive to the value of nfrepeat.

Parameter=tolerance (real not required default=1.0e-15 min=1.0e-16 max=1.0e-6)

The pre-trials probability that a potential afterglow or hot pixel has occurred by chance is expressed as the sum of the terms in an infinite series. The computation of the sum ends when the fractional change in the sum, from one term to the next, changes by less than the value specified by the parameter tolerance. The same is true for the computation of the pre-trials probability that an afterglow or hot pixel is associated with a bright source. The afterglow and hot-pixel detection efficiencies are insensitive to the value of tolerance.

Parameter=runhotpix (boolean not required default=yes min= max=)

If the parameter runhotpix=yes, then acis_find_afterglow searches for hot pixels as well as afterglows. If runhotpix=no, then the tool searches for only afterglows.

Parameter=clobber (boolean not required default=no)

If a file exists that has the same name as the outfile, then the parameter clobber determines whether the existing file is overwritten or not. If clobber=yes, then the existing file is overwritten. If clobber=no, then the existing file remains unchanged (i.e. no output file is produced).

Parameter=verbose (integer not required default=0 min=0 max=5)

This parameter determines the amount of messages that is generated by acis_find_afterglow. If verbose=0, few messages are reported. If verbose=5, a larger amount of messages is produced.

Bugs

Caveats

On the rare occasions that there are two hot pixels adjacent to one another, the tool may not identify one of the hot pixels.

See Also

chandra

eventdef

tools::acis

acis_build_badpix, acis_check_pha_range, acis_clear_status_bits, acis_detect_afterglow, acis_process_events, acis_streak_map, acisreadcorr, destreak

tools::background

readout_bkg