Skip to the navigation links
Last modified: August 2010

AHELP for CIAO 4.2


Context: tools


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.

Example 1

acis_bkgrnd_lookup evt2.fits

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.

Example 2

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

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

See "ahelp subspace" for more information on the subspace information recored 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 an image then a combination of the ccd_id subspace and ccd_id column values - if present - are used instead.

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.


This release contains no user-visible changes.


Change to screen output when verbose is not 0

The screen output when verbose is not 0 has changed slightly.

Change to the outfile parameter

The "output" parameter of the tool, namely outfile, has been changed to have a paramter type of "l" rather than "h". This should not change how the tool behaves, but plist will now display this parameter without a surrounding pair of brackets.

Version numbering

The version scheme has changed to a date-based system.


CALDB changes

The tool has been updated to use the new Calibration Database, which means that:

  • The infile parameter MUST contain a CTI_APP keyword. The tool will abort if this condition is not met.
  • The outfile parameter now includes the block number to identify the relevant block (e.g. "[2]") whereas no block identifier was previously used.

Image support

The input file can now be an image, as long as it contains all the necessary header information. The set of ACIS ccds is taken from the ccd_id filter recorded in the data subspace of the image.

New parameter: blname

As of the CIAO 4.1 - 1.1 release, the tool now includes the blname parameter which determines whether the block identifier of the output file is included in the output, and what form this identifier should take (e.g. the block name, the DataModel number, or the CFITSIO number).

The default value for the blname parameter is "none". In the initial release of the tool (CIAO 4.1 - 1.0), the parameter was not included but acted as if set at blname="number". This was a departure from CIAO 4.0 and earlier versions, which acted as if blname="none".


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 the installation instructions page for help on installing the package.

Downloading the CALDB background files

Since CALDB 3.0.0, the ACIS background files have been moved out of the main CALDB download file. They are now packaged separately, and are available from the CALDB download page.


See the bugs page for this script on the CIAO website for an up-to-date listing of known bugs.

See Also

acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, add_grating_spectra, asphist, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, specextract

Last modified: August 2010