      Generate high frequency background maps (streakmaps) which identify
      ACIS streaks caused when bright source photons are applied to the
      wrong pixel  during readout.

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.

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.

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.

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.

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.

          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.

          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.

          Root for the output streakmap filenames

The chip number and a ".fits" extension will be appended to the bkgroot for each output streakmap file.

          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.

          nsigma is obsolete

          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.

          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.

          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.

          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.

         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).

         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).

          Temporary file path

Location for storing the temporary files used to generate streakmaps.

          Specifies if an existing output file should be overwritten.

          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.

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

December 2022