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:

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.

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.

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. These conditionas are written in a FORTRAN-like style: e.g. cti_corr.eq.yes means that the file must be valid for CTI-corrected data.

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

• from S-Lang;
• using the FTOOLS package.

S-Lang Interface

The "caldb" module is a S-Lang interface to the CALDB library.

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

chips> import("caldb")
chips> cal = calCreateInfo()
chips> calSetTelescope( cal, "Chandra" )
chips> calSetInstrument( cal, "ACIS" )
chips> calSetData( cal, "DET_GAIN" )
chips> calSetDate( cal, "2001-12-15T00:00:00" )
chips> calFindFile( cal )
/soft/ciao/CALDB/data/chandra/acis/bcf/gain/acisD2000-08-12gainN0003.fits[AXAF_DETGAIN]

FTOOLS

The FTOOLS commands for the CALDB can be seen using the command "fhelp caltools". The commands of interest for a user include quzcif and caldbinfo.

In order to use the CALDB, you must have the environment variables $CALDB, $CALDBALIAS, and $CALDBCONFIG defined. If your copy of the CALDB exists under /data/CALDB, then sourcing the script /data/CALDB/software/tools/caldbinit.unix will set up those environment variables and enable you to access files with the FTOOL quzcif.

quzcif is the basic routine used for selecting a file from the CALDB index. You can learn about the full form of this command, including how to invoke a bounded coordinate value, by using the fhelp quzcif command. The general form for the command is:

unix% quzcif telescop instrume detnam filter ccname yyyy-mm-dd hh:mm:ss boundaries

To omit searching on a given element, substitute a dash (-). For example, to get the gain file for an observation taken on Sept 30, 1999, you would enter:

unix% quzcif chandra acis - - det_gain 1999-09-30 00:00:00 -

/data/CALDB/data/chandra/acis/bcf/gain/acisD1999-09-16gainN0004.fits 1

The tool returns the file it located which matches the requested conditions, as well as the extension number (1) of the dataset.