Data Interface Dictionary

The DID module of the DIT Sub-Component (ifw-core/dit/did), provides tools to handle Data Interface Dictionaries (DIDs).

The purpose of the DIDs is to define the parameters, which are written in the data product meta data section. This is normally the FITS keywords in the FITS data files.

This mainly consists in the following operations:

Loading dictionaries.

Looking up keywords.

Filtering out sets of keywords.

The Doxygen documentation for the Core DID package is available here.

At this point in time, it is only foreseen to use DIDs to assist generating ‘ESO compliant’ FITS files.

Note

Up to IFWv4, the dictionary format was based on a temporary YAML format. After the release of IFWv4, the format has been changed to use the CII Configuration Service. This means that existing dictionaries, based on the previous, temporary format, will have to be ported. This must be done manually.

Data Interface Dictionary - Format

The DID format is based on the CII Configuration Service.

An example of a DID is shown in the following (extract from “primary.did.yaml”):

!cfg.include schema/ifw/core/dit/did/did.schema.yaml:

#===============================================================================
header: !cfg.type:DidHeader
  name: dictionary/dit/stddid/primary.did.yaml
  scope: Generic
  description: |
    Dictionary defining the non-hierarchical keyword cards used in ESO FITS files.
    DICB: Reviewed for compliance with ESO-044156/7.
#===============================================================================

#===============================================================================
# Mandatory keywords:
#===============================================================================
SIMPLE: !cfg.type:DidBoolKey
  comment: Standard FITS
  description: |
    SIMPLE must be equal to 'T' to conform to FITS.
#-------------------------------------------------------------------------------
BITPIX: !cfg.type:DidIntKey
  comment: Nb of bits per pixel value
  description: |
    Number of bits used to store pixel values
    See Definition of FITS -- IAUFWG 3.0 (July 2008)
    The only valid values are:
      8  character of unsigned binary integer
      16  16-bit twos-complement binary integer
      32  32-bit twos-complement binary integer
     -32  IEEE single precision floating point
     -64  IEEE double precision floating point
#-------------------------------------------------------------------------------
# ...

An example of a keyword definition of an ESO hierarchical keyword, is shown here:

INS(#) FILT# ID: !cfg.type:DidStrKey
  comment: Filter ID (test.did.yaml)
  description: |
    This is a description,
    of the "INS# FILT# ID" key,
    stretching over several lines.

As can be seen, it is possible to specify that a keyword has an index, appending “#” to the keyword component.

If the “#” is contained in parenthesis, the index is optional. The keyword above, can be looked up as e.g. “INS FILT2 ID” or “INS1 FILT2 ID”.

The module hosting the DID documents, shall typically be structured as follows (example):

<path>/<project>/<package>/<module>/resource/dictionary/<package>/<module>/<DID name>.did.yaml

Note

Note, it is proposed to use extension “.did.yaml” for DIDs.

An example of how to configure a module, which only provides DID files, can be found here:

https://gitlab.eso.org/ifw/ifw-core/-/tree/master/dit/did/stddid/resource/dictionary/ifw/core/dit/stddid

DID Header Fields

The properties of the fields of the DID header, are as follows:

header	Marks the beginning of the header segment.
name	The name of the DID, typically the name in the module under the “resource/dictionary” directory, e.g. “<package>/<module>/<DID name>.did”.Flexible Image Transportation System
scope	User defined. Could be e.g. “FCF FITS” or “FCF Ops Logs”.
description	Description of the DID.

DID Record Fields

The properties of the fields of the DID Keyword Record, are as follows:

<keyword>	The keyword itself. No specific casing is assumed, but a hierarchical structure of the keys is supported. E.g. “Detector#.Window#.StartX” or “INS# FILT# ID”. The DID Class interprets “.” (dot) and “ “ (space) as separators of the elements, which form the keyword. The hash sign (“#”) shown above, indicates that the component of the keyword has an index. The indeces must be in the internal “[0; oo[“. A future extension will allow to specify that a component of a keyword, may have an index as follows: “INS(#) FILT(#) ID”. This means that the keyword components may be used with an index or not. If the hash sign is defined like this “INS#”, that component must have an index, otherwise it is illegal.Marks the beginning of the header segment.
format	Format of the value when generating a keyword line. Based on the C ‘printf()’ formatting, leaving out the “%”. Only limited support at this point. Only relevant for double type.
unit	The unit of the value represented by the keyword. No specific checks of the value of this field is provided, but SI units shall be used, when possible. Not relevant for boolean.
comment	The comment field as it will be written when generating a keyword line.
description	Detailed description of the Keyword Record.

Header Files, Library & Namespace

The following header files are provided by the “ifw::core::dit::dit” module:

The library for the Core DID module is named: “coreDitDidlib”.

The namespace prefix is “ifw::core::dit::did”.

Classes

The DID module provides the following classes:

Example

The usage of the library is straightforward, but the following small example, provides an impression how to use it:

#include "ifw/core/dit/did/did.hpp"

dit::did::Did did;
did.Load("prj/pkg/mod/Test.did");

// Print out the headers of the DIDs loaded.
dit::did::Header::DidHdrField hdr_fields = static_cast<dit::did::Header::DidHdrField>
        (dit::did::Header::DID_HDR_FIELD_NAME |
         dit::did::Header::DID_HDR_FIELD_SCOPE |
         dit::did::Header::DID_HDR_FIELD_CRE_DATE |
         dit::did::Header::DID_HDR_FIELD_INCLUDE |
         dit::did::Header::DID_HDR_FIELD_DESCRIPTION);
for (auto it = did.GetHeaders().begin(); it != did.GetHeaders().end(); it++) {
    std::cout << std::endl << it->Print(hdr_fields) << std::endl;
}

// Print out entire DID, including header of main DID loaded.
std::cout << std::endl << did.Print(dit::did::Did::DID_HDR_LAST) << std::endl;

// Look up a single Keyword Record.
dit::did::Record record;
did.LookUp("INS1.LAMP3.NAME", record);
std::cout << std::endl << record.Print()) << std::endl;

// Look up multiple records.
ctd::defines::List<dit::did::Record> records;
did.LookUp("INS1.LAMP2.*", records);
std::cout << std::endl << dit::did::Record::PrintRecords(records)) << std::endl;

Standard Dictionaries

The following standard dictionaries are provided:

Data Products DID: FITS keywords for the DPR category.

Observation Info DID: FITS keywords for the OBS category.

Primary DID: Contains definition of (non-hierarchical) standard keywords for the FITS headers.

TPL DID: TPL category FITS keys.