Synopsis
Create a scaled background events file by using the scale factor calculated by and sampling the blanksky background file generated by the "blanksky" script for an observation.
Syntax
blanksky_sample infile bkgfile bkgout [psf_bkg_out] [regionfile] [fill_out] [reproject] [asolfile] [tmpdir] [random] [clobber] [verbose]
Description
This script will create a scaled background events file given a customized blanksky background events file with the BKGSCALE/BKGSCALn header keyword set.
With a given blanksky background, the "blanksky_sample" script estimates the number of background photons needed to match the observation based on the the background scaling factor(s) calculated for that observation by the "blanksky" script. In order to select a random subset of blanksky events -- which are listed in sky x and y coordinates -- on a per-chip basis, a random number between 0 and 1/BKGSCALn is assigned to each event, and events with a random number less than or equal to 1 are selected.
A random time between the TSTART and and TSTOP are then assigned to each selected event and then if necessary, column data types are converted to match those used in the reference input file.
Optionally, the sampled background and the input reference file can be combined by setting the "psf_bkg_out" parameter. Another optional use case is to "fill in the hole" if the "regionfile" and "fill_out" parameters are set. The regions are then used to exclude the events in the input reference file and then filling in the regions with sampled background events output to the "fill_out" file.
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_sample infile=evt2.fits bkgfile=bsky_particle.fits bkgout=bkg_sample.fits
This is the case that you'd be most interested in, since the bkg_sample.fits file will be the background file that you'd feed into specextract. The "infile" is the reference events file and "bkgfile" is the background file generated by blanksky containing the background scaling header keywords.
Example 2
unix% blanksky_sample infile=marx_evt2.fits bkgfile=bsky_particle.fits bkgout=bkg_sample.fits psf_bkg_out=marx+bsky_evt.fits
Another use case is for combining the scaled background events with an events file generated out of a PSF simulation. The "psf_bkg_out" parameter is the results from combining the "infile" and "bkgout".
Example 3
unix% blanksky_sample infile=evt2.fits bkgfile=bsky_particle.fits bkgout=bkg_sample.fits regionfile=src.reg fill_out=filled_evt.fits
The fill-in-the-hole" use case, the "regionfile" parameter and "fill_out" parameter are of interest, where the filled_evt.fits file is the events file that excludes the sources from the "infile" defined by the "regionfile" and replaces them with the sampled background events in "bkg_out" from the corresponding part of the detector.
Parameters
| name | type | ftype | def | min | reqd | stacks |
|---|---|---|---|---|---|---|
| infile | file | input | yes | no | ||
| bkgfile | file | input | yes | no | ||
| bkgout | file | output | yes | no | ||
| psf_bkg_out | file | output | no | no | ||
| regionfile | file | input | no | no | ||
| fill_out | file | output | no | no | ||
| reproject | boolean | no | no | |||
| asolfile | file | input | no | yes | ||
| tmpdir | string | ${ASCDS_WORK_PATH} | ||||
| random | integer | 0 | 0 | |||
| clobber | boolean | no | no | |||
| verbose | integer | 0 |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=no)
The reference event file used to generate a tailored blanksky background.
This reference file is typically the observed events file used with the 'blanksky' script to generate the unscaled background events file. Alternatively, it may be a PSF event file from a ray trace simulation that is based on the observed events file used to generate the background events file.
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=bkgout (file required filetype=output stacks=no)
Output sampled blanksky background events file.
Parameter=psf_bkg_out (file not required filetype=output stacks=no)
Output events file combining the events defined by the "infile" and "bkgout" parameters.
Parameter=regionfile (file not required filetype=input stacks=no)
CIAO-formatted region file used alongside the "fill_out" parameter of the region(s) in the "infile" to exclude events and be replaced with background events.
Parameter=fill_out (file not required filetype=output stacks=no)
Output event file with "infile" events in the regions defined by "regionfile" and replaced with background events.
Parameter=reproject (boolean not required default=no)
Reproject background events to match the infile coordinates.
Run reproject_events with 'asolfile' on 'bkgfile' to match the coordinates of 'infile'. Only set to 'yes' if the blanksky backgound file has not been reprojected.
Parameter=asolfile (file not required filetype=input stacks=yes)
Input aspect solution for events reprojection.
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 - cannot be used here.
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 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 describe d in "Absol ute 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).
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.
Changes in the scipts 4.14.0 (December 2021) release
Incorporated deadtime correction from reference observation to better bound the time range the randomly sampled time values assigned to the blanksky events.