Subject: draft column naming convention

From: William Pence <pence at tetra.gsfc.nasa.gov>
Date: Wed, 4 Jan 1995 14:06:05 -0500

During the discussion here last month about the TSORTKEY convention for
specifying how a FITS table has been sorted, another related issue was
raised, having to do with naming conventions for column names in a
table.  In response to this, our OGIP FITS Working Group has drafted
the following proposed recommendation on column names.  We would
welcome any comments or discussion about this.

-Bill Pence, for the OFWG
----------------------------------------------------------------------------

              FITS Table Column Naming Conventions
                      DRAFT: 16 Dec 1994

It is often logical or convenient to refer to a column in a FITS table
by its name as given by the TTYPEn keyword.  The FITS Standard,
however, does not require the TTYPEn keyword, nor does it provide
unambiguous guidelines for the value of the TTYPEn keyword when it is
present.  In order to enforce some homogeneity within FITS tables and
to provide guidelines for software that must read them, the following
conventions are recommended (and required for all FITS tables
produced by the HEASARC/OGIP):

1.  Every column of a FITS table (either ASCII 'TABLE' or binary
'BINTABLE') must be given a unique name using the TTYPEn keyword.

2.  Only upper or lower case letters, the digits from 0 to 9, and the
underscore character may be used in the column name.  This is similar
to the restriction placed on FITS keyword names (with the exception of
not allowing the hyphen character), which makes it possible to replace
a column in a table with a keyword with the same name if the column
values are identical in every row (the so-called 'Greenbank
Convention').  Note that this specifically excludes ASCII blank
characters within the name, except that non-significant trailing blanks
are allowed (e.g.,  TTYPE1 = 'X       ').  In cases where the column
name consists of several 'words', the words should be concatenated
together or connected with the underscore character (e.g., 'Bright_Stars').

3.  While both upper and lower case may be used within a column name,
the case is not significant when comparing names (e.g., 'COL_NAME',
'Col_Name', and 'col_name' are all considered the same name and are not
unique).  Software should be case insensitive when searching for
a given column name.

4. Column names must begin with a letter, and not a digit or the
underscore character.  This allows the column name to be used as a
variable name within processing software since many software languages
do not allow a variable name to begin with a digit.   This restriction
also enables users or software to unambiguously refer to a column by
its positional number instead of its name.  The only allowed exception
to this rule is in the case of standard FITS keywords whose name begins
with a digit (there are none known at present), in which case these same
names may be used as column names.

5.  It is strongly recommended that the column names within a given
table be unique within the first 8 characters.  This allows the first 8
characters to be used as a unique keyword name (e.g., under the
'Greenbank Convention'), and it minimizes the overhead on software when
searching a list of column names for a matching string.  It is
recognized, however, that this 8 character restriction can be
impractical in cases where the table contains many columns or where the
preferred names for the columns are dictated by some external source
(e.g., in a project database that defines longer names).  In these
cases, column names that are only unique within up to 16 characters are
allowed.

6. The column names may be up to 68 characters in length (the maximum
length of a FITS string-valued keyword) as long as the first 8 (or 16)
characters are unique.  In general, software should always use and
preserve at least the first 16 characters of the column names when
processing a FITS table.  Conversely, writers of FITS tables should not
assume that more than the first 16 characters of the column name will
be recognized or preserved by processing software.

-----------------------------------------------------------------------------
(The following appendices are not part of the proposed convention, but
are included here for convenience).

Appendix A.

For reference, the sections of the NOST Standard "Definition of FITS"
that (may) pertain to the TTYPEn keyword are listed below.

Section 5.3.2.1 (Fixed Format Character String Keyword Requirements):

If the value is a character string, column 11 shall contain a single
quote (hexadecimal code 27); the string shall follow, starting in
column 12, followed by a closing single quote that should not occur
before column 20 and must occur in or before column 80.  Reading the
data values in a FITS file should not require decoding any more than
the first eight characters of a character string value of a keyword.
The character string shall be composed only of ASCII text. [ASCII text
is defined to be ASCII characters hexadecimal 20-7E].

Section 8.1.2 (Reserved Keywords in ASCII Table Extensions):

TTYPEn Keywords:  The value field for this indexed keyword shall
contain a character string, giving the name of field n.  It is
recommended that only letters, digits, and the underscore (hexadecimal
code 5F) be used in the name.  However, string comparisons with the
values of TTYPEn keywords should not be case sensitive.  The use of
identical names for different fields should be avoided.

Section A.4 (Binary Table Header):

TTYPEnnn (character) gives the label for field nnn.

Appendix B:

For reference, the sections of the NOST "User's Guide for FITS" that
(may) pertain to the TTYPEn keyword are listed below.

3.1.1 (FITS Fundamentals, the Primary HDU)

The format of a fixed format value field depends upon its type: [a
character string has] a beginning "'" in column 11 and an ending "'" in
or after column 20 but no later than column 80, with the string in
between. [...]  If the reading program requires the value of the
keyword to interpret the data properly, the information should be in
the first eight characters.  Users should name their strings
accordingly.  For purely descriptive material, it is not so critical
to have the meaning be clear from the first eight characters, but it is
still a good idea.

3.4.2. (Reserved Keywords for ASCII Tables Extension):

TTYPEn (character) is the heading for field n.  The recommended
characters are letters digits, and underscore.  Lowercase letters may
be used.  The hyphen is *not* recommended.  While more than one field
may have the same heading (value of TTYPEn), the practice is not
recommended.

---

From: bschlesinger at nssdca.gsfc.nasa.gov (Barry M. Schlesinger)
Date: 6 Jan 1995 16:37 EDT

In article <199501041906.OAA02759 at tetra.gsfc.nasa.gov>, William Pence <pence at tetra.gsfc.nasa.gov> writes...
>				...

An additional reason for keeping the first 8 characters unique lies in 
some history that not all readers here may be aware of.  In the first 
FITS paper (page 366, paragraph 2) there is the statement,

	"... recipients of FITS tapes should be prepared to interpret 
	 the first eight characters of a string (appearing between
	 single quotes).  Originators of FITS tapes may generate 
	 longer strings, but should no (sic) expect recipients
	 to decode more than the first eight characters...."

While this statement was geared to the state of the art at the time 
(early 1980s), my understanding is that some data systems may require 
unique values for the first eight characters of the values of the 
TTYPEn.

				Barry Schlesinger
				NSSDC/NOST FITS Support Office