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 [stowedbg] [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. Similar "stowed" particle background files exist for ACIS data.
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.
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.
Examples
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 | ||
| stowedbg | boolean | no | no | |||
| 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=stowedbg (boolean not required default=no)
Query the set of stowed ACIS background. Only available for CTI-corrected ACIS data.
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.
method=particle-rate
This setting scales the background file by the ratio of the observation to background high-energy particle count rates.
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" is set to "particle" or "weight_method=particle-rate" 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.
Changes in the scripts 4.15.1 (January 2023) release
Corrected the screen output reporting the updated BKGSCAL keywords (the file output was correct).
Changes in the scripts 4.15.0 (December 2022) release
Querying the set of stowed ACIS background files has been added with the "stowedbg" parameter. The stowed background (NXB) files will be used in lieu of blank sky background (CXB+NXB) files. This feature only supports CTI-corrected ACIS data sets.
Changes in the scripts 4.12.0 (December 2019) release
The weight_method="particle-rate" scaling has been added which is calculated using the ratio of the observed high-energy event count rate, to the blanksky high-energy event count rate using the band defined by the "bkgparams" parameter. Additionally, support for VFAINT data where "check_vf_pha=no" is set in acis_process_events added.
Changes in the scripts 4.11.3 (May 2019) release
The aimpoint chip is now calculated using the RA_PNT and DEC_PNT keywords, rather than the RA_NOM and DEC_NOM, to better support reprojected datasets.
Changes in the scripts 4.11.2 (April 2019) release
The script no-longer copies over the RA_PNT, DEC_PNT, ROLL_PNT, DY_AVG, DZ_AVG, and DTH_AVG header keywords as they are now provided by reproject_events.
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.