HEASARC Calibration Memo CAL/GEN/92-011
Required and Recommended FITS keywords for Calibration Files
SUMMARY
| |
This document gives a list of FITS keywords which are required or
recommended to be included in any calibration data files to be
incorporated into the HEASARC CALDB. The defined values of each keyword are also given.
Intended audience: primarily HEASARC programmers, authors of
calibration files & downstream software.
|
| |
Log of Significant Changes to this document
| Release Date | Sections Changed | Brief Notes |
| 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 |
| 2016 Jul 08 | All | minor corrections/clarifications by MFC |
Contents
1 INTRODUCTION
2 REQUIRED KEYWORDS
3 RECOMMENDED KEYWORDS
A DEFINED CCNM0001 VALUES
A.1 Multi-Mission/Multi-Instrument Values of CCNM0001
A.1.1 CCNM0001 = 2D_PSF
A.1.2 CCNM0001 = COLLRESP
A.1.3 CCNM0001 = DETEFF
A.1.4 CCNM0001 = DET_EFF
A.1.5 CCNM0001 = EEF
A.1.6 CCNM0001 = DETMAP
A.1.7 CCNM0001 = EBOUNDS
A.1.8 CCNM0001 = EFFAREA
A.1.9 CCNM0001 = ENERGY_GRID
A.1.10 CCNM0001 = FATOM or WATOM
A.1.11 CCNM0001 = FTRANS or WTRANS
A.1.12 CCNM0001 = HKCONV
A.1.13 CCNM0001 = MATRIX
A.1.14 CCNM0001 = RPSF
A.1.15 CCNM0001 = SPECRESP
A.1.16 CCNM0001 = SPECRESP MATRIX
A.1.17 CCNM0001 = TVIGNET
A.1.18 CCNM0001 = VIGNET
A.1.19 CCNM0001 = WATOM
A.1.20 CCNM0001 = WTRANS
A.1.21 CCNM0001 = XSECT
A.1.22 CCNM0001 Values for Coordinate Transformations
A.2 Proposed CCNM0001 values
A.2.1 CCNM0001 = BADPIX
A.2.2 CCNM0001 = BKGRND_EVTS
A.2.3 CCNM0001 = BKGRND_EVTS_DARKEARTH
A.2.4 CCNM0001 = BKGRND_EVTS_BRIGHTEARTH
A.2.5 CCNM0001 = DETMSK
A.2.6 CCNM0001 = DET_ENRES
A.2.7 CCNM0001 = DET_GAIN
A.2.8 CCNM0001 = DET_POSCORR
A.2.9 CCNM0001 = DET_POSRES
A.2.10 CCNM0001 = OBSCFACT
A.2.11 CCNM0001 = TEMP
A.3 Mission/Instrument Specific Values of CCNM0001
A.3.1 CCNM0001 = ASCALIN
A.3.2 CCNM0001 = ASCALIN_FLF
A.3.3 CCNM0001 = ASCALIN_POW2
A.3.4 CCNM0001 = EDS_COR
A.3.5 CCNM0001 = GRIDTRNS
A.3.6 CCNM0001 = PART_BKGD_MAP_AP
A.3.7 CCNM0001 = PART_BKGD_MAP_EXT
A.3.8 CCNM0001 = PART_BKGD_MAP_INT
A.3.9 CCNM0001 = RTIBOUNDS
A.3.10 CCNM0001 = SGC_E
A.3.11 CCNM0001 = SGC_POS
A.3.12 CCNM0001 = WINTHICK
A.3.13 CCNM0001 = WC_E
A.3.14 CCNM0001 = WC_POS_X
A.3.15 CCNM0001 = WC_POS_Y
B THE CALIBRATION BOUNDARY KEYWORDS
B.1 Naming scheme for the boundary keywords
B.2 Number of keywords
B.3 CBD Keyword Values
B.3.1 NULL Values
B.3.2 Syntax of the CBDnxxxx boundary keywords
B.3.3 Examples
B.4 Allowed formats of expr
B.5 The Number of Limitations Required
1 INTRODUCTION
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 ingest of calibration datasets into the HEASARC CALDB,
it is the responsibility of suppliers of calibration datasets to
ensure the appropriate keywords are present and that 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.
2 REQUIRED KEYWORDS
The following keywords (also listed in Table 2)
are required if a calibration data file is to be indexed in the
Calibration Index File (CIF):
- TELESCOP - the name of the satellite/mission.
Defined values are given in HEASARC/93-013 (George & Angelini 1993,
available on-line as
postscript
and
html
versions).
Value to be inserted into TELESCOPE column of the CIF.
- INSTRUME - the name of the instrument.
Defined values are given in OGIP/93-013 (George & Angelini 1993).
Value to be inserted into INSTRUME column of the CIF.
- DETNAM - (if applicable) the name of the detector,
required only in cases where the value of
the INSTRUME keyword is insufficient.
Defined values are given in OGIP/93-013 (George & Angelini 1993).
Value to be inserted into DETNAM column of the CIF.
- FILTER - (if applicable) the name of the filter in use.
This keyword is not required for instruments without a
moveable filter or for calibration data files for which
filter information is not relevant.
Defined values are given in OGIP/93-013 (George & Angelini 1993).
Value to be inserted into FILTER column of the CIF.
- CCLS0001 - the HEASARC-specified "class" of this calibration file.
Defined values:
- CCLS0001 = 'PCF';
dataset is a Primary Calibration File
- CCLS0001 = 'BCF';
dataset is a Basic Calibration File
- CCLS0001 = 'CPF';
dataset is a Calibration Product File
- CCLS0001 = 'USR';
dataset has been constructed by a User, and
is not part of the official HEASARC calibration
database.
Value to be inserted into CAL_CLAS column of the CIF.
- CDTP00001 - code describing whether the 'calibration dataset'
consists of real data, or 'virtual' data (ie a taskname and associated
parameter inputs - see also CAL/GEN/92-013, George, Zellar & White 1993).
Allowed values:
- CDTP0001 = 'DATA';
dataset contains calibration data
- CDTP0001= 'TASK';
dataset contains a task name and associated
input parameters values.
Value to be inserted into CAL_DTYP column of the CIF.
- CCNM0001- codename of the dataset to be used within
CIF to describe the contents (for downstream software).
Allowed values: see Section A at the end of this document
Value to be inserted into CAL_CNAM column of the CIF.
- CBDnxxxx - string giving parameter limitations on dataset
(if any) to be used within
CIF to further describe the contents for downstream software
(in association with the value of the CCNMxxxx keyword).
Allowed values: see Section B at the end of this document
Value to be inserted into CAL_CBD column of the CIF.
- CVSD0001 - the UTC date (in either dd/mm/yy or
yyyy-mm-dd format) when this calibration data should first be used.
Value to be inserted into CAL_VSD column of the CIF.
- CVST0001- the UTC time (in hh:mm:ss format) on
the day CVSDxxxx when this calibration data should first be used.
Value to be inserted into CAL_VST column of the CIF.
- CDESxxxx - a string giving a brief descriptive summary of this
dataset.
Value to be inserted into CAL_DESC column of the CIF.
where xxxx is a number of the form 0001,
0002, 0003 etc and
n a single-digit integer between 1 and 9.
The xxxx values are used
to identify the respective set of keywords associated with each dataset
should 2 or more datasets be included within in single extension.
In the vast majority of cases, only one calibration dataset is stored in
a given extension (indeed, this is strongly recommended), thus
xxxx = 0001 can be used.
The use of the n digit is described in Section B.
Table 1: Required Keywords for Calibration Datasets
| 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 |
| | |
3 RECOMMENDED KEYWORDS
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.
- CTELxxxx - the name of the satellite/mission.
This keyword is useful if the calibration dataset in a given extension
is applicable to more than one X-ray mission; for example, a table of
atomic constants which are used by both ROSAT and ASCA should have
CTEL0001= 'ROSAT ' / used applicable to the ROSAT mission
CTEL0002= 'ASCA ' / data applicable to the ASCA mission
Defined values are the same as those used for the TELESCOP
keyword and are given in HEASARC/93-013 (George & Angelini 1993).
- CINSxxxx - the name of the instrument.
This keyword is useful if the calibration dataset in a given extension
is applicable to more than one X-ray instrument; for example, a table of
gains which are used by both SIS0 and SIS1 on ASCA should have
CINS0001= 'SIS0 ' / used applicable to the SIS0
CINS0002= 'SIS1 ' / data applicable to the SIS1
The values of these keywords are the same as those for the INSTRUME
keyword as given in OGIP/93-013 (George & Angelini 1993)
- CDTnxxxx - (if necessary) the name of the detector,
required only in cases where the value of
the INSTRUME keyword is (or the CTELxxxx
keywords, if present, are) insufficient to fully identify the
calibration data. n is an integer from 1-9 which identifies the
instrument, while the xxxx are indices which identify the individual
detector. For example an effective area curve applicable to CCD
chips 0,2 and 4 of the ASCA SIS0 and chip 1,3 of SIS1 would have:
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).
- CFInxxxx -the name of the filter in use for detector
xxxx of instrument n. This keyword is not to be used for
instruments without a moveable filter or for calibration data files
for which filter information is not relevant. Values should be the
same as those used for the FILTER keyword, as 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.
Table 2: Recommended Keywords for Calibration Datasets
| 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) |
| |
REFERENCES
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
USEFUL LINKS TO OTHER HTML PAGES
The following useful links are available (in the HTML version of this
document only):
A DEFINED CCNM0001 VALUES
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.
A.1 Multi-Mission/Multi-Instrument Values of CCNM0001
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.
Table 3: Multi-mission Values of CCNM0001 Currently in Use at
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 |
| | |
A.1.1 CCNM0001 = 2D_PSF
Dataset contains a 2-dimensional mini-image of the point spread function,
centered on the peak, and normalized to one detected photon.
A.1.2 CCNM0001 = COLLRESP
Collimator Response
A.1.3 CCNM0001 = DETEFF
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).
A.1.4 CCNM0001 = DET_EFF
Deprecated; same as DETEFF
A.1.5 CCNM0001 = EEF
Dataset contains a (1-dimensional) encircled energy fraction profile of the
the point spread function, constructed using concentric annuli centered
on the peak.
A.1.6 CCNM0001 = DETMAP
Detector Map
A.1.7 CCNM0001 = EBOUNDS
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).
A.1.8 CCNM0001 = EFFAREA
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).
A.1.9 CCNM0001 = ENERGY_GRID
Contains the lower and upper boundaries to the standard
incident energy grid used for many PSPC calibration files.
A.1.10 CCNM0001 = FATOM or WATOM
Data table consists of one or both of 2 (optional) calibration datasets:
- the mass absorption coefficient of each chemical component within
the filter/window as a function of energy
- the effective thickness of each chemical component within the
filter/window as a function of position.
Detailed file formats are given in
CAL/GEN/92-023 (George & Zellar 1992).
A.1.11 CCNM0001 = FTRANS or WTRANS
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).
A.1.12 CCNM0001 = HKCONV
Dataset is in a highly instrument-specific format, and contains
information necessary to convert satellite housekeeping information
to physical units.
A.1.13 CCNM0001 = MATRIX
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:
- Detector Gain (ie given the basic energy→channel
relationship.
- Detector Energy Resolution (including escape peaks, partial charge
tails etc)
Use: Spectral analysis of PHA data (in conjunction with an ARF containing
CCNM0001 = 'SPECRESP' dataset).
Usual Origin: MATRIX extension within an RMF.
See CAL/GEN/92-002 (George et al. 1992) and its addendum, CAL/GEN/92-002a
(George & Arnaud 1993).
A.1.14 CCNM0001 = RPSF
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.
A.1.15 CCNM0001 = SPECRESP
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:
- Effective Area of the Telescope/Collimator (including vignetting)
- Filter Transmission (if any)
- Detector Window Transmission
- Detector Efficiency
- any additional energy dependent effects (eg
corrections due to the psf)
Use: Spectral analysis of PHA data (in conjunction with an RMF containing
CCNM0001 = 'MATRIX' dataset).
Usual Origin: 'SPECRESP' extension within an ARF.
See CAL/GEN/92-002 (George et al. 1992) and its addendum, CAL/GEN/92-002a
(George & Arnaud 1993).
A.1.16 CCNM0001 = SPECRESP MATRIX
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:
- Detector Gain (ie given the basic energy→channel
relationship.
- Detector Energy Resolution (including escape peaks, partial charge
tails etc)
- Effective Area of the Telescope/Collimator (including vignetting)
- Filter Transmission (if any)
- Detector Window Transmission
- Detector Efficiency
- any additional energy dependent effects (eg
corrections due to the psf)
(thus a combination of the information alternatively contained within
CCNM0001 = 'MATRIX' and
CCNM0001 = 'SPECRESP' datasets).
Use: Spectral analysis of PHA data.
Usual Origin: MATRIX extension within an RMF.
Generally not recommended.
See CAL/GEN/92-002 (George et al. 1992) and its addendum, CAL/GEN/92-002a
(George & Arnaud 1993).
A.1.17 CCNM0001 = TVIGNET
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).
A.1.18 CCNM0001 = VIGNET
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).
A.1.19 CCNM0001 = WATOM
Same as FATOM
A.1.20 CCNM0001 = WTRANS
Same as FTRANS
A.1.21 CCNM0001 = XSECT
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.
A.1.22 CCNM0001 Values for Coordinate Transformations
Table 4: Example CCNM0001 values containing coordinate transformations
| CCNM0001 | Coordinate |
| Transformation |
| value | from | to |
| | |
| RAW2PHY | Raw Detector | Physical Detector |
| RAW2LIN | Raw Detector | Linearized Detector |
| PHY2ECL | Physical Detector | (Celestial) Ecliptic |
| | |
A.2 Proposed CCNM0001 values
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.
A.2.1 CCNM0001 = BADPIX
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).
A.2.2 CCNM0001 = BKGRND_EVTS
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
A.2.3 CCNM0001 = BKGRND_EVTS_DARKEARTH
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,
A.2.4 CCNM0001 = BKGRND_EVTS_BRIGHTEARTH
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,
A.2.5 CCNM0001 = DETMSK
Dataset is 2-dimensional listing the unobscured regions of an
imaging detector.
A.2.6 CCNM0001 = DET_ENRES
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
A.2.7 CCNM0001 = DET_GAIN
Dataset contains the gain of the detector.
The format and details of precisely what values are stored
are considered detector-specific
A.2.8 CCNM0001 = DET_POSCORR
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
Table 5: Proposed List of MULTI-MISSION Values for CCNM0001
| 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 |
| |
A.2.9 CCNM0001 = DET_POSRES
Dataset contains the position resolution of the detector.
The format and details of precisely what values are stored
are considered detector-specific
A.2.10 CCNM0001 = OBSCFACT
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).
A.2.11 CCNM0001 = TEMP
Dataset is a simple list of (detector) temperature vs time.
A.3 Mission/Instrument Specific Values of
CCNM0001
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.
A.3.1 CCNM0001 = ASCALIN
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.
A.3.2 CCNM0001 = ASCALIN_FLF
This is a non-standard codename, only used for the
ASCA/GIS.
A.3.3 CCNM0001 = ASCALIN_POW2
This is a non-standard codename, only used for the
ASCA/GIS. It represent GIS raw to linearized coordinate
transformation maps.
Table 7: MISSION-SPECIFIC Values of CCNM0001 used at the
HEASARC CALDB
| 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 |
| | |
A.3.4 CCNM0001 = EDS_COR
XTE/PCA EDS gain corrections
A.3.5 CCNM0001 = GRIDTRNS
This is a non-standard codename, only used for the
ASCA/GIS. It represents the transmission for the GIS2 window grid
A.3.6 CCNM0001 = PART_BKGD_MAP_AP
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
A.3.7 CCNM0001 = PART_BKGD_MAP_EXT
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.
A.3.8 CCNM0001 = PART_BKGD_MAP_INT
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.
A.3.9 CCNM0001 = RTIBOUNDS
This is a non-standard codename, only used for the ASCA/GIS.
This type of file should be used to reject GIS background events based on
their invariant rise-time (RTI) values. (RTI values are RT values
which have been corrected for any intrinsic position dependent
fluctuations by the GISLIN task.) Therefore, this file should only be
applied to corrected science extension data.
A.3.10 CCNM0001 = SGC_E
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
A.3.11 CCNM0001 = SGC_POS
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
A.3.12 CCNM0001 = WINTHICK
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
A.3.13 CCNM0001 = WC_E
ROSAT PSPC Window Correction: Energy-dependent correction term.
A.3.14 CCNM0001 = WC_POS_X
ROSAT/PSPC Window Correction, X-dependent terms
A.3.15 CCNM0001 = WC_POS_Y
ROSAT/PSPC Window Correction, Y-dependent terms
B THE CALIBRATION BOUNDARY KEYWORDS
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.
B.1 Naming scheme for the boundary keywords
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.
B.2 Number of keywords
By default the CALDB software can accomodate up to nine of these keywords.
B.3 CBD Keyword Values
B.3.1 NULL Values
It is required that at least one CDBnxxxx keywords be defined. Defining more than one of the CDBnxxxx is optional. It is recommended that software which writes calibration FITS files to include all 9 CBD keywords all FITS headers. Unused boundary keywords should be filled with the NULL boundary value, which 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.
B.3.2 Syntax of the CBDnxxxx boundary keywords
The value of each CBDnxxxx keyword is
a character string which refers to a
different dimension of parameter space, and has the following format:
|
CBDnxxxx = ′expr(VALDES1,VALDES2,...,VALDESj)units′ |
| (1) |
where expr is a special character string describing the boundary
parameter, VALDESj is the jth value descriptor specifying the set
of values for which the parameter is valid, and units is the physical
units of VALDESj.
The allowed values of expr are listed in Section B.4,
and the allowed values of the units string are as for the
TUNITSn keyword
and summarized in OGIP/93-001 (George & Angelini 1994).
Each of the value descriptors, VALDESj, can have four possible forms,
any of which can be included/combined in the same CBDnxxxx keyword
value:
- VALDESj = m.n
representing a single real number, m.n, for which the boundary
parameter is valid. Only a single integer m need to specified in
the case of an integer boundary value.
- VALDESj = minval:maxval or VALDESj = minval−maxval
representing a range of continuous values between minval and
maxval (where minval and maxval both have the form m.n
given above) for which the boundary parameter is valid.
- VALDESj = cstr
representing a single character string, cstr
for which the(character) boundary parameter is valid.
In this syntax, double quotes (") can be included as
the first and last characters of cstr to force a value
to be interpreted as a string. The double quotes are
required if cstr would otherwise be interpreted as either a
single integer/real or as a ranges of integers/reals.
- VALDESj = BOOLEAN
representing a single character string, either T or F representing
the boolean value "true" or "false", respectively. This
syntax is useful is the data is only valid when a certain
indicator or status flag (for eg. high voltage "on" status) is
true.
Examples of these formats are given below.
B.3.3 Examples
- CBDnxxxx = 'THETA(0,5)deg'
indicates that the dataset is valid for the parameter
THETA at 0.0 degrees and at 5.0 degrees, but is NOT
valid for the range 0.0 < THETA < 5.0 degrees.
'THETA(0.0,5.0)deg', 'THETA(0.0,5)deg',
'THETA(0,5.0)deg' are equivalent.
- CBDnxxxx = 'THETA(0-5)deg'
indicates that the dataset is valid for all values of the parameter
THETA in the range
0.0 ≤ THETA ≤ 5.0
degrees.
'THETA(0.0-5.0)deg', 'THETA(0.0-5)deg',
'THETA(0-5.0)deg' are equivalent.
- CBDnxxxx = 'PARAM(LOW,HIGH)'
indicates that the dataset is valid for values of the parameter
PARAM equal to 'LOW' or 'HIGH', but is NOT
valid for any other values such as (say) 'MEDIUM'.
'PARAM("LOW",HIGH)', 'PARAM(LOW,"HIGH")'
'PARAM("LOW","HIGH")' are equivalent.
- CBDnxxxx = 'GRADE("0234")'
indicates that the dataset is valid for values of the
character-string parameter
GRADE equal to the character string value '0234' (only)
Here the double quotes are required. Without them, the dataset
would be incorrectly interpreted as valid for GRADE=234.0.
- CBDnxxxx = 'PARAM("0234",0,2-4)'
demonstrates a combination of the above VALDESj types
within a single CBDnxxxx keyword. The example indicates
that a dataset is valid for the parameter PARAM
equal to the string '0234', but also valid for PARAM=0.0
and 2.0 ≤ PARAM ≤ 4.0. While allowed, no
requirement for a mixing of strings & numerical values has
yet been encountered and is therefore strongly discouraged.
- CBDnxxxx = 'HIGH_VOLTAGE_STATUS(T)'
indicates
that the dataset is only valid if the high voltage status is TRUE
B.4 Allowed formats of expr
Table 8: Example pname values for the CBDnxxxx keyword
| 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 |
| | |
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'
B.5 The Number of Limitations Required
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 rspf
for file 1,
CCNM0001 = 'R_PSF ' / radial point spread function
CBD10001 = 'ENERG(1-2)keV ' / energy range appropriate to this rspf
for file 2, and
CCNM0001 = 'R_PSF ' / radial point spread function
CBD10001 = 'ENERG(3-3.5)keV ' / energy range appropriate to this rspf
for 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.
Footnotes:
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).
File translated from
TEX
by
TTH,
version 4.08.
On 8 Jul 2016, 16:36.