blanksky_image

Context: Tools::Background

Synopsis

Create scaled background and background-subtracted images given an observation-specific blanksky background file and a reference image.

Syntax

blanksky_image  bkgfile outroot imgfile [tmpdir] [clobber] [verbose]

Description

This script will create a scaled background image and background-subtracted image, given a customized blanksky background events file and reference FITS image.

The needed ACIS blanksky background files are selected for the observation and then processed as outlined in the "Analysing the ACIS Background with the 'Blank-Sky' Files" analysis thread and HRC-I observations, processing the particle background files are described in The HRC-I Background Event Files; these threads are automated by the "blanksky" script. Multi-CCD observations will be scaled on a per chip basis, using the chip-appropriate BKGSCALn header keywords to produce the background image. Energy and PI filters applied to the reference image file -- for ACIS and HRC-I observations, respectively -- will also be applied to the background image.

Examples

Example 1

unix% blanksky_image bkgfile=bsky.fits outroot=obs imgfile=src.img

For a given blanksky background event file, "bsky.fits" and a FITS counts image of an observation, "src.img", the scaled background and background-subtracted images "obs_particle_bgnd.img" and "obs_particle_bkgsub.img", or "obs_time_bgnd.img" and "obs_time_bkgsub.img" will be created, dependent on the BKGMETH header keyword of the blanksky background events file. If the reference image was created with fluximage, then the output images will use the same binning and sky range as the reference image.

Example 2

unix% blanksky_image bkgfile=bsky.fits outroot=obs
imgfile="evt.fits[bin sky=32][energy=500:7000]"

The same as above, but the reference image is a binned and energy filtered virtual image.

Parameters

name	type	ftype	def	reqd	stacks
bkgfile	file	input		yes	no
outroot	file	output		yes
imgfile	file	input		yes	no
tmpdir	string		${ASCDS_WORK_PATH}
clobber	boolean		no	no
verbose	integer		0

Detailed Parameter Descriptions

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

Input blanksky background event file.

The modified and reprojected blanksky background event file; the output from the "blanksky" script.

Parameter=outroot (file required filetype=output)

Root name for the output files.

A string for the prefix in all filenames created by blanksky_image, including specified directory.

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

Reference FITS image file.

The image file that the background image derives its size grid, energy range, and is subtracted from to create a background-subtracted image.

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

Directory for temporary files.

Directory for storing temporary files that require further processing before becoming useful. If the directory does not exist then it will be created for use by the script, and then deleted.

Parameter=clobber (boolean not required default=no)

Specifies if an existing output file should be overwritten.

Parameter=verbose (integer default=0)

Specifies the level of verbosity (0-5) in displaying diagnostic messages.

Determining background scaling factor for an observation

The background scaling method and factor are stored in the BKGMETH and BKGSCALE/BKGSCALn header keywords in the tailored blanksky background file, each BKGSCALn value corresponds to a specific chip. These scaling values may be used to weigh FITS image files, on a per chip basis for an observation.

When scaling by time, the ratio of the observation to blanksky files' LIVTIMEn keywords are calculated.

The basis for scaling by the high-energy particle background is described in "Absolute Measurement of the Unresolved Cosmic X-Ray Background in the 0.5-8 keV Band with Chandra" (Hickox & Markevitch, ApJ 645 95). The calculation of the factors are done by taking the ratio of the counts in the observation to the blanksky background for each chip in a defined hard energy band (the "bkgparams" parameter in the "blanksky" script).

Changes in the scripts 4.11.2 (April 2019) release

The script has been updated to recognize any CCD filter that has been applied to the input file.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.