Subject: FITS TSORTKEY keyword

From: William Pence <pence at tetra.gsfc.nasa.gov>
Date: Tue, 5 Jul 1994 10:58:54 -0400

Last year there was some discussion on this newsgroup of a proposal for
a FITS keyword to indicate the order in which a FITS table has been
sorted.  The OGIP FITS Working Group has recently readdressed this
issue and is proposing that the 'TSORTKEY' keyword be used for this
purpose as described below.  Any comments or criticisms about this
are welcome.

Bill Pence
Ofice of Guest Investigator Programs
NASA/GSFC
-----------------------------------------------------------------------

   TSORTKEY: a FITS Keyword to Specify the Sort Order of a Table

The TSORTKEY keyword is used to indicate the order in which the rows in
a FITS TABLE or BINTABLE extension have been sorted.  The value of the
TSORTKEY keyword is a character string which lists the name (as given
by the TTYPEn keyword) of the primary sort column, followed by the
names of any (optional) secondary sort column(s).  The rows in the
table are sorted first by the value in the primary column; any rows
which have the same value in the primary column are further sorted by
the value in the secondary column and so on for all the specified sort
columns.  If more than one column is specified by TSORTKEY then the
names must be separated by a comma.  One or more spaces are also
allowed between the comma and the following column name.

By default, columns are sorted in ascending order, but a minus sign may
precede the column name to indicate the rows are sorted in descending
order. (Note that this implies that the names of any columns used to
sort a table must not begin with a minus sign).

Integer or floating point columns are sorted by numerical order and not
by their internal ASCII representation in the case of TABLE
extensions.

Character columns are sorted by the ASCII collating sequence order of
the entire string by default.  If the table has been sorted on a
substring within the character column, this may be indicated by
including the range of the substring characters in parentheses after
the column name (e.g.,  'NAME(3:8)' indicates that the rows of the
table are sorted based on the 3rd through 8th characters in the NAME
character column).

The sort order for logical format columns (L) in BINTABLE extensions is
defined such that all false values (F) will precede the true values (T)
when sorted in ascending order.

The sort order of complex data type columns ('C' or 'M') is not defined
by this convention.

In the case of vector columns in binary tables, the TSORTKEY convention
only supports sorting on the value of a particular element within the
vector (except for character string vectors as described above).  The
vector element number that was used to sort the table is included in
parentheses following the vector column name.  If no element is
explicitly specified it is assumed that the table is sorted on the
first element in the vector.

Any null/undefined elements in a sort column will appear after all the
defined values when the table is sorted in ascending order.  Undefined
elements will precede all defined elements when sorted in descending
order.

Examples of TSORTKEY usage:

TSORTKEY = 'X       '
      The table is sorted in ascending value of the X column.

TSORTKEY = 'X,Y     '
      The table is sorted in ascending value of the X column.   Rows 
      which have the same value of X have been further sorted in 
      ascending value of the Y column.

TSORTKEY = '-TIME   '
      The table is sorted in descending value of the TIME column.

TSORTKEY = '-OBJECT(2:4)'
      The table is sorted in reverse alphabetical order on the 2nd through
      4th characters in the OBJECT character string column.

TSORTKEY = 'ARRAY(10)'
      The table is sorted in ascending value of the 10th element of the
      ARRAY vector column.