acis_detect_afterglow

Synopsis

Identify and flag cosmic ray afterglows

Syntax

acis_detect_afterglow infile outfile [logfile] [pha_rules]
[fltgrade_rules] [maxchain] [verbose] [clobber]

Description

NOTE: this tool has been superseded by acis_find_afterglow in CIAO 4.4.

`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_find_afterglow. The results obtained using acis_find_afterglow 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 4). In these situations, it may be advantageous to use the tool acis_detect_afterglow (after acis_find_afterglow) 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.

Examples

Example 1

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.

Example 2

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.

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes	yes
outfile	file	output				yes	yes
logfile	file	output	stdout
pha_rules	string		LTEQ
fltgrade_rules	string		NONE
maxchain	integer		16	2	1024
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

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?

Bugs

There are no known bugs for this tool.