/ ciao4.15 / ahelp / acis_streak_map.html

Jump to: Description · Example · Parameters · Changes in CIAO 4.15 · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

acis_streak_map

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.

The script now writes proper history records

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