About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: December 2006

URL: http://cxc.harvard.edu/ciao3.4/quizcaldb.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 quizcaldb Context: tools

Synopsis

Find calibration files in the CALDB

Syntax

quizcaldb infile codename expr [verbose]
or
quizcaldb infile="none" mission instrument detector filter codename
date time expr [verbose]

Description

`quizcaldb' is used to query the calibration database for the file that will be used if the user specifies "CALDB" for the calibration data parameters of various tools. It works by reading the CALDB index file corresponding to the "mission" and "instrument" values specified in the call, and looking for specific matches in that index to the other parameter values specified.

Note: quizcaldb is not in general a trivial tool to use, inasmuch as specific knowledge of the structure of the CALDB is required in order to select the correct data files. Hence this command is recommended for ADVANCED USERS ONLY. For detailed information on the structure and operation of the CALDB, see the Chandra CALDB webpages.

`quizcaldb' may be used in either of two modes:

  • where an input file (FITS image, FITS table, or observation parameter file) is specified
  • where no infile is used (infile="" or infile="none")

When an infile IS used, only "codename" and "expr" must be specified separately, and the infile values override all those otherwise specified. For infile="none", all of the other parameters must be specified explicitly.

The parameters detector, filter, and expr may be ignored in a CALDB file search by specifying them as equal to "-". All other parameters require a specific allowable value or quizcaldb will fail with a diagnostic message. Allowable values are specified in the examples and links below.

Only one CALDB file may be returned. If there are multiple matching files, only the first will be returned and a warning will be printed. The matching file (if any) will be printed to the screen with the path, filename, and extension name. The same information will be stored in the parameter file ("outfile").

Example 1

quizcaldb acis_evt2.fits codename=det_gain
expr="fp_temp.eq.153.2.and.cti_corr.eq.no"

Getting the meta-data from the file "acis_evt2.fits", look up the detector gain file appropriate for the ACIS observation. Note that a L2 event file is used as infile, to specify mission, instrument, detector, date, and time. The expr parameter specifies two boundary conditions relevant to the ACIS detector gain: the focal plane temperature in Kelvin, and the status of the CTI correction. In the example given, the focal plane temperature is set to -120C (-153.2K), and the data are known not to have had the CTI corrector turned on. For CTI corrected events, you would set "cti_corr.eq.yes" in the expr.

The name of the file is printed to the screen, but can also be found in the outfile parameter of quizcaldb. This means we can get its value by saying:

set val = `pget quizcaldb outfile`

Example 2

quizcaldb cxc_obsid.par codename="DEGAP" expr="-"

Get the needed meta-data from an observation parameter file and find the degap map appropriate for the observation. For an HRC DEGAP file, no boundary conditions need to be specified, and hence expr is set to '-' so that it will be ignored in the search.

Example 3

quizcaldb none chandra HRC HRC-S - GMAP 2001-01-01 00:00:00 -

Here we do not use a file to set up the CALDB search but supply them on the command line. This query looks for the GMAP file applicable to a HRC-S observation taken starting at midnight on January 1, 2001.

Parameters

name type ftype def min max reqd
infile file input       yes
mission string         yes
instrument string         yes
detector string         yes
filter string         yes
codename string         yes
date string         yes
time string         yes
expr string         yes
outfile string output        
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input file name

The name of the file (with extension) from which the necessary meta-data should be retrieved. Can be an image, a table, or an observation parameter file (see 'ahelp dmmakepar'). If an observation parameter file is used, it must be constructed with the parameters expressed in lower case. This is the default output keyword case for dmmakepar.

If set to "NONE" or "", the necessary information will be queried. If an infile is specified, all the other parameters (except for "codename" and "expr") are overridden and the meta-data is taken from the file.

Parameter=mission (string required)

Name of mission

The mission is "chandra", for all CXC CALDB queries.

Parameter=instrument (string required)

Name of instrument

"ACIS" and "HRC" are the two instrument names valid for Chandra data.

Parameter=detector (string required)

Name of detector, use "-" if not applicable.

ACIS-I, ACIS-S, HRC-I, or HRC-S. Use of the ACIS DETNAM header keyword (e.g. ACIS-012367) is also acceptable.

Parameter=filter (string required)

Name of filter, use "-" if not applicable.

A filter for which the chosen dataset needs to be valid.

Parameter=codename (string required)

Data product code name.

The code name of the calibration product you want. `Codename' specifies the type of calibration data your task requires. A list of the most commonly used ACIS and HRC codenames is given below. For a full list of all the codenames, see the Table 3 of "About the Chandra CALDB -- Basic Structure." The FITS header keyword CCNM0001 stores the codename value in each CALDB file, and that value is what goes into the index.

Instrument codename description
ACIS GRADE Detector grade table
ACIS BADPIX Detector bad pixel list
ACIS DET_GAIN Detector gain table
ACIS OSIP OSIP table (grating obs only)
HRC BADPIX Bad pixel list
HRC GMAP Detector gain correction map (image)
HRC DEGAP Degap correction table
ACIS or HRC 2D_PSF PSF library hypercube file

Parameter=date (string required)

Date for which the calibration product is valid.

Requires "yyyy-mm-dd" format. Entering the value "now" uses the current system date.

Parameter=time (string required)

Time for which the calibration product is valid.

Requires "HH:MM:SS" format. Entering the value "now" uses the current system time.

Parameter=expr (string required)

Query expression to further refine search. Use "-" if not applicable.

Some calibration products are futher indexed by additional "boundary" conditions, e.g. an angle or energy range. These expressions must be added via this parameter, if it is required in order to distinguish between files of the same codename and instrument/detector specifications. For a list of required boundary conditions for a given instrument/codename, see the CALDB Required Boundary Conditions table.

The expression can use the operators ".eq." and ".and." to define the boundary conditions. For example:

saosac_az.eq.-0.364900.and.saosac_el.eq.-0.471500

gives limits in selecting a PSF library file.

Parameter=outfile (string filetype=output)

The selected file with path and extension appended.

This field is populated after the tool has finished running. The information is also printed to the screen.

Parameter=verbose (integer default=0 min=0 max=5)

Amount of tool output.

CHANGES IN CIAO 3.0

Exit status on error

The exit status value of quizcaldb is now set to a non-zero value when the tool is unable to locate a file.

Querying the CALDB from S-Lang

The caldb module was added in CIAO 3.0 to allow CALDB queries to be called from S-Lang.

Bugs

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

See Also

calibration
ardlib, caldb
modules
caldb, pixlib
Hardcopy (PDF): A4 | Letter
Last modified: December 2006



The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.