CAL Memo CAL/GLAST/2007-001

Fermi Calibration Data in the HEASARC Calibration Database
Michael F. Corcoran
Code 662,
NASA/GSFC,
Greenbelt,
MD 20771
Jerry Bonnell
Code 662,
NASA/GSFC,
Greenbelt,
MD 20771


Version: 2007-Jan-01





SUMMARY

This document describes the structure of the Fermi calibration database (CALDB) at the HEASARC. It includes brief descriptions of the data files, update plans, and retrieval information.

LOG OF SIGNIFICANT CHANGES


Release Sections Changed Brief Notes
Date
2007 Jan 01 All First (internal) Draft
2007 Mar 21 § 2, table 1, fig. 1 included cal data files from
2009 Apr 21 (throughout) Changed GLAST to Fermi
2011 May 10 Table 1 revised LAT caldb file names
2012 Feb 22 Table 1 added GBM leaf files

Contents

1  Introduction
    1.1  Fermi
    1.2  The HEASARC Calibration Database
2  Structure of the Fermi CALDB
    2.1  The docs subdirectory
    2.2  The software subdirectory
    2.3  The data subdirectory
3  Fermi CALDB Codenames Values: the CCNM0001 keyword list
4  CALDB Updates
5  General Calibration Data
6  CALDB Data Access
7  CALDB Websites
8  Relevant Fermi Documents
9  Relevant HEASARC Documents
10  Other Useful Webpages

List of Tables

    1  Values of the CCNM0001 keyword in Fermi CALDB calibration files.
    1  Values of the CCNM0001 keyword in Fermi CALDB calibration files.
    2  General Calibration Files Available for Use by Fermi

1  Introduction

1.1  Fermi

The Fermi Gamma-Ray Space Telescope is a joint NASA/DOE mission to survey the gamma-ray sky in the energy range from 10 keV to 300 GeV. Fermi was successfully launched aboard a Delta II rocket from Cape Canaveral Air Force Station in Florida at 12:05 p.m. EDT, June 11, 2008. Fermi consists of 2 instruments, the Large Area Telescope (LAT) and the Gamma-Ray Burst Monitor (GBM). The GBM is an all-sky monitor similar to the BATSE instrument on the Compton Gamma-Ray Observatory (CGRO) and is designed to detect and coarsely localize gamma-ray bursts and other high energy transient events. The GBM includes 12 Sodium Iodide (NaI) scintillation detectors and 2 Bismuth Germanate (BGO) scintillation detectors. The NaI detectors cover the lower part of the energy range, from a few keV to about 1 MeV and provide burst triggers and locations. The BGO detectors cover the energy range of  150 keV to  30 MeV, providing a good overlap with the NaI at the lower end, and with the LAT at the high end. Together the NaI and BGO detectors have similar characteristics to the combination of the BATSE large area and spectroscopy detectors but cover a wider energy range and have a smaller collection area.
The LAT detector is designed to provide high-sensitivity detection of gamma-ray sources in the 20 MeV - 300 GeV range, with fine position resolution. The LAT consists of a four-by-four array of 16 tower modules. Each tower module consists of interleaved planes of silicon-strip detectors and tracker lead converter sheets. Silicon-strip detectors (SSDs) are able to more precisely track the electron or positron produced from the initial gamma-ray than previous types of detectors. The SSDs will give the LAT the ability to determine the location of a cosmic gammay-ray source to within 0.5 to 5 arc minutes. More details on the Fermi mission and the LAT and GBM instruments are available from the Fermi website, http://fermi.gsfc.nasa.gov.
Fermi calibration data is any data obtained on ground or in orbit which is used to characterize the properties of the spacecraft and/or instruments for the analysis of Fermi science data. Calibration data may vary with time, but usually such variations are on timescales long compared to relevant observational timescales (for example, the orbital period or the slewing timescale). Calibration data may also vary with instrumental, environmental or observing conditions. Calibration data includes such things as instrumental response matrices, instrumental effective areas, sensitivities, gains, etc., but generally excludes ancillary engineering or housekeeping data like pointing histories or livetimes which might vary with each observing scan.
During the mission the Fermi Science Support Center (FSSC) is tasked with making Fermi calibration data available to the astrophysical community in a manner consistent with the Fermi analysis software. The FSSC will produce and provide all Fermi calibration data necessary for analysis of Fermi science data in a format consistent with the specifications of the "Calibration Database" (CALDB) at the High Energy Astrophysics Science Archive Research Center (the HEASARC).

1.2  The HEASARC Calibration Database

The HEASARC's calibration database (CALDB) system stores and indexes datasets associated with the calibration of high energy astronomical instrumentation. The system can be accessed by users and software to determine which calibration datasets are available, and which are appropriate for data reduction and analysis. Data in the CALDB which is to be used in analysis must be stored in FITS format, and must include specific FITS header keywords as described in "Required and Recommended FITS keywords for Calibration Files" (CAL/GEN/92-011), available online from the HEASARC CALDB document library. The HEASARC also distributes a set of access routines, called the caltools, as part of the HEASoft multi-mission analysis system. The HEASARC CALDB access software is supported on every operating system that is supported by the HEASoft software suite. This includes almost all flavors of Unix (including linux and Mac OS X). There is currently no support for versions of the Microsoft Windows operating system.
The CALDB for any and all supported missions can be downloaded and installed on a user's machine for any analysis task. Alternatively, users can access the HEASARC CALDB remotely without having to download, install or maintain a local copy of the CALDB (which can be rather large, and which can be updated rather frequently). Analysis software included in the HEASoft package includes CALDB access support. This simplifies the identification and use of calibration data appropriate to the observation being analyzed.

2  Structure of the Fermi CALDB

The top-level CALDB directory is stored in the Unix environment variable $CALDB. For the HEASARC CALDB, the environment variable $CALDB may be defined as http://heasarc.gsfc.nasa.gov/FTP/caldb, which is useful for users to remotely access CALDB data via the internet without having to install a version of the CALDB on a local disk. Remote access to the CALDB is described on the "CALDB Remote Access" document at http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_remote_access.html. Users may copy the Fermi CALDB to their own machines for easier access by downloading a single tar file, in which case a local $CALDB environment variable needs to be defined, as described in "How to Install a Calibration Database" (cal/gen/94-004).
Subdirectories of the $CALDB directory include data, docs and software subdirectories.

2.1  The docs subdirectory

The docs subdirectory contains documentation describing the calibration data for given missions. Fermi-specific calibration documentation describing types of calibration data, uncertainties in the calibrations, applications of the calibrations, and other descriptive matter (including this document) will be located in the docs/fermi subdirectory. Documents describing the structure and use of the CALDB as instituted at the HEASARC will be stored in the docs/memos subdirectory.

2.2  The software subdirectory

The software subdirectory contains various scripts and procedures used for CALDB maintenance. The software/tools/ subdirectory contains setup and initialization files used by the CALDB, in particular:

2.3  The data subdirectory

The Fermi CALDB follows the general CALDB structure in which calibration data are divided, for largely historical reasons, into two types, "basic calibration files" (bcf), consisting of FITS-formatted calibration data primitives, and "calibration product files" (cpf), FITS-formatted calibration data usually derived from the "basic calibration" primitives. A discussion of the differences between "bcf" and "cpf" data is given in CAL/GEN/92-003, "BCF & CPF Calibration File Guidelines". For a given mission and instrument, the calibration data are stored in CALDB subdirectories whose directory path is specified by the mission and instrument name, according to the "type" of data (basic calibration or calibration product). Data for the LAT instrument will be stored in $CALDB/data/glast/lat/<type>, where <type> is either bcf or cpf, depending, respectively, on whether the file is assigned to the basic calibration file or calibration product file type. Similarly, GBM data will be stored in $CALDB/data/glast/gbm/<type>.
Figure
Figure 1: Map of the Fermi CALDB data directory.

3  Fermi CALDB Codenames Values: the CCNM0001 keyword list

Calibration data in the calibration database can be identified by codenames given by the CALDB keyword CCNM0001 in the header of the calibration file extension. Table 1 lists the values of the CCNM0001 keywords, with brief descriptions, in use by the Fermi mission to describe Fermi CALDB data. For all tabulated entries, the keyword TELESCOP='GLAST' (for Gamma-ray Large Area Space Telescope, which was the name of the telescope prior to launch).
Table 1: Values of the CCNM0001 keyword in Fermi CALDB calibration files.
CCNM0001 Value INSTRUME FSSC Des.1 Sample File CAL_DESC Comment
DET_GAIN GBM GS-005 glg_spechist_ < wx > _ < yymmdd > _v < zz > .fit+ Spectral Gain History for Detector NAI_00 Spectral Gain History for GBM Detector XXX_YY. w=N or B for NaI or BGO; x=HEX detector number; yymmdd = date covered by the file; zz = version number
DET_BIN GBM GS-007 glg_lut < ww > _ < zzz > _ < yymmddfff > _v < xx > .fit GBM PHA LUT GBM PHA Look up table; ww = (ct for ctime,cs for cspec); zzz = nai or bgo; yymmdd=date of start of table validity; fff = fraction of day; xx= version number
ECOMPRESS GBM GS-008 glg_leaf_ < nt > _z < wwwwww > _az < yyyyyy > _v < xx > .rsp LEAF files for GBM response generator n='n' or 'b' for detector type; t=0 to b for detector HEX number; wwwwww = zenith angle, millidegrees; yyyyyy = azimuth angle, millidegrees; xx=version number
EDISP LAT LS-011 edisp_PN_vM_<class>.<side>.fits2 (BLANK) Constants for parameterization of the LATŐs energy redistribution
EFF_AREA LAT LS-012 ea_PN_vM_<class>.<side>.fits2+ (BLANK) Constants for parameterization of the LATŐs effective area
RPSF LAT LS-013 psf_PN_vM_<class>.<side>.fits2 (BLANK) Constants for parameterization of the LATŐs radial point spread function
1see GLAST FITS Format Document (GLAST-GS-DOC-0001),
2class is either diff, source or trans; side is either front or back

4  CALDB Updates

Updates to the Fermi CALDB will follow the procedure described in "Automated Delivery of Calibration Data to the CALDB" (cal/gen/2003-001). Ingest data scripts are located in
$CALDB/local/scripts/DATA_DELIVERIES at the HEASARC. Data to be ingested can be placed in appropriate subdirectories in $CALDB/staging/data/glast. Each update to the Fermi CALDB will be listed on the CALDB "What's New" webpage, and also announced via the CALDB RSS NewsFeed.

5  General Calibration Data

The Fermi mission may use general calibration data which may be used by many various missions.
Table 2: General Calibration Files Available for Use by Fermi
Type of File CCNM0001 Value CAL_DIR CAL_DESC Sample
Leap Seconds Table LEAPSECS $CALDB/data/gen/bcf Table of times at which Leap seconds occurred leapsec_010905.fits

6  CALDB Data Access

Fermi data in the CALDB can be retrieved by a number of mechanisms. Users can directly access files via anonymous ftp from ftp://legacy.gsfc.nasa.gov/caldb/data/glast, or via the WWW from http://heasarc.gsfc.nasa.gov/FTP/caldb/data/glast, if the user knows the name and location of the file. This is not very convenient when a user needs to choose from a number of versions of the same file, since it may not be clear which version is applicable to the analysis task at hand. The tool quzcif, distributed as part of the HEASoft caltools package, allows users to determine which calibration file (or files) are appropriate for a given analysis task after the user specifies a given set of observing parameters (date and time of observation, instrument, and other relevant parameters). After the relevant observing parameters are specified, quzcif returns the names of the appropriate files from the CALDB. The HEASoft calibration software library (callib) FORTRAN subroutine gtcalf can be used by individual software tasks to retrieve relevant calibration data from the CALDB with little or no user input. A description of gtcalf is given in "HEASARC CALDB Access Subroutines" (cal/sw/95-002).
This subroutine may evolve as new capabilities are required; users should check the latest distribution of the HEASoft package for the latest version of the gtcalf.f subroutine.
Users of the HEASoft software (or any software that supports virtual file input using urls1 (like software based on the CFITSIO library) and an internet connection can also access the HEASARC CALDB remotely (i.e. without having to install the CALDB locally).
The CALDB website has more information on installing and managing the CALDB, and information on accessing the CALDB remotely.

7  CALDB Websites

The CALDB homepage is http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/. General information regarding the Fermi CALDB, including links to tarfiles of Fermi calibration data and dates of updates, will be made available on the CALDB supported missions webpage and announced on the CALDB rss feed, and included on the CALDB "What's New" web page. For each Fermi CALDB release for the LAT and the GBM, a summary of the current calibration files will be available from the Fermi LAT and Fermi GBM CALDB summary pages.

8  Relevant Fermi Documents

9  Relevant HEASARC Documents

10  Other Useful Webpages

Footnotes:

1Uniform Resource Locator

File translated from TEX by TTHgold, version 4.00.
On 4 Dec 2012, 11:51.