Last modified: December 2022

AHELP for CIAO 4.16



Find the matching ACIS "blank-sky" dataset for an observation


acis_bkgrnd_lookup  infile [outfile] [blname] [verbose]


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:

- ACIS Background Memos page

- 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



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.


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.


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:


No identifier is added; this is the default value. The output will look something like


Add the name of the block to the file, so the output will look something like


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


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


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:


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.


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.


There are no known bugs for this tool.

See Also

asphist, dither_region
hrc_bkgrnd_lookup, readout_bkg
combine_grating_spectra, combine_spectra, specextract
acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg