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 three methods you can use to access the CALDB:

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

quizcaldb

The quizcaldb 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% quizcaldb infile="none" mission="chandra" instrument="ACIS" \
      detector="-" date="2001-12-15" time="00:00:00" filter="-" \
      codename="DET_GAIN" expr="-"

/soft/ciao/CALDB/data/chandra/acis/bcf/gain/acisD2000-08-12gainN0003.fits[AXAF_DETGAIN]
unix% pget quizcaldb outfile
/soft/ciao/CALDB/data/chandra/acis/bcf/gain/acisD2000-08-12gainN0003.fits[AXAF_DETGAIN]

The path to the 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 (AXAF_DETGAIN in this example) is included with the output filename and path of the requested calibration file.

The quizcaldb help file has more examples, including using a file as input and specifying boundary conditions.

S-Lang Interface

The "caldb" module is a S-Lang interface to the CALDB library. The caldb ahelp page describes how the module can be used, and there are also ahelp pages for the individual functions in the module.

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.