Skip to the navigation links
Last modified: 30 March 2018


Querying the CALDB

Many of the CIAO tools—such as acis_process_events, mkwarf, and tg_resolve_events—access the CALDB in order to obtain calibration files to apply to the data. Instead of requiring the user to specify the exact filename and path, the tools use header information and other parameter values to find the necessary files from the CALDB.

It is also possible to query the CALDB directly. There are three pieces of information that are needed:

  1. the codename

    Each file type stored in the CALDB has an associated codename, which is given in the Codenames table. For example, if you wanted to find the gain file to use for an ACIS observation, the codename would be DET_GAIN.

  2. keywords

    In order for the CALDB to find the file that matches your data set it needs to be told a number of facts about the observation, such as what detector was in the focal plane and the time of the observation. The keywords and allowed values are are listed in the Keyword specifications table.

  3. boundary conditions

    In order to find certain files—i.e. for specific codenames—it is necessary to supply extra information in the form of boundary conditions. For some tools these conditions are written in a FORTRAN-like style: e.g. cti_corr.eq.yes, which means that the file must be valid for CTI-corrected data.

The sections below descibe the methods you can use to access the CALDB:


The calquiz tool allows you to query the CALDB for a file from the command line. The parameters of the tool are used to set up the information needed by CALDB, and the matching file—if there is one—is printed to the screen and stored in the outfile parameter of the tool. For example, to find the ACIS gainmap for an observation taken on 15 December 2001:

unix% punlearn calquiz
unix% calquiz infile=none telescope=chandra instrument=acis \
      product=DET_GAIN calfile="CALDB(START=2001-12-15T00:00:00)"
unix% pget calquiz outfile

Note that in this example multiple files are returned.

The path to each file begins with the contents of the $CALDB environment variable; for this example this is /soft/ciao/CALDB. Note that specifying the instrument automatically selects the branch index file in which to search for the desired file and extension. The extension is included with the output filename and path of the requested calibration file; as shown below it refers to the AXAF_DETGAIN block in this example.

unix% dmlist /soft/ciao/CALDB/data/chandra/acis/det_gain/acisD2000-01-29gainN0005.fits blocks

Dataset: /soft/ciao/CALDB/data/chandra/acis/det_gain/acisD2000-01-29gainN0005.fits

     Block Name                          Type         Dimensions
Block    1: PRIMARY                        Null
Block    2: AXAF_DETGAIN                   Table        10 cols x 3072     rows

The calquiz help file has more examples, including using a file as input and specifying boundary conditions. Setting the verbose parameter to 1 can provide more information on what information the tool is using to query the CALDB.

Python Interface

CIAO provides a Python module, caldb4, to query the CALDB.

One way to use the module to find the ACIS-S gainmap for an observation taken on 15 December 2001 is:

chips> import caldb4
chips> cdb = caldb4.Caldb(telescope='chandra', instrume='ACIS')
chips> cdb.product = 'DET_GAIN'
chips> cdb.start = '2001-12-15T00:00:00'
chips> res =
chips> for r in res:

Block numbering

The block numbering used by the Python module follows the CFITSIO convention, where the first block is numbered 0, rather than the CIAO Data Model scheme (first block is numbered 1) used by calquiz.