|AHELP for CIAO 4.2||
Identify and flag cosmic ray afterglows
acis_detect_afterglow infile outfile [logfile] [pha_rules] [fltgrade_rules] [maxchain] [verbose] [clobber]
`acis_detect_afterglow' identifies residual charge from cosmic rays in CCD pixels, released over consecutive exposures. These events are flagged by status bits in the output event file.
The tool runs on a stack containing one or more event files and produces a corresponding output file stack. The input stacks are processed in a 1-1 pairing. The input file is read in one exposure at a time and is checked against previously read exposures for afterglow events. When a flaring pixel is detected, it is marked and a count of the total number of exposures that the afterglow persisted is maintained. When the afterglow subsides, reaches a user specified chain length, or the end of the input file is reached, the number of affected exposures is written in the corresponding output events.
To qualify as afterglow events, the event chip coordinates and exposure numbers are always utilized; chip coordinates must be identical and the exposure numbers must be consecutive. Optional criteria are the checking of PHA, fltgrade and chainlength. These checks may be done such that the current row's values are less than, less than or equal to, or equal to the previous row's values.
`acis_detect_afterglow' will run on any FITS event file which contains the following columns: expno (long), chipx (short), chipy (short), and status (32 bit). PHA (long) and fltgrade (short) are only required if the "pha_rules" or fltgrade rules parameters are set to anything other than "NONE". Other columns are not utilized but merely propogated to the output file. It is the user's responsibility to ensure that the columns specified above conform to the expected data types. (Note: the types listed above are defined in the "ACIS Level 1 to archive Interface Control Document" and are subject to change.)
This tool was applied by the CXC pipeline to all ACIS observations up until processing version DS 7.4.0. The use of acis_detect_afterglow has been replaced by the use of acis_run_hotpix. (The "Remove the acis_detect_afterglow Correction" thread describes how to remove the afterglow correction for cases in which the correction may be inappropriate.) The results obtained using acis_run_hotpix should be sufficient unless a user is interested in searching for or studying sources that have a small number of counts (i.e. less than about 10). In these situations, it may be advantageous to use the tool acis_detect_afterglow (in addition to acis_run_hotpix) to try to eliminate afterglows that have only a few events. Some care is required to ensure that acis_detect_afterglow does not eliminate a significant number of real x-ray events.
acis_detect_afterglow acisf051271721N001_evt1.fits acisf051271721N001_ada_evt1.fits
Run acis_detect_afterglow on the file acisf051271721N001_evt1.fits to create an output file acisf051271721N001_ada_evt1.fits which has status bits set for flaring pixels.
acis_detect_afterglow acisf051271721N001_evt1.fits acisf051271721N001_ada_evt1.fits pha_rules=EQ fltgrade_rule=NONE maxchain=16
Run acis_detect_afterglow on the file acisf051271721N001_evt1.fits to create an output file acisf051271721N001_ada_evt1.fits which has status bits set for flaring pixel chains of length up to 16 exposures. Only count rows with identical pha values (and chip positions). Do not check the fltgrade values.
Parameter=infile (file required filetype=input stacks=yes)
An event file or a stack of files.
This value specifies the name of the input event file(s) to process. The specified files (FITS format) must exist and have read permission. If using a stack, the number of stack elements must have a 1-1 correspondence with the outfile stack.
Parameter=outfile (file required filetype=output stacks=yes)
An event file or a stack of files
This value specifies the name of the output file(s) to create from the input files. The files will be identical to the input files with the exception of the status column which will have bits set to indicate detected flaring pixels. If using a stack, the elements in the stack must have a 1-1 correspondence with the items in the infile stack.
Parameter=logfile (file filetype=output default=stdout)
A text file or 'stdout'.
This value specifies the name of the ascii text file which acis_detect_afterglow will generate if the verbose parameter (see below) is set to a value other than 0. If the value is set to "stdout", the output will be redirected to standard output (typically the screen)
Parameter=pha_rules (string default=LTEQ)
PHA criteria for subsequent events
The pha_rules parameter is used to specify the relationship between the pha column of two consecutive exposures. The check may be such that the current exposure's pha is less than (LT), less than or equal to (LTEQ), equal to (EQ), or not checked (NONE) against the previous exposure's pha value.
Parameter=fltgrade_rules (string default=NONE)
Fltgrade criteria for subsequent events
The fltgrade_rules parameter is used to specify the relationship between the fltgrade column of two consecutive exposures. The check may be such that the current exposure's fltgrade is less than (LT), less than or equal to (LTEQ), equal to (EQ), or not checked (NONE) against the previous exposure's fltgrade value.
Parameter=maxchain (integer default=16 min=2 max=1024)
Maximum number of exposures for a single flaring event
This value allows the user to specify the maximum number of exposures that a flaring pixel should be counted for before resetting the count. For values less than 16, it determines the maximum value of the after glow status bits for chains that are of maxchain length.
Parameter=verbose (integer default=0 min=0 max=5)
Option which allows the user to request a varying level of textual output to the log file based upon the program execution.
Levels range from 0 to 5 with 0 representing no information and 5 representing as detailed a log as possible.
Parameter=clobber (boolean default=no)
Clobber output file if it exists?
See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.