The grouping proposal provides several capabilities:
The last feature is becoming particularly useful as the fraction of data available on-line has increased and access from one computer to data on another has become routine. Related data may now be stored in separate locations and accessed electronically, instead of putting separate copies of all the related data on several machines.
Jennings et al. provide an illustration of where such a convention would be useful. Consider a set of observations, each of which has associated with it an observation log, event list, derived image, and calibration data, and for which many observations share the same calibration data. It would be possible to logically associate each (log, event list, image, calibration) set into a separate group; in addition, the same calibration data HDU could belong to many groups but would only need to be stored once. Another possible group would be one of observations of the same object at different times, and these observations could be combined into a group even though they might reside on multiple FITS files.
An extension HDU called a group table defines a group and its members. This table may be either an ASCII table extension (XTENSION= 'TABLE ') or a binary table (XTENSION= 'BINTABLE'). Group tables are required to contain the following keywords in the header:
EXTNAME = 'GROUPING' in a given FITS file must have a
different value of EXTVER. This number distinguishes the group
from any other defined in the file.
The following keyword is not required but is strongly recommended:
GRPNAME (character) provides a name for the group table. This name should contain only letters, digits, and underscore (hexadecimal 5F, decimal 95); in particular, it should not contain any embedded ASCII blanks (hexadecimal 20, decimal 32). The value is case-insensitive.
A group can contain any number of members. The members may be a mix of HDU types, in any order. They may be primary HDUs, extensions of types endorsed by the IAUFWG (currently TABLE, IMAGE, and BINTABLE), and other extensions that conform to the general rules for extensions provided in section 3.3 but have not been endorsed specifically by the IAUFWG. Member tables may be group tables, thus identifying subordinate groups. Group members can be identified by the group table in two ways: by reference or by position. Either or both can be used. Both have potential drawbacks. For identification by reference, the HDU is identified using the values of the XTENSION, EXTNAME, and EXTVER keywords. A possible difficulty is that there may be more than one HDU with these keywords in a previously created data set, making it impossible to identify the HDU uniquely. For identification by position, the numerical order of the HDU in the data set is specified. Caution is required in the use of this method because the order of HDUs in a FITS file may be changed when the file is copied. The location of group members not in the same file as the group table is specified by the World Wide Web Uniform Resource Identifier (URI). The table must specify the kind of URI being used: Uniform Resource Locator (URL), Uniform Resource Name (URN), or any future form of URI. The identification information is provided in columns of the group table with prescribed names, given as values of the TTYPEn keyword.
The following keywords are used to define columns of the group table if all or some group members are identified by reference:
'PRIMARY ' is be used. If no value is given, as when the
group table contains a mix of identifications by reference and by
position and the HDU is identified by position, an ASCII NULL
(hexadecimal 00, decimal 000) may be used.
The following keyword is used to define a column needed if all or some members are identified by position:
The following keywords are required if some or all of the group members are not in the same file as the group table:
If either of the above fields is undefined, the field should contain an ASCII NULL.
A group table may contain any number of additional, user-defined columns. Group table columns may appear in any order. The values of TTYPEn are not case-sensitive.
To permit inclusion of HDUs from existing FITS files in groups, the grouping proposal does not require any new keywords for group members. Use of the EXTNAME and EXTVAL keywords defined in section 3.3.2, the rules for generalized extensions, permitting identification by reference, is strongly recommended. Every member of a group located in a particular file should have a unique combination of XTENSION, EXTNAME, and EXTVER keywords. Group tables that are members should have a unique combination of EXTNAME and EXTVER keywords, and there should not be an ASCII group table and a binary group table with the same (EXTNAME, EXTVER) in the same file. In addition, the use of EXTNAME allows HDUs of a given extension type and structure to be identified by a common name.
Use of the following two keywords also is strongly recommended:
An HDU may be a member of many groups. If the HDU is a member of m groups, then there will be GRPID1 GRPIDm keywords, each identifying one of these groups. If the value of a particular GRPIDn is negative, it is the negative of the group identification number (the value of EXTVER in the group table), the group table is not in the same file as the member, and there will be a GRPLCn keyword with the URI where the group table is located.
The Jennings et al. proposal presents a number of illustrations. As of this writing, it is available at http://fits.gsfc.nasa.gov/group.html.