Contents

1  OVERVIEW

1.1  Location

The HEASARC calibration database (CALDB) is physically located on the legacy machine within the LHEA at NASA/GSFC:

• Internet: legacy.gsfc.nasa.gov

1.2  Basic Structure

The contents of the /caldb area is sub-divided between the following sub-directory trees²:

• data - containing the calibration dataset directory tree.

• software - containing the caltools software tasks, the callib subroutine library and a number of other software-related items.

• docs - containing related calibration documentation

1.3  Relation to Other Areas of the HEASARC anonymous FTP account

During a reorganization of the HEASARC anonymous FTP account on legacy carried out in 1993 Feb, it was decided to relationalize the structure seen by remote users in the hope that this would facilitate their search for desired files. The account contains the following sub-directories:

• software - containing general software (e.g. XSPEC, FTOOLS, XRONOS, XIMAGE etc)

• documents - containing general documents such as GOF Users Guides, PROS Cookbooks etc

• retrieve - where the XOBSERVER accounts at located

• mission - where mission-specific archival data, documentation, software etc is located.
  A generic mission sub-directory tree therefore consists of:
  • doc

  • problems

  • nra_info

  • data/inst

  • timelines

  • software

  • publications

  • calib_data

• caldb - the calibration database

1.4  Access

As described in Section 1.1, at the present time the HEASARC CALDB exists onftp://legacy.gsfc.nasa.gov/caldb.

1.4.1  Anonymous ftp to the Legacy machine

Users of machines on the Internet network may use File Transfer Protocol (ftp), to list the contents and/or copy file from the HEASARC CALDB.

To initiate ftp from the command line, type the following (boldface) commands in a terminal window at the prompt (comments appear in italics):
ftp legacy.gsfc.nasa.gov (or ftp 128.183.8.233)
then
ftp> user anonymous
Password: type your e-mail address as the password
You will now be in the top level directory³ of the HEASARC anonymous ftp account on legacy and a message to this effect, along with any important bulletins, should be displayed. A general overview of the account can be found in Drake (1993). More detailed on-line information, instructions etc concerning the ftp account can be found within the ASCII README file within this (and many other) directories.

The following list of basic ftp commands may be of use to the inexperienced ftp user:
ftp> help                 (or ftp> ?) displays list of ftp commands
ftp> help lcd displays help for ftp command lcd
ftp> cd caldb/docs move to the caldb/docs directory
ftp> cd ../ move back up one directory
ftp> ls brief list of the contents of the current legacy directory
ftp> dir detailed list of the contents of the current legacy directory
ftp> pwd display the present working directory on legacy
ftp> binary set binary transfer type (required for FITS files etc)
ftp> mget * copies all files in the current legacy directory to your area
ftp> ascii set ASCII transfer type (required for L^AT_EXdocuments, postscript files etc)
ftp> get README copies the README from current Legacy dir to local dir
ftp> lcd /home change local directory to /home on user's home machine
ftp> quit quits from ftp & returns control to local operating system A variety of other useful commands are available within ftp, a number of which depend on which version of ftp is installed on the local machine.

2  CALIBRATION DATA FILES

The HEASARC CALDB classifies files as `Primary Calibration Files' `Basic Calibration Files' and `Calibration Product Files' (PCFs, BCFs & CPFs respectively; see also CAL/GEN/91-001). PCFs are 'raw' ground and in-orbit calibration datasets not of immediate interest to most users as they are not directly required for (all but the most specialized) scientific data analysis tasks. BCFs contain the lowest level calibration datasets potentially required by downstrem software, and can be considered the `atomic units' of the instrument calibration. CPFs contain `convolutions' of the information stored within BCFs customized for a specific analysis task and/or scientific observation.

2.1  BCF & CPF Datasets

All BCF & CPF calibration files are organized using the scheme

Besides the calibration datasets themselves, each sub-directory of /caldb/data/mission contains:

• a caldb.indx Calibration Index File (CIF), required for accesing calibration datasets within the OGIP,

• a tar file containing valid BCF & CPF calibration datafiles

2.1.1  Symbolic Links to Other Areas

As mentioned in Section 1.3, there are 2 routes via which ftp users can access BCF & CPF calibration datasets:

• via the /mission/calib_data tree (the prefered route for most users), or

• via the /caldb/data/mission tree (probably the preferred route for users maintaining a remote version of the HEASARC CALDB.

2.2  PCFs

Due the the large data volume, the PCFs from all missions are given their own parallel directory tree:

• ground containing (if any) ground calibration measurements and datasets from theoretical simulations

• in-orbit containing in-orbit calibration data (eg raw data from on-board radioactive calibration sources etc), but excluding calibration observations of astronomical sources.

• cal_obs containing scientific datasets from calibration observations of astronomical sources.

2.2.1  Symbolic Links to Other Areas

The calibration datasets resulting from the observation of astronomical sources (eg the Crab) are available in the /mission/data/inst directory tree (see Section 1.3). Thus cal_obs will be a symbolic link to this directory. It should be noted that NO corresponding symbolic link from the /mission/data/inst area back to /caldb/data/pcf/mission/inst will be provided. Users wishing to return will therefore be required to use the full path when changing directory back.

2.3  Non-FITS files

For the convenience of users, at the present time the HEASARC CALDB does contain a small number of calibration datasets in formats other than FITS. In almost all cases, FITS versions of these datasets (using a standard OGIP file format) also exist within the caldb. Users should note that the permanent existence, quality etc of these non-FITS files is in NO WAY guarenteed. In most cases such files represent calibration datasets in an old format. Thus such files are stored in a old sub-directory of the .../inst/bcf or .../inst/cpf directories. ASCII README files usually exist explaining the formats etc of the datasets, and giving the name and location of the corresponding FITS versions of the file(s).

3  CALIBRATION SOFTWARE

3.1  CALTOOLS & CALLIB

The bulk of the calibration-related software publically available from the HEASARC will be in the form of ftools forming the caltools sub-package. All routines are written in ANSI FORTRAN or C, and are able to be executed both as standalone tasks on all OGIP-supported platforms/operating systems, or from within IRAF environment. A list of all currently available and planned caltools tasks is given in CAL/SW/93-004.

Users may also be interested in the callib subroutine library (in a directory of this name parallel to the caltools package) containing commonly used utilities, and in particular, routines for reading and writing calibration datasets adhering to OGIP-standard file formats. A detailed listing of the contents of callib can be found in CAL/SW/93-005.

Details on the installation and maintanence of the HEASARC caldb software collection at remote nodes can be found in CAL/GEN/92-015.

3.1.1  Symbolic Links to Other Areas

The /caldb/software/caltools file is a symbolic link to the /software/ftools/caltools area within the main HEASARC software collection. Similarly /caldb/software/callib is a symbolic link to the /software/ftools/callib area.

It should be noted that NO corresponding symbolic links from these directories back to /caldb/software are provided. Users wishing to return will therefore be required to use the full path of the disired directory when changing back.

4  CALIBRATION DOCUMENTATION

The /caldb/docs directory is sub-divided into

• memos containing all non mission-specific HEASARC calibration memos

• mission containing all mission-specific calibration documentation.

The best starting point for finding calibration-related documentation is via the World-wide Web via the URL:
/docs/heasarc/caldb/caldb\_doc.html

REFERENCES

Drake, S., & O'neel, B., 1993. Legacy, 3, 53.

George, I.M., 1992. Legacy, 1, 56. (CAL/GEN/91-001)

George, I.M. & Zellar, R., 1993. In preparation. (CAL/GEN/92-015)

George, I.M., Zellar, R. & Yusaf, R, 1993a. In preparation. (CAL/SW/93-004)

George, I.M., Zellar, R. & Yusaf, R, 1993b. In preparation. (CAL/SW/93-005)

Pence, W., 1992. Legacy, 1, 14.

USEFUL LINKS TO OTHER HTML PAGES

The following useful links are available (in the HTML version of this document):

• The HEASARC Home Page
• The HEASARC Calibration Database Home Page