Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: February 2017

URL: http://cxc.harvard.edu/ciao/ahelp/blanksky.html
AHELP for CIAO 4.9

blanksky

Context: tools

Synopsis

Tailor an unscaled blanksky background file to be compatible with a given events file; combining and reprojecting the necessary background files from the CalDB.

Syntax

blanksky  evtfile outfile asolfile [weight_method] [bkgparams] [tmpdir]
[random] [clobber] [verbose]

Description

This script will customize a blanksky background file for the input event file, using the instrument-specific background files in the CalDB. By default, due to size, these background files are not included as part of the standard CalDB installation and must be specifically installed.

The HRC-I background files are generated from exposures when the detector is active and not exposed to the telescope's optics, manifesting itself as a measure of the particle background. While similar "stowed" particle background files exist for ACIS data, they are not utilized by this script.

The ACIS blanksky background files used by this script are generated by co-adding sets of observations, taken over the course of the mission, of relatively empty fields, with the conditions of high galactic latitude (|b| > 20 deg) and low, soft X-ray emission in the ROSAT All Sky Survey maps (sum of R4 + R5 bands < 200). All observations were performed using the entire CCD in standard timing mode with no gratings inserted. Again, this script does not make use of any ACIS "stowed" background files.

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. Multi-CCD observations will combine the background files for the corresponding CCDs before reprojecting the events to match the coordinates of the observation.

Example 1

unix% blanksky evtfile=evt.fits outfile=bkg_evt.fits

For a given event file, "evt.fits", the appropriate blanksky background files will be selected from the CalDB, combined, and projected to the its matching coordinates as "bkg_evt.fits". The script will attempt to find the required aspect solution file from the events file header.

Example 2

unix% blanksky evtfile=evt.fits outfile=bkg_evt.fits asolfile=asol.fits

The same as above, except the aspect solution file is explicitly specified.

Parameters

name type ftype def min reqd stacks
evtfile file input     yes no
outfile file output     yes  
asolfile file input     yes yes
weight_method string   particle      
bkgparams string   default      
tmpdir string   ${ASCDS_WORK_PATH}      
random integer   0 0    
clobber boolean   no   no  
verbose integer   0      

Detailed Parameter Descriptions

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

Input event file.

An events file that the blanksky background will be tailored to match.

Parameter=outfile (file required filetype=output)

Output file

Output name of the events file-specific blanksky background file.

Parameter=asolfile (file required filetype=input stacks=yes)

Input aspect solutions.

If the value is empty then the ASOLFILE keyword from the events file will be used to find the files to use. An aspect solution is required for the script to run.

The aspect solution files have names like pcadf*_asol1.fits and are included in the output directory of the chandra_repro script. To explicitly specify the asol files use the stack syntax (e.g. a comma, or space, separated string or an external file as described in "ahelp stack" for more information). So to use asol1.fits, asol2.fits, and asol3.fits you could say

asolfile="asol1.fits,asol2.fits,asol3.fits"

or

asolfile="asol1.fits asol2.fits asol3.fits"

or

asolfile=@asol.lis

where asol.lis contains the names of each file, one per line. The files do not have to be given in time order.

Since there may be multiple asol files for an observation there may be more entries in this parameter than there are in the infiles parameter.

Aspect histograms - the output of the asphist tool - can not be used here.

Parameter=weight_method (string default=particle)

Method to calculate the background scaling factor.

This parameter determines the method used to calculate the background scaling factor for a given observation.

method=particle

This option scales the background by the ratio of the counts in the range determined by the bkgparams parameter, rather than by exposure time.

method=time

This setting scales the background file by the ratio of the observation to background exposure times.

Header keywords

The scaling method and factor are added to the tailored blanksky background file using the BKGMETH and BKGSCALE keywords, respectively.

Parameter=bkgparams (string default=default)

Optional argument for calculating the particle background scaling factor.

This parameter is only used if "weight_method=particle" and otherwise ignored. The default is [pi=300:500] for HRC and [energy=9000:12000] for ACIS.

The parameter is taken to be a Data Model filter to apply to both the observation and the particle background file, and is expected to be of the form "[energy=lo:hi]" or "[pi=lo:hi]". It is used to select a subset of the observation that represents the particle background -- i.e. it is not strongly "contaminated" by cosmic emission -- but is close enough (in PI) to the source emission to minimise differences in the spectral shape of the particle emission between the observation and that seen in the background observations or use the high-energy event data (above 10 keV) to see how the particle background normalization differs between your observation and the background file.

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=random (integer default=0 min=0)

Random seed for randomization.

The random parameter is sent to reproject_events when processing the ACIS blanksky and HRC-I particle background files to match the observation. A value of 0 uses the system time to seed the random number generator.

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 weight FITS image files, on a per chip basis, to be used with 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 the energy band defined by the "bkgparams" parameter.

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 - such as how to ensure that the parameter file is available.


Last modified: February 2017
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.