quzcif2 HEADAS help file

NAME

QUZCIF2 -- Returns the name and location of calibration files

USAGE

quzcif2 mission instrument detector filter codename date time expr

DESCRIPTION

This task is a command-line interface to the Calibration Database access software. It writes to the standard output datasets in the Database which meet the selection criteria as specified by the input parameters. The number of datasets returned and displayed to standard output can be restricted using the MAXRET parameter.

For each dataset which satisifies the specified criteria, the filename field (with the complete directory path) and the extension number is printed. If the user is accessing the HEASARC CALDB using remote access, the full URL of the files is returned.

Any datasets which are stored off-line (on magnetic tapes, for example) will be displayed with the word 'OFFLINE' and the off-line media will appear before the filename and extension number.

Datasets which are located on the HEASARC server can be accessed if the user's CALDB environment variable is set to https://heasarc.gsfc.nasa.gov/FTP/caldb and can be optionally downloaded to the user's current working directory (if the retrieve parameter is set to "yes").

If no datasets are found which satisfy the specified criteria, then the message "No datasets found matching selection criteria" is displayed, as long as the chatter parameter is greater than 0.

Before using this task, the 'CALDB' and 'CALDBCONFIG' environment variables (logicals) must be set. See the Caldb Installation Guide for details.

PARAMETERS

mission [string]

The name of the mission for which selected datasets should be valid (for example "rosat", "asca", "halosat"). The mission parameter is matched against the TELESCOP keyword in the calibration file extensions.

instrument [string]

The name of the instrument for which the selected datasets should be valid. The instrument value specified will be matched against the value of the INSTRUME keywords in the calibration file extensions.

detector [string]

The name of the detector for which the selected datasets should be valid. If a "-" character is input, this parameter will not be used in the selection process. The detector parameter is compared against the DETNAM keyword in the calibration file extensions

filter [string]

The name of the filter for which the selected datasets should be valid. If a "-" character is input, this parameter will not be used in the selection process. The filter parameter is compared against the FILTER keyword in the calibration file extensions

codename [string]

The OGIP codename for the requested data. The value input for this parameter corresponds to the CCNM0001, CCNM0002, ... keyword values found in all CALDB calibration files. Also, the NASA OGIP Memo CAL/GEN/92-011 contains a list of valid codenames and their meanings. This memo can be obtained from https://heasarc.gsfc.nasa.gov/FTP/caldb/docs/memos/cal_gen_92_011/cal_gen_92_011.html.

date [string]

The date portion of the time for which the selected datasets should be valid, in UT. The date and time specified by the user will be added together and converted to MJD, and compared to the MJDs of the validity start date/time of the files in the CALDB. The latest calibration datasets which match other specifications and which have a validity start date/time less than or equal to the specified date and time are returned. The date should be specified as a value in yyyy-mm-dd format, with days and months given as 2-digit integers with leading zeroes. Two special values are allowed:

If the date is specified as "now", the current system date is used for the selection.
If the date is given as a single dash ("-"), then the date check is bypassed (and the value of time is ignored).

time [string]

The time portion of the time for which the selected datasets should be valid, in UT. The date and time specified by the user will be added together and converted to MJD, and compared to the MJDs of the validity start date/time of the files in the CALDB. The latest calibration datasets which match other specifications and which have a validity start date/time less than or equal to the specified date and time are returned. The time should be specified in hh:mm:ss format, with hours, minutes and seconds given as 2-digit integers with leading zeroes. One special value is allowed:

If the date is specified as "now", the current system time is used for the selection.

Note that if the date is given as a single dash ("-"), then the check of the validity start dates is bypassed (and the value of time is ignored).

expr [string]

A boolean selection expression for Calibration Boundary parameters. These parameters can be used to restrict the data selection using additional criteria, like intrument temperature, off-axis angle and other criteria. If no expr selection is required, a "-" character should be input at the prompt. The boolean expression syntax only allows the arithmetic operator ".eq." and the logical operator ".and.". For example, a value of expr = theta.eq.10.and.energy.eq.5 would select calibration datasets whose theta boundary equals 10 and whose energy boundary equals 5, in the units specified by the CALDB boundary keyword values. See Section B of "Required and Recommended FITS keywords for Calibration Files, Section B" for more information, expression syntax and examples.

(caldbver=-)[string]

a string giving the name of the specific calibration index file in the $CALDB/data/mission/instrument/index subdirectory. For example for the NICER XTI a user could specify caldbver=caldb.indx20170814 to query the 20170814 version of the NICER XTI caldb. Specifying a dash (i.e. caldbver=- (the default value of caldbver) queries the current version of the CALDB.

(maxret=-1) [integer]

An integer indicating the maximum number of datasets to return to the screen. If set to -1 all found datasets will be returned. The user will be warned if more datasets were found than were returned, if maxret is a positive integer.

(quality=0) [integer]

An integer giving the desired value of the CAL_QUAL flag of the caldb files. A value of quality = 0 will return the standard "good" calibration files for the specified search. A list of other quality values that have been used historically is available in Section 3 of the Calibration Index Files document (Calibration Memo CAL/GEN/92-008) available at https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_doc.html

(retrieve) [boolean]

If set to "yes", and the user is accessing the caldb remotely (as opposed to accessing the caldb from a locally mounted disk) identified calibration data file which match the selection criteria are downloaded to the user's current working directory. If set to "no", files are not downloaded. This parameter has no effect if the user is accessing a local version of the caldb.

(nfound) [integer]

An integer, returned after the successful completion of this task, which indicates the number of datasets found matching the selection criteria. If this parameter is greater than maxret (and maxret is positive), a warning message will be displayed.

(chatter=0)[integer]

increasing the value of chatter increases the amount of diagnostic output. In particular if chatter = 2 and the specified caldb codename is not found, then the list of unique codenames in the specified caldb.indx file will be displayed.

EXAMPLES

1. Find the location of the ASCALIN dataset for the SIS0 instrument of the ASCA mission valid for Jun 20, 1994, via remote access to the HEASARC CALDB

    % setenv CALDB https://heasarc.gsfc.nasa.gov/FTP/caldb
    % quzcif2 asca sis0 - - ascalin 1994-06-20 12:00:00 -
    https://heasarc.gsfc.nasa.gov/FTP/caldb/data/asca/sis/bcf/s0_teldef_070294.fits   0

2. Find the ALIGNMENT dataset for the FPM instrument of the NuSTAR mission for the optical axis, from the HEASARC CALDB:

    % quzcif2 nustar fpm  - - alignment now now TYPE.eq.OPTICAL
    https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nustar/fpm/bcf/align/nuCalign20200901v001.fits   3

3. Find the ALIGNMENT dataset for the FPM instrument of the NuSTAR mission for the optical axis, from the HEASARC CALDB, and retrieve the file using retrieve=yes, and overwrite the file if it exists in the current working directory, with verbose output:

    % quzcif2 nustar fpm - - alignment now now TYPE.eq.OPTICAL retrieve=yes chatter=1 clobber=yes maxret=-1
 ...... environ-var/logical CALDB defined
 .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
 ... environ-var/logical CALDBCONFIG defined
 ...   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
 ...... environ-var/logical CALDBALIAS defined
 .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
 ...... CALDB is configured for the FPM instrument onboard NUSTAR
 ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nustar/f
           pm/caldb.indx
 ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nu
           star/fpm
gtcalf 1.2.3  : Searching CALDB for quality values =  0
 ...... Searching for CAL_QUAL =          0
 ...... Quality: Found        527 matches out of       1172 rows
 ...... Telescope: Found        527 matches out of        527 rows
 ...... Instrument: Found         88 matches out of        527 rows
 ...... Detector: Found         88 matches out of         88 rows
 ...... Filter: Found         88 matches out of         88 rows
 ...... CAL_CNAME: Found         66 matches out of         88 rows
 ...... Checking boundary expression =TYPE.EQ.OPTICAL
 ...... Boundary: Found         11 matches out of         66 rows
 ...... Time check: Found         11 matches out of         11 rows
 ... Found          1 rows after final selections
nuCalign20200901v001.fits   3

4. Find the files which have CAL_QUAL value of 5 for the Swift XRT MATRIX files

        % quzcif2 swift xrt - - matrix now now - chatter = 1 quality = 5
        ...... environ-var/logical CALDB defined
        .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
        ... environ-var/logical CALDBCONFIG defined
        ...   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
        ...... environ-var/logical CALDBALIAS defined
        .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
        ...... CALDB is configured for the XRT instrument onboard SWIFT
        ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xr
                  t/caldb.indx
        ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/sw
                  ift/xrt
       gtcalf 1.2.3  : Searching CALDB for quality values =  5
        ...... Searching for CAL_QUAL =          5
        ...... Quality: Found        389 matches out of        729 rows
        ...... Telescope: Found        389 matches out of        389 rows
        ...... Instrument: Found        389 matches out of        389 rows
        ...... Detector: Found        389 matches out of        389 rows
        ...... Filter: Found        389 matches out of        389 rows
        ...... CAL_CNAME: Found         63 matches out of        389 rows
        ...... Boundary: Found         63 matches out of         63 rows
        ...... Time check: Found         63 matches out of         63 rows
        ... Found         10 rows after final selections
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s0_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s0_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0s0_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0s6_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s0_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s6_20070901v011.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v012.rmf   1
       https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v012.rmf   1

5. Search for a non-valid codename with chatter = 0 (with remote access to the HEASARC CALDB):

    % quzcif2 swift xrt - - matrix1 now now - chatter = 0
    ERROR - cifsl3 1.0.1: No match for CAL_CNAM = MATRIX1 in https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/caldb.indx
    ERROR - cifsl3 1.0.1: STOPPING
    ERROR - gtcalf 1.2.3: Fatal - STOPPING

6. Search for a non-valid codename with chatter = 2 (with remote access to the HEASARC CALDB):

% quzcif2 swift xrt - - matrix1 now now - chatter = 2 quality = 0
 ...... environ-var/logical CALDB defined
 .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
 ...... environ-var/logical CALDBCONFIG defined
 .........   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
 ...... environ-var/logical CALDBALIAS defined
 .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
 ...... CALDB is configured for the XRT instrument onboard SWIFT
 ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xr
           t/caldb.indx
 ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/sw
           ift/xrt
gtcalf 1.2.3  : Searching CALDB for quality values =  0
 ...  using cifsl3 1.0
 ...... Searching for CAL_QUAL =          0
 ...... Quality: Found        336 matches out of        719 rows
 ...... Telescope: Found        336 matches out of        336 rows
 ...... Instrument: Found        336 matches out of        336 rows
 ...... Detector: Found        336 matches out of        336 rows
 ...... Filter: Found        336 matches out of        336 rows
 ERROR - cifsl3 1.0: No match for CAL_CNAM = MATRIX1 in https://heasarc.gsfc.nas
         a.gov/FTP/caldb/data/swift/xrt/caldb.indx
 ... Allowed Values of CAL_CNAM are:
 ...  using rcnfig 2.0.2
 ... RATEDN2FLUX          EEF                  EVTRANGE
     HKCONV               HKRANGE              BIAS                 MKFCONF
     SPECRESP             TDPOSERR             POSERR
     TDPOSDATA            POSDA
 ERROR - cifsl3 1.0: STOPPING
 ERROR - gtcalf 1.2.3: Fatal - STOPPING

7. Specify date= '-'

% quzcif2 'mission=MAXI' 'instrume=GSC_2' 'detector=-' 'filter=-' 'codename=HVBITHIST' 'date=-' 'time=-' 'expr=-'
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/maxi/gsc/bcf/mx_gsc2_hvhist_20180213.fits   1

BUGS

The current expr parser cannot precheck the expression well. Subexpressions such as "cor.eq.7.and.and.energy.eq.5" will be incorrectly interpreted as "cor=7" and "and.energy=5".

LOG OF SIGNIFICANT CHANGES

MFC (11/09/23), version 0.9: initial release

PRIMARY CONTACT

Mike Corcoran

HEASARC