Synopsis
Provides a Python interface to the CXC Calibration Database library: CALDB4
Syntax
>>> from caldb4 import Caldb
Description
The Calibration Database (CALDB) is the repository of all the calibration files needed to analyze Chandra data. The `caldb4` Python module provides a Python interface to the Chandra CALDB. The Chandra CALDB extends the functionality of the HEASARC CALDB and requires its own library interface to make use of the extended features.
The `caldb4` module provides a `Caldb()` object to access the CALDB. The design of this object is not typical or standard for Python objects in that it uses attributes rather than methods to set and get information. This will be illustrated in the examples below.
Caldb() object
The semantics of the CALDB requires three primary inputs: Telescope, Instrument, and Calibration Data Product. The secondary requirement is that all calibration products are valid for a specific time range. Finally, there are optional tertiary conditions (boundary conditions in the CALDB lexicon); they do not need to be specified. However, if they are, then the conditions must be satisfied. The `Caldb()` constructor has the following signature:
class Caldb(caldb4.caldblib.CDBlib, caldb4.calattr.Calattr) | Caldb(telescope='chandra', instrume='default', product='', infile='')
Typical usage will be to either specify the telescope, instrument (`instrume`), and product
>>> my_caldb = Caldb("chandra", "acis", "det_gain")
or to specify the product and provide an input file (`infile`).
>>> my_caldb = Caldb(product="t_gain", infile="acis_evt.fits")
In this case, the `infile` must be a FITS file (with optional extension name/qualifiers), and the object will extract the information it needs to build its search from the file's header keywords.
'product' attribute
The `product` attribute of the `Caldb()` object provides access to the calibration data product code name.
>>> my_caldb = Caldb("chandra", "acis", "det_gain")
>>> my_caldb.product
'det_gain'
It is also possible to set the data product code name.
>>> my_caldb.product = "t_gain" >>> my_caldb.product 't_gain'
However, this may not work as expected since the possible boundary conditions are different for different data products.
'start' and 'stop'
The `start` and `stop` attributes provide the time range to search for. Typically, this will be the time range of the observation. These should be in FITS/Y2K YYYY-MM-DDTHH:MM:SS format. For Chandra, the DATE-OBS keyword value should be used for the `start` value, and the DATE-END keyword value should be used for the `stop` value.
>>> my_caldb.start='2000-01-29T20:00:00' >>> my_caldb.stop='2000-11-28'
'allneeded'
One enhancement in the CXC CALDB library is that users can query the database for the list of optional boundary conditions for a particular data product. This means that tools can adapt to changes in the CALDB without making code changes. The list of optional parameters is available using the `allneeded` attribute.
>>> from caldb4 import Caldb
>>> my_caldb = Caldb("chandra", "acis", "det_gain")
>>> my_caldb.start='2000-01-29T20:00:00'
>>> my_caldb.stop='2000-11-28'
>>> my_caldb.allneeded
[('GRATING', ''), ('GRATTYPE', ''), ('CTI_APP', ''), ('FP_TEMP', 'K'), ('OBS_MODE', '')]
A list of tuples is returned. The first element in the tuple is the keyword name to use to lookup the boundary condition. The second element is the units (if any) of the value. Note: The module does not perform any unit conversions; it simply checks that the units match **during the search**.
The attribute name is deceiving, as these are not **needed** (as in, must have or required to complete the query), but are only needed to fully qualify the search. One way to explain it is that by omitting these values, a search may return multiple matches; however, by including them, it may filter the search results. This is an important point, since these optional criteria only act to filter the search results; they will never expand them to include more results.
To specify a value for one of the boundary conditions, simply set the object's attribute (case insensitive).
>>> my_caldb.OBS_MODE = "POINTING"
>>> my_caldb.allneeded
[('GRATING', ''), ('GRATTYPE', ''), ('CTI_APP', ''), ('FP_TEMP', 'K')]
If, for some reason, you need to remove a boundary condition, you can delete the attribute.
>>> del my_caldb.OBS_MODE
>>> my_caldb.allneeded
[('GRATING', ''), ('GRATTYPE', ''), ('CTI_APP', ''), ('FP_TEMP', 'K'), ('OBS_MODE', '')]
'search'
Accessing the `search` attribute triggers the actual search of the CALDB. The `search` attribute returns a list of strings with the file name and the CFITSIO block number in square brackets.
>>> my_caldb = Caldb("chandra", "acis", "det_gain")
>>> my_caldb.start='2000-01-29T20:00:00'
>>> my_caldb.stop='2000-11-28'
>>> my_caldb.search
['/soft/ciao-4.18/CALDB/data/chandra/acis/det_gain/acisD2000-01-29gain_ctiN0008.fits[1]']
Note: The CXC Datamodel and CFITSIO use different block numbering sequences; CXC starts at 1, CFITSIO starts at 0.
It is important to note that if the `infile` is specified in the constructor, then the values are not taken from the header until the `search` attribute is accessed. For example:
>>> my_caldb = Caldb(product="t_gain", infile="/export/img.fits")
>>> my_caldb.allneeded
[('GRATING', ''), ('GRATTYPE', ''), ('CTI_APP', ''), ('FP_TEMP', 'K'),
('OBS_MODE', ''), ('start', ''), ('stop', '')]
>>> my_caldb.search
['/soft/ciao_from_source/ciao-4.18/CALDB/data/chandra/acis/t_gain/acisD2000-01-29t_gainN0008.fits[1]']
>>> my_caldb.allneeded
[('GRATTYPE', '')]
Before the `search` attribute is accessed, the list of "needed" parameters is long and includes things like the `start` and `stop` times. After the `search` attribute is accessed, the list of remaining "needed" parameters is short. Unfortunately, users cannot access the parameter values that were loaded from the input file.
>>> print(my_caldb.OBS_MODE) None
Chandra CALDB vs. HEASARC CALDB
There are two main differences between the Chandra CALDB and the HEASARC CALDB: the ability to query for boundary condition keywords and optional fidelity.
Boundary Condition Keywords
As illustrated above, the Chandra CALDB allows programs to query the CALDB to obtain a list of the optional boundary conditions that can be applied to a given data product. This allows the CALDB to evolve without having to update programs that would need to hard-code parameter/keyword values.
Fidelity
The standard HEASARC CALDB allows users to search for calibration quality: 0 is good, and 1 to 5 are varying degrees of "bad". Only integer values of quality are allowed. The Chandra CALDB allows for an optional fidelity, which provides a filter on the goodness of calibration files. Fidelity=0 files are the lowest/poorest, and values greater than 0 are increasingly better. Values are allowed to be real, floating-point values (e.g., 1.5), and have no prescribed upper limit. Quality and fidelity are set as attributes.
>>> my_caldb.quality = 0 >>> my_caldb.fidelity = "0-999"
Calibration algorithms
The CALDB4 library only provides access to the calibration files. The actual calibration algorithms are encoded in the various CIAO tools and libraries. For example, the algorithm to convert from observed ACIS pulse height (PHA) to energy (and eventually PI) is coded in the `acis_process_events` tool and requires multiple calibration files: detector gain, time-dependent gain, CTI corrections, grades, split threshold, etc.
There are few use cases for general users to need access to the CALDB files.
CALDB version
The CALDB itself does not provide any version mechanism. The Chandra CALDB versions are manually managed by the CXC CALDB manager. The Chandra CALDB version is stored in the `$CALDB/docs/chandra/caldb_version` directory:
$ tail -1 $CALDB/docs/chandra/caldb_version/caldb_version.txt 4.12.3 DS10.14.3 CIAO4.18 2025-12-16T16:00:00 2025-12-15T16:00:00 2025-12-16T16:00:00 N/A caldbN0469.indx caldbN0408.indx caldbN0400.indx caldbN0449.indx caldbN0418.indx caldbN0418.indx caldbN0400.indx
It is also accessible using the CIAO contributed scripts `caldb` module:
>>> from ciao_contrib.caldb import * >>> print(get_caldb_installed_version()) 4.12.3
Bugs
See the bugs page for the region library on the CIAO website for an up-to-date listing of known bugs.
Refer to the CIAO bug pages for an up-to-date listing of known issues.