Index Header Keywords

This implementation uses the FITS binary table extension format (XTENSION= 'BINTABLE') to store the table index information. In addition to the mandatory and reserved keywords that apply to all FITS binary table extensions a number of other keywords are defined here and have a reserved meaning within this convention, as described below:

EXTNAME = '         '   / TABLE_INDEX, TIME_INDEX or SPATIAL_INDEX (required)

The EXTNAME keyword may have one of 3 values under this convention. First, there are 2 common sub-types of indices that are given specific names: EXTNAME = 'TIME_INDEX' should be used for a 1-dimension index on a time-ordered column; EXTNAME = 'SPATIAL_INDEX' should be used for a 2-dimensional index on 2 spatial position columns (e.g., 'X' and 'Y' columns). Indices that do not fall under one of these 2 subclasses should be given the generic name 'TABLE_INDEX'. These 3 names are not case-sensitive and may be specified using any mixture of upper and lower case letters.

DATE    = '1996-11-19T13:37:34' / date and time of index creation (optional)

The DATE keyword records the time that the index was created. This date may be used to help verify that the index is still valid. If, for example, the indexed table has a creation date later than the date of the index, then this may be an indication that the index is obsolete.

INDTABLE= `myfile.fits:BINTABLE:EVENTS:1' / name of indexed table (optional)

The naming convention used here conforms to that used in the Jennings et al. FITS file grouping proposal (http://adfwww.gsfc.nasa.gov/other/convert/group.html). Basically, the value of this keyword gives the name of the FITS file followed by the value of the XTENSION, EXTNAME, and EXTVERS keywords in the table that is indexed. In general the table name is considered case sensitive. Other examples of the INDTABLE keyword are:

INDTABLE= 'http://mycomp.stateu.edu/user/data/filename.fits:BINTABLE:EVENTS:1' 
INDTABLE= '/user/data/filename.fits:BINTABLE:EVENTS:1'  / full path
INDTABLE= 'filename.fits:BINTABLE:EVENTS:1'             / filename only
INDTABLE= ':BINTABLE:EVENTS:1'    / table and index are in the same FITS file

If the event list is split into more than one physical FITS table, then 'INDTABLE' becomes a column in the index table rather than a keyword and the individual table name for each bin of the index is than listed in the body of the index table. (See example 5 below). Note that this keyword is considered optional because other conventions may be used to associate a particular table with its index. In particular the file grouping proposal mentioned above provides a general mechanism for constructing hierarchical associations of FITS header-data units.

INDCHECK= '      1490'        / checksum of the indexed table data (optional)

The value of the INDCHECK keyword may be compared to the computed checksum of the indexed event list data (not including the header keywords) to verify that the event list has not been modified subsequent to creating the index. If the event list is split into more than one physical FITS table, then 'INDCHECK' becomes a column in the index table rather than a keyword. Note that the checksum value is an unsigned integer, but it is represented as a character string (i.e., enclosed in quotes) because the value of the integer may be too large to be stored in the native integer format on some computer systems.

IAXIS   = (positive integer) / index dimensionality: 1, 2, ... (required)

The IAXIS keyword gives the dimensionality, or number of axes, in the index. In most cases the value will be either 1 (e.g., for an index on the TIME column) or 2 (e.g., for a spatial index on a pair of coordinate columns).

IAXISn  = (positive integer) / number of bins along each index axis (required)

The value of this indexed keyword contains the length (number of bins) along the corresponding axis of the index. Ordinarily, the value of these keywords corresponds to the number of rows in the index so that the total number of rows in the index (as given by the NAXIS2 keyword) is equal to the product of all the IAXISn keyword values. As discussed below, however, it is possible to compress the size of the index by deleting all the index bins which contain no events in which case NAXIS2 will be less than the product of the IAXISn keywords.

ITYPEn  = 'column name'      / column name of index axis n  (required)

The ITYPEn keyword gives the name of the column in the indexed table (as given by the TTYPEn keyword) corresponding to this axis of the index. The specified column name is not case sensitive. In the special case where the event list is not sorted and is simply indexed on row number, then INDTABLE will have the reserved value of '(row#)' or '(ROW#)'. (See example 6).

ISTRTn  = (float value) / first inclusive value of first index bin (required)

The ISTRTn keyword gives the starting inclusive value for the first index bin along the corresponding axis of the index. It is used in combination with the IDELTn keyword to determine the range of values in each bin of the index.

IDELTn  = (float value) / width of bins along this index axis (required)

The IDELTn keyword gives the width (or delta) of the bins along the corresponding axis of the index. Negative values of IDELTn are allowed and indicate that the index is sorted in inverse order. The values included in the Nth bin of the index then range from ISTRTn + (N - 1) * IDELTn (inclusive) to ISTRTn + N * IDELTn (exclusive). To be precise, for positive values of IDELTn the range is greater than or equal to the starting value and less than (but not equal to) the last value. In order to reduce the effect of numerical rounding errors, any computations using ISTRTn and IDELTn keywords should be performed using double precision arithmetic. The values of the ISTRTn and IDELTn keywords should also be given with maximum possible numerical precision (typically with up to 15 or 16 decimal places).

FORELINK= 'column name'      / column containing forward  links (optional)
BACKLINK= 'column name'      / column containing backward links (optional)

If the FITS table is not physically sorted and instead contains columns with forward and/or backward pointers to the next or previous event in the index bin, then the FORELINK (and optionally, BACKLINK) keyword(s) will be present. The specified column name is not case sensitive.