Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/create_bkg_map.html
AHELP for CIAO 4.16

create_bkg_map


Synopsis

Create a background map for ACIS and HRC from the event files.

Syntax

create_bkg_map  infile fovfile expmap outfile xygrid [outimgfile]
[outstreakmap] [outlowfreqmap] [tmpdir] [expcorr] [scale]
[smoothing_kernel] [clobber] [verbose]

Description

create_bkg_map is a script which creates a background map for ACIS and HRC from the event file data. These maps can be used for source detection and for detection sensitivity maps.

The script calls the CIAO tools acis_streak_map, reproject_image, and dmimgpm, as well as some of the Data Model tools (e.g. dmcopy, dmstat).

ACIS: This script uses the acis_streak_map tool to create a high frequency spatial map (streakmap) and the dmimgpm tool to create a low spatial frequency map (modified poisson mean). These maps are separately exposure map corrected and combined.

HRC-I: Only a low spatial frequency map (modified poisson mean) is needed. This script uses the dmimgpm tool to created a low spatial frequency map and exposure corrects the resultant map.


Examples

Example 1

create_bkg_map infile="evt.fits[energy=500:7000]" fovfile=fov.fits
expmap=exp.fits outfile=bkg.fits xygrid="0.5:8192.5:4,0.5:8192.5:4"

Create a background image, bkg.fits, for the 0.5-7.0 keV range of evt.fits. The field of view file is named fov.fits and the exposure map is in exp.fits.

Example 2

create_bkg_map infile=data.fits fovfile=fov.fits expmap=exp.fits
outfile=bkg.fits outimgfile=img.fits outstreakmap=streak.fits
outlowfreqmap=lf.fits xygrid="0.5:8192.5:4,0.5:8192.5:4"

Create a background image, bkg.fits, for the full energy range of data.fits. The field of view file is named fov.fits and the exposure map is in exp.fits.

Filenames are provided for outimgfile, outstreakmap, and outlowfreqmap, so the intermediate data products from this run will be written to disk and saved.


Parameters

name type ftype def reqd stacks
infile file input   yes no
fovfile file input   yes no
expmap file input   yes no
outfile file output   yes no
xygrid string     yes  
outimgfile file output   no no
outstreakmap file output   no no
outlowfreqmap file output   no no
tmpdir string   ${ASCDS_WORK_PATH} no  
expcorr boolean   yes no  
scale integer   129 no  
smoothing_kernel string   lib:tophat(2,1,3,3) no  
clobber boolean   no no  
verbose integer   0 no  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=no)

Input event file for ACIS and HRC.

The event file should be the same one that will be used in subsequent analysis, so that the same filters are applied.

Parameter=fovfile (file required filetype=input stacks=no)

Input field of view file.

The field of view file (fov1.fits) is used to identify the chip region in order to exclude zero or null value pixels off the chip.

This file has been part of the standard Chandra data distribution since ASCDSVER 6.9.0. It can also be created by running the skyfov tool.

Parameter=expmap (file required filetype=input stacks=no)

Input exposure map [cm^2 * sec].

An image in sky-coordinates, the exposure map is essentially an image of the effective area associated with each sky position as a result of the aspect motion of the telescope over the course of an observation. It accounts for the effects of dither motion which are especially important near the edges of the detector and also near bad pixels and bad columns. This file can be created with the the mkexpmap tool.

The exposure map should be normalized so that the units are [cm^2 * sec].

Parameter=outfile (file required filetype=output stacks=no)

Output background image for ACIS and HRC.

Parameter=xygrid (string required)

Exposure map grid: x0:x1:#nx,x0:x1:ny

This string specifies a region in sky (X,Y) coordinates and the resolution of the exposure map image given in the expmap parameter.

The format is "x0:x1:#nx,y0:y1:#ny", where x0, x1, y0, & y1 are real valued numbers and nx & ny are positive integers. These numbers specify a region in sky coordinates satisfying the conditions x0<=X<x1 and y0<=Y<y1, and indicate that the region is to be regridded to nx by ny pixels in the output image.

Parameter=outimgfile (file not required filetype=output default= stacks=no)

Temporary output image for ACIS and HRC.

Temporary intermediate file created from binning the event file with the factor of xygrid of the exposure map. The intermediate file is always deleted unless a filename is specified in this parameter.

Parameter=outstreakmap (file not required filetype=output default= stacks=no)

Temporary output streak map for ACIS.

Temporary intermediate file created from acis_streak_map and reproject_image. The intermediate file is always deleted unless a filename is specified in this parameter.

Parameter=outlowfreqmap (file not required filetype=output default= stacks=no)

Temporary output low frequency image for ACIS and HRC.

Temporary intermediate low frequency image created from dmimgpm. The intermediate file is always deleted unless a filename is specified in this parameter.

Parameter=tmpdir (string not required default=${ASCDS_WORK_PATH})

Directory for temporary files.

Directory for storing the intermediate files.

Parameter=expcorr (boolean not required default=yes)

Is final background exposure corrected?

Normalization is done by default. If this parameter is set to "no", the user has to correct the background with the normalized exposure map.

Parameter=scale (integer not required default=129)

Scale in pixels for dmimgpm.

This parameter value is passed to dmimgpm as 'dmimgpm xhalf=scale yhalf=scale'. The full sampling region is 2*scale + 1 in each dimension. When binning data, one needs to adjust the scale appropriately.

Parameter=smoothing_kernel (string not required default=lib:tophat(2,1,3,3))

Smoothing kernel for HRC data

This parameter is used to set the value of kernelspec when running the tool aconvolve for HRC data.

Parameter=clobber (boolean not required default=no)

Clobber output if it exists?

Parameter=verbose (integer not required default=0)

Display level (0-5)


Changes in CIAO 4.15

The header of the new file (the outfile 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.


Bugs

See Also

tools::detect
celldetect, vtpdetect, wavdetect, wrecon, wtransform
tools::gratings
tgdetect, tgidselectsrc, tgmatchsrc
tools::region
rank_roi, regphystocel, roi, splitroi