Synopsis
Generate high frequency background maps (streakmaps) which identify ACIS streaks caused when bright source photons are applied to the wrong pixel during readout.
Syntax
acis_streak_map infile fovfile bkgroot regfile [nsigma] [msigma] [ssigma] [dither] [binsize] [k1] [k2] [tmppath] [clobber] [verbose]
Description
acis_streak_map is a script which generates high frequency background maps (streakmaps) for individual ACIS chips. It is specifically designed to identify streaks on a chip caused by bright source photons striking pixels along the readout column during readout. Output consists of a streakmap for each individual ACIS chip and a single region file identifying bright streaks on all chips.
General Algorithm
acis_streak_map identifies streaks by first selecting chip rows which do not contain sources and then summing counts in these rows along columns. The streakmap is created by calculating the average counts per row from the summed values and creating an image with columns populated by that average value (i.e. information from the one-dimensional data is projected back onto a two-dimensional image). acis_streak_map also attempts to identify the highest intensity streaks by flagging summed values significantly larger than the average summed value. A region file is generated which shows ds9 regions as boxes around the high intensity streaks found at the location of these largest values.
Selecting Source-Free Rows (parameters k1 and k2)
To identify chip rows that do not contain sources, a maximum allowable value of summed counts is determined, and any row with more than the maximum allowed counts is assumed to contain a source. Two candidate methods are used to determine the maximum summed value. The first max summed candidate value is equal to the median of the summed counts plus parameter k1 * the standard deviation of the summed counts. The second max summed candidate value is the mode of the summed counts * parameter k2. The lesser of these two candidate values is used to set the upper limit of summed counts for source free rows. Chip rows with summed counts higher than the limit are assumed to contain sources and are not used in identifying streaks.
Identifying Streaks (parameter msigma)
Once rows without sources have been identified, the counts in those rows are then summed along columns. Bright streaks are identified in the resulting array as much larger values among the summed background counts. Streak regions are generated as boxes which run the entire length of bright streak on the chip, and begin and end where the value of the summed counts is above the median value + msigma * the standard deviation.
Example
acis_streak_map infile="evt.fits[energy=500:7000]" fovfile=fov.fits bkgroot=output/bkg regfile=output/streakreg.fits
Generate high frequency background maps (streakmaps) for individual chips in evt.fits. Generate a single region file with regions identifying bright streaks. Use default values for parameters k1, k2, msigma.
Parameters
| name | type | ftype | def | reqd | stacks |
|---|---|---|---|---|---|
| infile | file | input | yes | no | |
| fovfile | file | input | yes | no | |
| bkgroot | file | output | yes | no | |
| regfile | file | output | yes | no | |
| nsigma | real | 6.0 | no | ||
| msigma | real | 6.0 | no | ||
| ssigma | real | -1 | no | ||
| dither | integer | 35 | no | ||
| binsize | integer | 1 | no | ||
| k1 | real | 1.0 | no | ||
| k2 | real | 2.0 | no | ||
| tmppath | string | ${ASCDS_WORK_PATH} | no | ||
| clobber | boolean | no | no | ||
| verbose | integer | 0 | no |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=no)
The ACIS observation source event file
The primary input to this tool is an event file from an ACIS observation. Streakmaps will be created for all chips listed in the event file's DETNAM header keyword.
Parameter=fovfile (file required filetype=input stacks=no)
The field of view file
The fovfile is used to identify the chip region in order to exclude zero or null value pixels off the chip.
Parameter=bkgroot (file required filetype=output stacks=no)
Root for the output streakmap filenames
The chip number and a ".fits" extension will be appended to the bkgroot for each output streakmap file.
Parameter=regfile (file required filetype=output stacks=no)
Filename of the output streak region file
A single ASCII region file will be created with boxes identifying each bright streak found in any of the output streakmap files. This parameter may be left blank if no region file is desired.
Parameter=nsigma (real not required default=6.0)
nsigma is obsolete
Parameter=msigma (real not required default=6.0)
Standard deviation multiple used in identifying non-streak columns
msigma is used to determine the width of the region surrounding bright streaks. Larger values of msigma generate thinner streak regions.
Parameter=ssigma (real not required default=-1)
Used to separate sources from a readout streak.
ssigma (streak sigma) is a multiplier used to identify where to break the streak regions so they do not include sources. The streak region stops before an assumed source and begins again after that source whenever the counts in the streak region exceed (mean counts) + ssigma * (std. dev. counts). Counts along the streak are assumed to have a Poisson distribution, so the std. dev. of counts is the square root of the mean number of counts along the streak. In calculating the mean and std. dev. of the streak counts, both the dither region and the largest 10% of counts (assumed to possibly be source counts) are excluded.
A setting of ssigma=-1 indicates that the streak region should not be broken around sources.
Parameter=dither (integer not required default=35)
Number of dither pixels
Streakmap intensities decrease linearly near chip edges. The dither parameter indicates the number of pixels in from the edge where this attenuation begins.
Parameter=binsize (integer not required default=1)
Size of source-free row bins (counts)
The width in counts of the bins of the histogram created from summed row counts and used to determine source-free rows.
Parameter=k1 (real not required default=1.0)
Source free row calculation factor k1
k1 is used to calculate one of two candidate max values for summed counts along rows, in the formula max_1 = median + k1 * sigma. The lesser of max_1 and max_2 (calculated with k2) is used as the maximum allowable value of summed counts along source free rows. Summed counts greater than this value indicate rows with sources (see the discussion in the DESCRIPTION, above).
Parameter=k2 (real not required default=2.0)
Source free row calculation factor k2
k2 is used to calculate one of two candidate max values for summed counts along rows, in the formula max_2 = k2 * mode. The lesser of max_2 and max_1 (calculated with k1) is used as the maximum allowable value of summed counts along source free rows. Summed counts greater than this value indicate rows with sources (see the discussion in the DESCRIPTION, above).
Parameter=tmppath (string not required default=${ASCDS_WORK_PATH})
Temporary file path
Location for storing the temporary files used to generate streakmaps.
Parameter=clobber (boolean not required default=no)
Specifies if an existing output file should be overwritten.
Parameter=verbose (integer not required default=0)
Specifies the level of verbosity (0-5) in displaying diagnostic messages.
For verbose > 0, an ASCII file containing the summed count histogram (used to determine the source free region) is created. This file is necessary for users who want to use k1 and k2 to create their own customized streakmap.
Changes in CIAO 4.15
The header of the new file (the regfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.
Changes in CIAO 4.16
-
Fix for compatibility issue with Numpy 1.25 and newer.
Bugs
- At verbose > 0, an additional diagonstic output file is supposed to be saved. It is not.
-
When the verbose parameter is set to a value > 0, the tool is supposed to save a counts histogram file that can be used to fine-tune the algorithm (via the k1 and k2 parameters).
The current version of tool no longer saves this file.
- Don't change binsize parameter value
-
The binsize parameter should be left at the default value of 1. If the value is greater than 1, this error will be printed:
Array index 0 (value=1915) out of allowed range 0<=index<1915
See Also
- chandra
- eventdef
- contrib
- lc_clean, lc_sigma_clip, lightcurves
- tools::acis
- acis_build_badpix, acis_check_pha_range, acis_clear_status_bits, acis_detect_afterglow, acis_find_afterglow, acis_process_events, acisreadcorr, destreak, multi_chip_gti
- tools::background
- readout_bkg
- tools::core
- dmcopy
- tools::timing
- deflare, gti_align