HCSS IA IO::FITS

The FitsArchive class provides a mechanism to store and retrieve HCSS Products in FITS format.
For a general discussion of the DP I/O framework, please read the general IO documentation first.

Contents

What is FITS
The role of this FITS Archive
Parameter Names
   Dictionaries
   Known Parameters
   Unknown Parameters
Composite Handling
Reserved FITS Keywords
Long Values
HIERARCH convention
Output Example

What is FITS?

The Flexible Image Transport System (FITS) is the format adopted by the astronomical community for data interchange and archival storage.

Click on the links below to obtain more information about FITS:
Definition External link to a document containing the format definition of the Flexible Image Transport System
FITS support External link that brings you to the FITS Support Office home pages.

The role of this FITS Archive

The FitsArchive is designed to cast an HCSS Product to file in FITS compliant format.

For more information see the Java Application Programmers Interface of this package. It includes code snippets written in Jython as well.

The FitsArchive class provides additional features that allow you to control the final format in the generated FITS file. These features are contained in what we call FITS rules.

Parameter Names

The current implementation of the FITS rules mentioned above allows you to convert long parameter names defined in the meta data of your product into a FITS-compliant notation. The latter dictates that keyword names must be uppercase, with a maximum length of eight characters.

Dictionaries

The FITS rules provide dictionaries that do the mapping for you. The idea is that one should use pretty names for your parameters, and the FITS rules mechanism will try to find an appropriate name that complies to the FITS standard.

This package provides the following dictionaries:
FITS standard Provides pretty names for FITS keywords that are part of the standard NOST 100-2.0.
HEASARC standard Provides pretty names for FITS keywords that have been widely used within the astronomical community. They are taken from HEASARC common FITS keywords.
HCSS standard Provides pretty names for FITS keywords that are common within the Herschel Interactive Analysis.

Known Parameters

The default behavior of the FITS rules is a concatenation of all dictionaries mentioned above. The system queries the HCSS dictionary first, then HEASARC and finally the standard dictionary. For example, the metadata parameter obsMode with value Pointed is translated to the followind in the FITS header:
   OBS_MODE= 'Pointed'
A further line in the header show the header keyword with the original metadata name:
   HIERARCH  key.OBS_MODE='obsMode'

Header lines beginning with HIERARCH reflect the mapping of the parameter names in your meta data as found in one of the used dictionaries. See also the HIERARCH convention.

Unknown Parameters

Parameter names for which the system can not find any suitable mapping get an ad-hoc unique name as shown in the following example. The original HCSS product has two custom metadata parameters, called MyFirstSpecial and MyLastSpecial, whose values are This keyword you would not find in the FITS dictionaries and Neither this one, respectively. These are the resulting lines in the FITS header:
   META_0 = 'This keyword you would not find in the FITS dictionaries'
   META_1 = 'Neither this one'
   :
   HIERARCH  key.META_0='MyFirstSpecial'
   HIERARCH  key.META_1='MyLastSpecial'

The META_xxx keyword is reserved by this package. (See HIERARCH convention also.)

Composite Handling

The FITS format is a flat format of what is called Header Data Units or HDUs. As a result it does not allow for composites (nested structures) such as a Product itself as well the CompositeDataset (both are defined in herschel.ia.dataset).

This imposes a problem: we try to map a nested structure on a flattened one. Though various proposals in the FITS world have been around to accomodate for this need, none of them seem elegant enough to be adopted as part of the FITS standard. This package is circumventing this problem by adding the following entries to the header part of a composite as follows:

   DSETS___=                    3 / Number of datasets
   DSET_0  =                    1 / HDU of Child Dataset
   DSET_1  =                    2 / HDU of Child Dataset
   DSET_2  =                    3 / HDU of Child Dataset
These reserved keywords refer to physical HDU locations of children datasets.

Reserved FITS Keywords

The FITS Archive may populate your FITS headers with additional information needed to restore your product from a FITS file. For such information this package reserves the following keywords:

Long string values and descriptions

Each header card of a FITS file consist of 80 characters, in which the keyword name, the parameter value and its unit and/or description are tried to be stored.

If a value of a StringParameter or a description does not fit in a single header card, it is automatically split in several lines. The way of doing so is based on the HFWG Recommendation R13, which is a convention for long string values, and an HCSS specific extension of it that is applied to the comments.

HIERARCH convention

HIERARCH convention (21-Sep-2009) is implemented for read operations only. It means that a FITS file that contains HIERARCH convention keywords will be read and translated into Herschel product metadata keywords.

When reading FITS keywords, Herschel product metadata keywords translation mechanism, explained in Known Parameters and Unknown Parameters has priority over the HIERARCH convention.

Write operations will follow the procedure explained in Parameter names. In other words, Herschel product metadata keywords will be translated into FITS keywords following the procedure explained in Parameter names.

Output Example

Below you will find an example of all the headers in a FITS file. It was generated using the default FITS rules.
SIMPLE  =                    T / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                   32
NAXIS   =                    0 / Dimensionality
EXTEND  =                    T / May contains datasets
TIMESYS = 'UTC     '           / All dates are in UTC time
LONGSTRN= 'OGIP 1.0'           / The OGIP long string convention may be used.
COMMENT This FITS file may contain long string keyword values that are
COMMENT continued over multiple keywords.  This convention uses the  '&'
COMMENT character at the end of a string which is then continued
COMMENT on subsequent keywords whose name = 'CONTINUE'.
          ---------------Herschel FITS Data Generator---------------
          This product is generated by Herschel software.
HCSS____=                    4 / HCSS Fits Product Version
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
CLASS___= 'herschel.ia.dataset.Product' / java representation
INFO____= 'FITS demonstration'
          -------------- Herschel Parameter Data--------------------
          All actual parameter names are converted to FITS compliant
          conventions. Note that the HIERARCH comments contain the
          appropriate key mapping
HIERARCH  key.META_0='type'
META_0  = 'Unknown '           / Product Type Identification
HIERARCH  key.CREATOR='creator'
CREATOR = 'You?    '           / Generator of this product
HIERARCH  key.DATE='creationDate'
DATE    = '2007-06-13T13:49:59.331000' / Creation date of this product
HIERARCH  key.INSTRUME='instrument'
INSTRUME= 'Unknown '           / Instrument attached to this product
HIERARCH  key.MODELNAM='modelName'
MODELNAM= 'demonstration'      / Model name attached to this product
HIERARCH  key.DATE-OBS='startDate'
DATE-OBS= '2007-06-13T13:49:59.331000' / Start date of this product
HIERARCH  key.DATE-END='endDate'
DATE-END= '2007-06-13T13:49:59.331000' / End date of this product
HIERARCH  key.META_1='sampleKeyword'
META_1  = 'This keyword you would not find in the FITS dictionaries'
HIERARCH  key.OBS_MODE='observationInstrumentMode'
OBS_MODE= 'UnitTest'
HIERARCH  key.META_2='longValue'                                                
META_2  = 'This value is so long that it is split in several lines, because it&'
CONTINUE  ' does not fit in a single header card' / &                          
COMMENT The description is also very long. Therefore, it is split in more than &
COMMENT one line too                                                            
          -----------------Dataset Children-------------------------
          Below you will find all HDU locations that are children of
          this composite dataset.
DSETS___=                    3 / Number of datasets
DSET_0  =                    1 / HDU of Child Dataset
DSET_1  =                    2 / HDU of Child Dataset
DSET_2  =                    3 / HDU of Child Dataset
END


XTENSION= 'IMAGE   '           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                  -64
NAXIS   =                    1 / Dimensionality
NAXIS1  =                   50
PCOUNT  =                    0 / No extra parameters
GCOUNT  =                    1 / One group
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
EXTNAME = 'myArray '           / name of this HDU
CLASS___= 'herschel.ia.dataset.ArrayDataset' / java representation
INFO____= 'range of real values'
DATA____= 'herschel.ia.numeric.Double1d' / java Data
QTTY____= 'eV      '           / Unit of the data
          -------------- Herschel Parameter Data--------------------
          All actual parameter names are converted to FITS compliant
          conventions. Note that the HIERARCH comments contain the
          appropriate key mapping
HIERARCH  key.TEMPERAT='temperature'
TEMPERAT=                  293 / [K] room temperature
END


XTENSION= 'BINTABLE'           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                    8
NAXIS   =                    2 / Dimensionality
NAXIS1  =                   16
NAXIS2  =                   50
PCOUNT  =                    0
GCOUNT  =                    1
TFIELDS =                    2
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
EXTNAME = 'myTable '           / name of this HDU
CLASS___= 'herschel.ia.dataset.TableDataset' / java representation
INFO____= 'This is a table'
          ---------------Herschel Column Information----------------
          Below follow additional fields to re-create the table
          columns into herschel.ia.dataset.Column objects
          * TTYPExxx - Column name
          * TCOLUxxx - Java Column container
          * TCLASxxx - Java ArrayData container
          * TFORMxxx - FITS column type
          * TDIMxxx  - FITS column dimensions
          * TUNITxxx - herchel.share.unit.Unit
TTYPE1  = 'x       '
TCOLU1  = 'herschel.ia.dataset.Column'
TCLAS1  = 'herschel.ia.numeric.Double1d'
TFORM1  = '1D      '
TDIM1   = '(1)     '
TTYPE2  = 'sin     '           / sin(x)
TCOLU2  = 'herschel.ia.dataset.Column'
TCLAS2  = 'herschel.ia.numeric.Double1d'
TFORM2  = '1D      '
TDIM2   = '(1)     '
END


XTENSION= 'IMAGE   '           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                   32
NAXIS   =                    0 / Dimensionality
PCOUNT  =                    0 / Mandatory FITS keyword
GCOUNT  =                    1 / Mandatory FITS keyword
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
EXTNAME = 'myNest  '           / name of this HDU
CLASS___= 'herschel.ia.dataset.CompositeDataset' / java representation
INFO____= 'As a composite, I contain three datasets!'
          -------------- Herschel Parameter Data--------------------
          All actual parameter names are converted to FITS compliant
          conventions. Note that the HIERARCH comments contain the
          appropriate key mapping
HIERARCH  key.EXPOSURE='exposureTime'
EXPOSURE=                 10.0 / [] duration
          -----------------Dataset Children-------------------------
          Below you will find all HDU locations that are children of
          this composite dataset.
DSETS___=                    3 / Number of datasets
DSET_0  =                    4 / HDU of Child Dataset
DSET_1  =                    5 / HDU of Child Dataset
DSET_2  =                    6 / HDU of Child Dataset
END


XTENSION= 'IMAGE   '           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                  -64
NAXIS   =                    1 / Dimensionality
NAXIS1  =                   50
PCOUNT  =                    0 / No extra parameters
GCOUNT  =                    1 / One group
EXTNAME = 'childArray'         / name of this HDU
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
CLASS___= 'herschel.ia.dataset.ArrayDataset' / java representation
INFO____= 'range of real values'
DATA____= 'herschel.ia.numeric.Double1d' / java Data
QTTY____= 'eV      '           / Unit of the data
          -------------- Herschel Parameter Data--------------------
          All actual parameter names are converted to FITS compliant
          conventions. Note that the HIERARCH comments contain the
          appropriate key mapping
HIERARCH  key.TEMPERAT='temperature'
TEMPERAT=                  293 / [K] room temperature
END


XTENSION= 'BINTABLE'           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                    8
NAXIS   =                    2 / Dimensionality
NAXIS1  =                   16
NAXIS2  =                   50
PCOUNT  =                    0
GCOUNT  =                    1
TFIELDS =                    2
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
EXTNAME = 'childTable'         / name of this HDU
CLASS___= 'herschel.ia.dataset.TableDataset' / java representation
INFO____= 'This is a table'
          ---------------Herschel Column Information----------------
          Below follow additional fields to re-create the table
          columns into herschel.ia.dataset.Column objects
          * TTYPExxx - Column name
          * TCOLUxxx - Java Column container
          * TCLASxxx - Java ArrayData container
          * TFORMxxx - FITS column type
          * TDIMxxx  - FITS column dimensions
          * TUNITxxx - herchel.share.unit.Unit
TTYPE1  = 'x       '
TCOLU1  = 'herschel.ia.dataset.Column'
TCLAS1  = 'herschel.ia.numeric.Double1d'
TFORM1  = '1D      '
TDIM1   = '(1)     '
TTYPE2  = 'sin     '           / sin(x)
TCOLU2  = 'herschel.ia.dataset.Column'
TCLAS2  = 'herschel.ia.numeric.Double1d'
TFORM2  = '1D      '
TDIM2   = '(1)     '
END


XTENSION= 'IMAGE   '           / Java FITS: Wed Jun 13 15:49:59 CEST 2007
BITPIX  =                   32
NAXIS   =                    0 / Dimensionality
PCOUNT  =                    0 / Mandatory FITS keyword
GCOUNT  =                    1 / Mandatory FITS keyword
          -------------- Herschel Structure Data--------------------
          Following fields are private to the structure of the
          Java object this HDU is representing.
EXTNAME = 'childNest'          / name of this HDU
CLASS___= 'herschel.ia.dataset.CompositeDataset' / java representation
INFO____= 'Empty child, just to prove nesting'
END