HEASARC Calibration Memo CAL/GEN/92-011
Required and Recommended FITS keywords for Calibration Files
Ian M George,
Lorraine Breedon,
&
Michael F. Corcoran
Codes 662,
NASA/Goddard Space Flight Center,
Greenbelt, MD 20771
Version: 1998 Nov 20
|
Release | Sections Changed | Brief Notes |
Date | ||
1992 Oct 02 | First Draft | |
1993 May 18 | All | Reviewed & updated |
1994 Jan 05 | The CBDnxxxx String | New syntax introduced |
1994 Dec 19 | All | New CCNMxxxx values |
(and made LaTeX2HTML compatible) | ||
1998 Nov 20 | All | reviewed and updated by MFC; revised list of CCNM0001 values |
2004 Apr 01 | All | made tth compatible |
2004 Jul 14 | Appendix B | added discussion of NONE boundary value |
In order to facilitate software and user identification/access of the numerous calibration datasets within the HEASARC calibration database (CALDB), the location, contents and quality of all datasets will be contained with Calibration Index Files (CIFs). The CIFs provide a link between processing/analysis software and the calibration datasets. A detailed description of the contents, format and operation of CIFs is given in CAL/GEN/92-008. A number of required keywords need to be present within the FITS file extension header of every calibration dataset contained within the HEASARC CALDB. These keywords and defined keyword values are given in this document.
Furthermore, while limited human & software checks are performed as part of the ingestion of calibration datasets into the CALDB, it is the responsibility of suppliers of calibration datasets to ensure the appropriate keywords are both present and their values are in the correct format. Authors of calibration datasets are urged to contact the HEASARC Calibration Team if this document is unclear, and/or does not cover their specific needs. In particular, in cases where the list of defined keyword values is insufficient, new values may be defined in consultation with the HEASARC Calibration Database team.
Please send e-mail to caldbhelp@olegacy.gsfc.nasa.gov for more information.
The following keywords (also listed in Table 2) are required if a calibration data file is to be indexed in the Calibration Index File:
versions).
Value to be inserted into TELESCOPE column of CIF.
Keyword | Description | Required/Optional |
TELESCOP | Name of satellite or mission | required |
INSTRUME | Name of instrument or Detector | required |
DETNAM | Name of specfic detector if INSTRUME insufficient | optional |
FILTER | Name of Filter in use (if any) | optional |
CCLS0001 | HEASARC class of file | required |
CDTP0001 | HEASARC data type code | required |
CCNM0001 | HEASARC calibration dataset codename (see also Section ) | required |
CBDnxxxx | Calibration Dataset parameter limitations (see also Section B) | optional |
CVSD0001 | Start date of validity of calibration dataset | required |
CVST0001 | Start time of validity of calibration dataset | required |
CDESxxxx | Description of Calibration Dataset | required |
The following keywords are recommended to be present in each FITS calibration file extension to be indexed in the calibration index file. Their presence in a FITS file extension is not currently required by any CALDB software routines or subroutines.
CTEL0001= 'ROSAT ' / used applicable to the ROSAT mission CTEL0002= 'ASCA ' / data applicable to the ASCA missionDefined values are the same as those used for the TELESCOP keyword and are given in HEASARC/93-013 (George & Angelini 1993).
CINS0001= 'SIS0 ' / used applicable to the SIS0 CINS0002= 'SIS1 ' / data applicable to the SIS1The values of these keywords are the same as those for the INSTRUME keyword as given in OGIP/93-013 (George & Angelini 1993)
CINS0001= 'SIS0 ' / data applicable to the SIS0 CINS0002= 'SIS1 ' / data applicable to the SIS1 CDT10001= 'CCD0 ' / data applicable to the CCD0 for CINS0001 (i.e. SIS0) CDT10002= 'CCD2 ' / data applicable to the CCD1 for CINS0001 (i.e. SIS0) CDT10003= 'CCD4 ' / data applicable to the CCD4 for CINS0001 (i.e. SIS0) CDT20001= 'CCD1 ' / data applicable to the CCD1 for CINS0002 (i.e. SIS1) CDT20002= 'CCD3 ' / data applicable to the CCD3 for CINS0003 (i.e. SIS1)Note: a given calibration dataset can thus store information for up to 9999 detectors for up to 9 instruments; additional instrument data should be placed in separate file extensions. The values of the CDTNxxxx keywords are the same as that of the DETNAM keyword, and are given in OGIP/93-013 (George & Angelini 1993).
These recommended keywords have been defined to uniquely identify single datasets which may be appropriate to two or more individual instruments/detectors and so minimize the number of files/extensions of calibration data which needs to be written and archived. In practice such combinations can become quite complicated; we recommend that clarity never be sacrificed for efficiency.
Keyword | Description |
CTELxxxx | Name of satellite or mission |
CINSxxxx | Name of Instrument(s) for given mission |
CDTnxxxx | Name of detector(s) for given instrument(s) (if necessary) |
CFInxxxx | Name of Filter in use (if any) |
George, I.M. & Yusaf, R.,1992. HEASARC Calibration Memo CAL/GEN/92-020.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_020/cal_gen_92_020.html
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-019.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_019/cal_gen_92_019.html
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-021.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_021/cal_gen_92_021.html
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-022.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_022/cal_gen_92_022.html
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-023.
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-024.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_024/cal_gen_92_024.html
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-025.
George, I.M. & Zellar, R.,
1992. HEASARC Calibration Memo
CAL/GEN/92-026.
George, I.M. & Angelini, L.,
1993. HEASARC Memo OGIP/93-013.
http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/ogip_93_013/ogip_93_013.html
George, I.M. & Arnaud, K.A.,
1993. HEASARC Calibration Memo
CAL/GEN/92-002a
(addendum to CAL/GEN/92-002a).
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002a/cal_gen_92_002a.html
George, I.M. & Zellar, R.,
1993. HEASARC Calibration Memo
CAL/GEN/92-003.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_003/cal_gen_92_003.html
George, I.M. & Angelini, L.,
1994. Legacy, 4, in press
(OGIP/93-001).
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_003/cal_gen_92_003.html
George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L.,
1992. Legacy, 2, 51.
http://heasarc.gsfc.nasa.gov/docs/journal/calibration_rqmts2.html
George, I.M., Pence, W. & Zellar, R.
1993. HEASARC Calibration Memo CAL/GEN/92-008.
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_008/cal_gen_92_008.html
George, I.M., Zellar, R. & White, N.E.,
1993.
(CAL/GEN/92-013).
Zellar, R. & George, I.M.,
1993.
(CAL/GEN/92-017)
Most of the above references are also available via anonymous ftp from ftp://legacy.gsfc.nasa.gov/caldb/docs/memos
The following useful links are available (in the HTML version of this document only):
The value of the CCNM0001 keyword provides the means for downstream software to check that a given calibration dataset is indeed what is required by the user, and as a pointer as to whether or not further calibration inputs are required for a given software task.
In the following section we provide a list of values for the CCNM0001 keywords. This list will be updated as new values are defined.
These keyword values represent general properties which almost all X-ray missions and instruments share. These values appear in at least one file in the HEASARC CALDB.
CCNM0001 | Description | see |
value | Section | |
2D_PSF | 2-dimensional Point Spread Function (Image) | A.1.1 |
COLLRESP | Collimator Response (potentially energy dependent) | A.1.2 |
DETEFF | Efficiency of Detector (only) | A.1.3 |
DET_EFF | Detector Efficiency | A.1.4 |
DETMAP | Detector Map | A.1.6 |
EBOUNDS | Redistribution Matrix Energy Boundaries | A.1.7 |
EEF | Encircled Energy Fraction Point Spread Function | A.1.5 |
EFFAREA | Effective Area of Optics (only) | A.1.8 |
(may include on-axis values only) | ||
ENERGY_GRID | Standard Energy grid used for calibration datasets | A.1.9 |
FATOM | Atomic data used for Filter transmission | A.1.10 |
FTRANS | Filter Transmission | A.1.11 |
HKCONV | Housekeeping data Conversion parameters | A.1.12 |
MATRIX | Redistribution Matrix | A.1.13 |
RPSF | Radial Profile Point Spread Function | A.1.14 |
SPECRESP | Spectral response | A.1.15 |
SPECRESP MATRIX | Redistribution & Spectral response Matrix | A.1.16 |
TVIGNET | Total Vignetting function of optics | A.1.17 |
(ie with obscuration factor included) | ||
VIGNET | Vignetting function (only) of optics | A.1.18 |
(ie excluding obscuration factor) | ||
WATOM | Atomic data used for Window transmission | A.1.10 |
WTRANS | Transmission of the detector/instrument window | A.1.11 |
XSECT | Atomic absorption Cross-sections | A.1.21 |
Dataset contains a 2-dimensional mini-image of the point spread function, centered on the peak, and normalized to one detected photon.
Collimator Response
Dataset is an n-dimensional grid giving the efficiency of the detector as a function of energy, position, and any other necessary parameters. The dimensions and contents are obviously highly detector-specific. Detailed file formats are given in CAL/GEN/92-025 (George & Zellar 1992).
Deprecated; same as DETEFF
Dataset contains a (1-dimensional) encircled energy fraction profile of the the point spread function, constructed using concentric annuli centered on the peak.
Detector Map
Dataset is a 1-dimensional list (as a function of energy)
listing the (nominal) energy boundaries for each raw detector
PHA channel.
Constructed from the associated Detector Redistribution Matrix, with
the energies corresponding to the maxima in the matrix for the lower and
upper channel boundaries (and thus defining the nominal gain
(energy→channel) relationship).
Use: Spectral analysis of PHA data (in conjunction with
an RMF containing CCNM0001 = 'MATRIX' dataset and
an ARF containing a CCNM0001 = 'SPECRESP' dataset;
or equivalently with an RMF containing a
CCNM0001 = 'SPECRESP MATRIX' dataset).
Usual Origin: EBOUNDS extension within an RMF.
See CAL/GEN/92-002 (George et al. 1992) and its addendum, CAL/GEN/92-002a
(George & Arnaud 1993).
Dataset is a 3-dimensional grid giving
the effective area of the instrument optics (only) as
a function of energy, and off-axis position.
For off-axis angles, any reduction in geometric area due to
obscuration by the telescope structure and the effects of vignetting
are assumed to be included.
However, should there be CBDnxxxx keywords
with values:
'THETA(0.0)arcmin', and
'PHI(0.0)arcmin',
the
3-d dimensional dataset will be assumed to have
been collapsed to a 1-d list of
on-axis effective area as a function energy.
In such cases a CCNM0001 = 'TVIGNET'
calibration dataset
(or CCNM0001 = 'VIGNET' and
CCNM0001 = 'OBSCFACT' datasets)
will be assumed to be required to calculate
an off-axis effective area.
Detailed file formats are given in
CAL/GEN/92-019 (George & Zellar 1992).
Contains the lower and upper boundaries to the standard incident energy grid used for many PSPC calibration files.
Data table consists of one or both of 2 (optional) calibration datasets:
Dataset is a 3-dimensional grid giving the transmission of a filter/window as a function of energy and position. Detailed file formats are given in CAL/GEN/92-024 (George & Zellar 1992).
Dataset is in a highly instrument-specific format, and contains information necessary to convert satellite housekeeping information to physical units.
Dataset is a 2-dimensional matrix (energy vs PHA channel) describing the redistribution of photons within a detector, constructed by folding together (only) the components due to the:
Dataset contains a (1-dimensional) radial profile of the the point spread function, constructed using concentric annuli centered on the peak. The dataset should be normalized to one detected photon and expressed in units of photons per (physical) unit area.
Dataset is a 1-dimensional list (as a function of energy) containing the spectral response of an instrument (ie telescope + filter + detector) constructed by folding together the components due to:
Dataset is a 2-dimensional matrix (energy vs PHA channel) describing the redistribution of photons within a detector and the energy response of the instrument (ie telescope + filter + detector). Constructed by folding together the components due to the:
Dataset is a 3-dimensional grid giving the total vignetting function (including the effects of obscuration) of the instrument optics (only) as a function of energy, and off-axis position. For use calculating the off-axis effective area, this dataset must be used in conjunction with on-axis data from a CCNM0001 = 'EFFAREA' calibration dataset. Detailed file formats are given in CAL/GEN/92-021 (George & Zellar 1992).
Dataset is a 3-dimensional grid giving the vignetting function of the instrument optics (only, excluding the effects of obscuration) as a function of energy, and off-axis position. For use calculating the off-axis effective area, this dataset must be used in conjunction with on-axis data from a CCNM0001 = 'EFFAREA' calibration dataset and with the relevant off-axis data from a CCNM0001 = 'OBSCFACT' calibration dataset. Detailed file formats are given in CAL/GEN/92-021 (George & Zellar 1992).
Dataset is a 2-dimensional grid listing the absorption cross-sections (or mass absorption coefficients) as a function of energy and element/compound which have been used during the construction of other calibration datasets.
CCNM0001 | Coordinate | |
Transformation | ||
value | from | to |
RAW2PHY | Raw Detector | Physical Detector |
RAW2LIN | Raw Detector | Linearized Detector |
PHY2ECL | Physical Detector | (Celestial) Ecliptic |
The CCNM0001 keyword is a string which explicitly describes the coordinate transform stored. Currently defined transformations are given in Table 4 (see also CAL/GEN/92-003, George & Zellar 1993, available on-line as postscript and html versions). It is strongly recommended that the transform is further described within the file via copious COMMENT lines. Detailed file formats of calibration files storing the necessary transformation information are described in HEASARC/92-016 (George & Yusaf 1992). The number and details of the coordinate transforms required is, of course, highly instrument-specific. It is recommended that usage of these keywords be confined to basic calibration file (CCLS0001='BCF ') data only.
The following values of CCNM00010001 have been proposed for use in calibration datasets in the HEASARC CALDB, but are not yet used by any archived dataset.
Dataset contains the location of all 'bad' pixels (ie those pixels from which the scientific data should be disregarding during scientific analysis), along with the date they went bad, and a flag to indicate the reason. Detailed file formats are given in CAL/GEN/92-026 (George & Zellar 1992).
Dataset consists of a ßtandard event list" for that mission/instrument, but contains only background photons. Such a dataset can be analyzed in the same way as a ßource event list" so as to obtain the corresponding background lightcurve/spectrum/image etc
Dataset consists of a ßtandard event list" for that mission/instrument, but contains only background photons WITHOUT inclusion of cosmic (``sky'') background events (as, for example, a dataset compiled by staring at the dark earth). Such a dataset can be analyzed in the same way as a ßource event list" so as to obtain the corresponding background lightcurve/spectrum/image etc,
Dataset consists of a ßtandard event list" for that mission/instrument, but contains only background photons compiled by staring at the bright earth. Such a dataset can be analyzed in the same way as a ßource event list" so as to obtain the corresponding background lightcurve/spectrum/image etc,
Dataset is 2-dimensional listing the unobscured regions of an imaging detector.
Dataset contains the energy resolution of the detector as a function of energy. The format and details of precisely what values are stored are considered detector-specific
Dataset contains the gain of the detector. The format and details of precisely what values are stored are considered detector-specific
Dataset contains correction factors and/or offsets such as to correct the detected positions of events to a 'standard' grid in the detector coordinate system. The format and details of precisely what values are stored are considered detector-specific
CCNM0001 | Description | see |
value | Section | |
Proposed Multi-mission Values | ||
BADPIX | Bad Pixel map | A.2.1 |
BKGRND_EVTS | Background events dataset | A.2.2 |
DETMSK | Detector Mask | A.2.5 |
DET_ENRES | Detector Energy resolution | A.2.6 |
DET_GAIN | Detector Gain | A.2.7 |
DET_POSCORR | Detector Position corrections | A.2.8 |
DET_POSRES | Detector Position resolution | A.2.9 |
OBSCFACT | Obscuration Factor of the optics | A.2.10 |
(ie the geometric vignetting factor only) | ||
TEMP | (Detector) Temperature History | A.2.11 |
Dataset contains the position resolution of the detector. The format and details of precisely what values are stored are considered detector-specific
Dataset is a 2-dimensional grid giving the geometrical obscuration factor (also sometime referred to as the geometric vignetting function or collimator response) of the optics/collimator as a function of off-axis position. For use calculating the total vignetting function, this dataset must be used in conjunction with a CCNM0001 = 'VIGNET' calibration dataset. This dataset is assumed to have already have been included in CCNM0001 = 'TVIGNET' and CCNM0001 = EFFAREA datasets (unless the latter is applicable on-axis only - see Section A.1.8). Detailed file formats are given in CAL/GEN/92-019 (George & Zellar 1992).
Dataset is a simple list of (detector) temperature vs time.
The following values of CCNM0001 represent calibration data which are instrument or mission specific, and have been defined at the request of the individual project.
This is a non-standard codename, only used for the ASCA/SIS. It is used in the ASCA Telescope Definition File. Created 1993 Jun 07 (Eric Gotthelf, ASCA GOF, NASA/GSFC). This SIS telescope definition file defines the detector address space along with the transformation needed to reconstruct the focal plane location of the individual SIS CCD chips. Further data parameterizes the telescope optics and boresight alignment. All data is contained within the keywords of the Primary Header. There is no data in the Primary Array.
This is a non-standard codename, only used for the ASCA/GIS.
This is a non-standard codename, only used for the ASCA/GIS. It represent GIS raw to linearized coordinate transformation maps.
CCNM0001 | Description | see |
value | Section | |
Mission/Instrument-specific Values | ||
ASCALIN | ASCA/SIS Telescope Definition File | A.3.1 |
ASCALIN_FLF | ASCA/GIS Unknown | A.3.2 |
ASCALIN_POW2 | ASCA/GIS Unknown | A.3.3 |
EDS_COR | XTE/PCA EDS gain corrections | A.3.4 |
GRIDTRNS | ASCA/GIS Unknown | A.3.5 |
PART_BKGD_MAP_AP | ROSAT/PSPC After-pulse contribution to background | A.3.6 |
PART_BKGD_MAP_EXT | ROSAT/PSPC External contribution to Background | A.3.7 |
PART_BKGD_MAP_INT | ROSAT/PSPC Internal contribution to Background | A.3.8 |
RTIBOUNDS | ASCA/GIS Unknown | A.3.9 |
SGC_E | ROSAT/PSPC Spatial Gain correction, E-dependent terms | A.3.10 |
SGC_POS | ROSAT/PSPC Spatial Gain correction, position-dependent terms | A.3.11 |
WC_E | ROSAT/PSPC Window Correction, E-dependent terms | A.3.13 |
WC_POS_X | ROSAT/PSPC Window Correction, X-dependent terms | A.3.14 |
WC_POS_Y | ROSAT/PSPC Window Correction, Y-dependent terms | A.3.15 |
WINTHICK | ASCA/GIS Unknown | A.3.12 |
XTE/PCA EDS gain corrections
This is a non-standard codename, only used for the ASCA/GIS. It represents the transmission for the GIS2 window grid
After-pulse Detector background map for the ROSAT PSPC.
Notes by Steve Snowden (02/03/94): Created using as many afterpulse events as could be isolate using strongly affected pointed observations and the survey completion data. This detector map is for the afterpulse background component of PSPC B
ROSAT PSPC external particle background detector map. Notes by Steve Snowden (02/03/94): Created using a devignetted detector map. This detector map is for the externally produced particle background component for both PSPCs.
ROSAT PSPC Internal particle background detector map. Notes by Steve Snowden (02/03/94): Created using the particle background calibration of Plucinsky et al. 1993, ApJ, 418, 519 This detector map is for the internally produced particle background component for the PSPC B.
ROSAT PSPC Spatial Gain Correction: Energy-dependent term. Notes from J. Turner, 1995 Oct 06: This dataset was converted to FITS format by Rehana Yusaf (FTOOLS) from the ASCII file GNAMPL_NEW.DAT used by SASS.
The dataset is used to correct for small-scale non-linearities which are introduced into the positions assigned to PSPC events by the detector wires. This dataset contains the energy-dependent correction vector, stored as a function of intermediate pulse-height (PH_3) in column SGC_HF_E. This dataset is assumed to be valid for both PSPCs. It should be noted that further vectors, which are a function of position (only), are also required to correct the position of each event for these electronic effects. Furthermore, an additional correction due to the bulging of the detector window must be performed on the position of each event before totally linearized detector coordinates are obtained. Finally it should be noted that PH_3 is NEITHER observed PHA channel NOR derived PI channel, but is instead a partially corrected pulse-height bin. See HEASARC Calibration Memo CAL/ROS/95-010 for further details
ROSAT PSPCB Spatial Gain Correction: Position-dependent terms. NOTES from J. Turner, 1995 Oct 06: This dataset was converted to FITS format by Rehana Yusaf (FTOOLS) from the ASCII file GAIN_KOR3_B.DAT used by SASS.The dataset is used to correct for small-scale non-linearities which are introduced into the positions assigned to PSPC events by the detector wires. This dataset contains the two position-dependent correction vectors, stored in columns SGC_LF_Y & SGC_HF_Y, both of which vary as a function of position (stored in column Y_1). It should be noted that a further vector, which is a function of pulse height (only), is also required to correct the position of each event for these electronic effects. Furthermore, an additional correction due to the bulging of the detector window must be performed on the position of each event before totally linearized detector coordinates are obtained. See HEASARC Calibration Memo CAL/ROS/95-010 for further details
This is a non-standard codename, only used for the ASCA/GIS. Data of this type represents the spatial variation of thickness in GIS2 Be window
ROSAT PSPC Window Correction: Energy-dependent correction term.
ROSAT/PSPC Window Correction, X-dependent terms
ROSAT/PSPC Window Correction, Y-dependent terms
The calibration boundary keywords provide a means of specifying the limitations or parameter boundaries of a calibration dataset (eg the energy range, range of spatial coordinates, range of temperatures, range of HV settings etc over which the dataset is valid) which the author of the dataset would like to indicate to downstream software.
The calibration boundary keywords are named CBDnxxxx where xxxx is the calibration dataset within that extension (as described above), and n is an integer index in the range 1-9 specifying the boundary reference number1. Thus the limits on each calibration dataset within an extension can be denoted via the keywords CBD1xxxx, CBD2xxxx, CBD3xxxx, ..., CBD9xxxx.
The ordering of the various strings is not crucial (ie which parameter limitations is specified by CDB1xxxx, which by CDB2xxxx etc is not crucial), although the values of n within the CBDnxxxx keywords must be sequential starting at 1. However, when checking for any limitations on a given parameter the (CIF) access software will first check the string stored in CDB1xxxx, then CDB2xxxx etc, thus it an advantage to store the most important limitations (from the point of view of downstream software) first.
The CDBnxxxx keywords are optional. It is sometimes convenient for software which writes calibration FITS files to include all 9 CBD keywords all FITS headers. In such cases unused boundary keywords should be filled with the NULL boundary value. For boundary keywords the NULL value is represented with the string ``NONE'', for example:
CBD20000 = 'NONE ' / only a single boundary keywords exists CBD30000 = 'NONE ' / only a single boundary keywords exists CBD40000 = 'NONE ' / only a single boundary keywords exists CBD50000 = 'NONE ' / only a single boundary keywords exists CBD60000 = 'NONE ' / only a single boundary keywords exists CBD70000 = 'NONE ' / only a single boundary keywords exists CBD80000 = 'NONE ' / only a single boundary keywords exists CBD90000 = 'NONE ' / only a single boundary keywords exists
Important Note: while the order of calibration keywords is in general unimportant, for NULL value keywords order is important in that, if the first calibration keyword has a null value (i.e. CBD10000 = 'NONE') all other keyword values will be ignored.
The value of each CBDnxxxx keyword is
a character string which refers to a
different dimension of parameter space, and has the following format:
| (1) |
Each of the value descriptors, VALDESj, can have four possible forms, any of which can be included/combined in the same CBDnxxxx keyword value:
pname | Parameter | Type of Units |
string | ||
Spatial Coordinates | ||
RAWX | Raw detector coordinates in a cartesian frame | (detector specific) |
RAWY | Raw detector coordinates in a cartesian frame | (detector specific) |
DETX | Linearized detector coordinates in a cartesian frame | (detector specific) |
DETY | Linearized detector coordinates in a cartesian frame | (detector specific) |
PHYX | Physical detector coordinates in a cartesian frame | physical linear |
PHYY | Physical detector coordinates in a cartesian frame | physical linear |
THETA | Off-axis angle (θ) in XMA polar coordinate frame | angular |
PHI | Azimuthal angle (φ) in XMA polar coordinate frame | angular |
ALPHA | Off-set angle in image plane from XMA optical axis | angular |
(along φ = 0° vector) | ||
BETA | Off-set angle in image plane from XMA optical axis | angular |
(along φ = 90° vector) | ||
Other (multi-mission) Parameters | ||
CHAN | (Detector) ADC channel | unitless |
ENERG | Photon energy | physical |
HV | (Detector) High Voltage | physical |
MODE | (Detector) Operating Mode | unitless |
PANG | Pair Opening Angle | angular |
PICH | Pulse Invariant detector channel | unitless |
TEMP | (Detector) Temperature | physical |
Mission/Instrument-specific Parameters | ||
ECHO | ASCA/SIS 'echo correction' applied/not-applied | unitless |
GRADE | ASCA/SIS photon 'grade' | unitless |
SPLIT | ASCA/SIS split threshold | unitless |
Currently only the simplest type of parameter expression is supported, namely a format in which the expr string is simply the name of a parameter, pname, denoting that the calibration dataset is valid for parameter pname values between min and max (in units given by units). The allowed values of the pname string are as for the standard column/keyword names listed in CAL/GEN/92-003 (George & Zellar 1993, available on-line as pdf and html versions). Those defined at the time of writing are also listed in Table 8 for convenience.
Example
A calibration dataset, which was the only such dataset within the extension
(hence had xxxx = 0001), and which was valid for photon energies in
the range 0.501-2.0 keV, off-axis angles in the range 0-54.2 arcmin, and
all azimuthal angles (0-360°) would have
CBD10001 = 'ENERG(0.501-2)keV'
CBD20001 = 'THET(0-54.2)arcmin'
CBD30001 = 'PHI(0-360)deg'
A calibration dataset, which was the only such dataset within the extension
(hence had xxxx = 0001), and which was valid for photon energies in
the range 1 eV - 10 MeV, an off-axis angle 5.4 arcmin (only), and
azimuthal angles 0-90° and 180°-270°
(but nowhere else) would have
CBD10001 = 'ENERG(1-10000000)eV'
CBD20001 = 'THETA(5.4)arcmin'
CBD30001 = 'PHI(0-90,180-270)deg'
The number of parameter-space limitations (ie CBDnxxxx keywords) required for a given calibration dataset depends upon the dataset itself, the characteristics of the specific instrument to which it refers, and the likelihood that other (Qual = 0) datasets with the same CCNMxxxx codename will ever exist in the archive at any time.
The following two detailed examples should help illustrate this point:
Example 1:
Consider an imaging instrument for which one requires to store a series of
point-spread-function psf calibration datasets for various off-axis
positions in the form of radial-profiles. However, it is known (or
suspected) that the psf is a function of energy, yet the energy
dependency has not (yet) been adequately parameterized such that the
datasets can be stored as a virtual calibration file and standalone software
task). One therefore wishes to store radial
profiles appropriate for several 'standard' energy ranges (eg in the 3
bands 0-1 keV, 1-2 keV & 3-3.5 keV) in separate files.
Each file would have the identical value of the CCNM0001
keyword, namely
CCNM0001 = 'R_PSF '
(Section A.1.14). In order to allow the CALDB
software to distinguish between the 3 files, each file header would have a
unique value of the CBD10001 keyword, such as:
CCNM0001 = 'R_PSF ' / radial point spread function CBD10001 = 'ENERG(0-1)keV ' / energy range appropriate to this rspffor file 1,
CCNM0001 = 'R_PSF ' / radial point spread function CBD10001 = 'ENERG(1-2)keV ' / energy range appropriate to this rspffor file 2, and
CCNM0001 = 'R_PSF ' / radial point spread function CBD10001 = 'ENERG(3-3.5)keV ' / energy range appropriate to this rspffor file 3.
Example 2:
Continuing from the above example, consider now that it is suspected
that the psf may also be a function of detector temperature. If
the above datasets were obtained at a detector temperature of 273 K,
each file could contain the header keyword CBD20001
='TEMP(273)K ' in order to document the detector temperature at
which the information in the file is appropriate.
Clearly the hardware and GOF teams will have the best idea as to which parameter boundaries are necessary for a given dataset, and thus the specification of of the necessary CBDnxxxx keyword values is primarily their responsibility. However, these teams are encouraged to refer to pre-existing calibration datasets within the CALDB and to the requirements of downstream software tasks prior to delivery to the HEASARC.
1It is anticipated that a
maximum of 9 will be easily
sufficient for all calibration datasets, though an extension making
n a hexadecimal number is possible if this is not the case
(however this is not implemented at the time of writing).