Synopsis
Find the matching ACIS "blank-sky" dataset for an observation
Syntax
acis_bkgrnd_lookup infile [outfile] [blname] [verbose]
Description
The acis_bkgrnd_lookup script is used to find the ACIS background (i.e. "blank sky") dataset from the CALDB that matches your observation. It is suggested that you the read the following before using the background files in your analysis:
- Maxim Markevitch's ACIS background discussion
- The ACIS Background Subtraction thread
The results of the CALDB search are written to the outfile parameter as well as being written to the screen, making them accessible by calling
pget acis_bkgrnd_lookup outfile
.
Output
If more than one file is found then they are listed on the screen one to a line and written to the parameter file as a comma-separated list (i.e. a stack). This will be the case, for instance, if the input file contains data from more than one CCD. See "ahelp stack" for more information on handling stacks.
Examples
Example 1
unix% acis_bkgrnd_lookup evt2.fits unix% set bfile = `pget acis_bkgrnd_lookup outfile`
The script finds the aimpoint, focal plane temperature, and details on the CTI correction from information in the header of the file and uses the ccd_id column of the event file to select the chips which contain data.
The matching file(s) are printed to the screen and stored in the outfile parameter of the script. We use the pget command to get this value from the parameter file.
Example 2
unix% acis_bkgrnd_lookup "evt2.fits[sky=region(source.reg)]"
The input file can include any Data Model expression (see "ahelp dmsyntax") as long as the resulting file is still a table with a ccd_id column. Here we use a spatial filter to filter the events file: the resulting background file(s) will be chosen to match only the CCDs that cover the region source.reg.
Example 3
unix% acis_bkgrnd_lookup img.fits
In this case the input file is an image, rather than an event file. The list of CCDs to use in the search is taken from the ccd_id filter recorded in the data subspace of the file; this can be seen by using the "subspace" option of dmlist, such as in this example
unix% dmlist img.fits subspace | grep ccd_id 2 ccd_id Int2 3:3 2 ccd_id Int2 2:2 2 ccd_id Int2 1:1 2 ccd_id Int2 0:0
See "ahelp subspace" for more information on the subspace information recorded in files.
Parameters
| name | type | def | min | max | reqd | stacks |
|---|---|---|---|---|---|---|
| infile | file | yes | ||||
| outfile | file | yes | ||||
| blname | string | none | ||||
| verbose | integer | 0 | 0 | 5 |
Detailed Parameter Descriptions
Parameter=infile (file required)
The file for which you want background files
The file must contain a CTI_APP keyword.
If the input file is an image then the ccd_id subspace filter is used to determine which ACIS chips should be searched for. If the input file is a table then a combination of the ccd_id subspace and ccd_id column are used to determine which chips to use.
Parameter=outfile (file stacks=yes)
ACIS background file(s) to use
This parameter will be set to the name(s) of the ACIS background files selected from the CALDB to match your observation. The file names include the full path. If more than one file is selected then they will be stored as a comma-separated stack.
Parameter=blname (string default=none)
What block identifier should be added to the filename?
This parameter determines whether any block identifier should be included in the filename and, if so, what form should the identifier be in. The allowed values are:
blname=none
No identifier is added; this is the default value. The output will look something like
acis1sD2000-01-29bkgrnd_ctiN0005.fits
blname=name
Add the name of the block to the file, so the output will look something like
acis1sD2000-01-29bkgrnd_ctiN0005.fits[EVENTS]
blname=number
Add the number of the block to the file using the DataModel numbering scheme ([1] refers to the first block). The output will look something like
acis1sD2000-01-29bkgrnd_ctiN0005.fits[2]
blname=cfitsio
Add the number of the block to the file using the CFITSIO numbering scheme ([0] refers to the first block). The output will look something like
acis1sD2000-01-29bkgrnd_ctiN0005.fits[1]
Parameter=verbose (integer default=0 min=0 max=5)
Debug level (0=no debug information)
In most cases the default verbose level (of 0) is the correct value to use. Higher values may prove useful when trying to track down problems with the script. Two useful values are:
Verbose=2
Setting verbose=2 will display the version of the script being used together with basic information derived from the input file. It also lists the equivalent calquiz call (or calls) that you would need to make to select the files.
Verbose=5
Setting verbose=5 lists the CALDB lookup that the script is using to select the background file.
Changes in the CIAO scrips 4.9.1 (December 2016) Release
The code has been updated for changes in CIAO in this release.
Changes in the CIAO 4.8.1 (December 2015) Release
The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.
Changes in the CIAO 4.6.1 (December 2013) Release
It is now possible to set infile to an image which contains data from multiple ACIS chips (bug fix).
About Contributed Software
Downloading the script
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.
Downloading the CALDB background files
The ACIS background files are packaged separately from the main CALDB download file and are available from the CALDB download page.
Bugs
There are no known bugs for this tool.
See Also
- calibration
- ardlib
- psf
- psf
- tools
- acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, rmfimg, sky2tdet, specextract