Subject: FITS column names

From: William Pence <pence at tetra.gsfc.nasa.gov>
Date: Wed, 8 Mar 1995 10:36:26 -0500

Returning to the issue of FITS column names, Francois Ochsenbein
wrote (on 01 Feb 1995):

> The CDS has recently incorporated a possibility of "on-the-fly"
> transformation of tabular data into FITS ascii tables in its
> anonymous FTP server (node  cdsarc.u-strasbg.fr).
  (...)
> This facility concerns over 1,000 tables for which we don't require
> to build and maintain FITS versions. We hope that the FITS generated
> is standard --- however we have conventions for UNIT which differ
> from the proposed OGIP ones, and we do allow column names with
> non-alphanumeric characters.

Just to make this clear, the recommendation to use only letters,
digits, and the underscore in column names did not come from the OGIP,
but was made in the original FITS paper defining the rules for table
extensions.  This recommendation is also repeated in the NOST FITS
Standard and the FITS Users Guide, so personally, I think this should
be strongly enforced unless a compelling case can be made to relax the
rule in certain cases.

The OGIP FITS Working Group recently adopted the following 6 rules for
FITS column names.  For the most part these rules just follow the
extablished FITS recommendations except that we allow the names to be
unique within up to 16 characters, instead of only 8 characters.

We would like to propose that the various FITS committees consider
endorsing these recommendations, and that the FITS Standard be revised
to clarify and strengthen the current recommendations on column names.
Note that the current Binary Table definition document places no
restictions at all on the allowed column names, so one has to assume
that the recommendations for ASCII tables also apply to binary tables.

-Bill Pence, on behalf of the OFWG
 pence at tetra.gsfc.nasa.gov

-----------------------------------------------------------------------------

              FITS Table Column Naming Conventions
                         1 March 1995

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 letters 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 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 (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 possible exception
to this rule is in the case of standard FITS keywords whose name begins
with a digit (there are none in common use at the present), in which
case these same names may be used as column names.

5.  It is required that the column names in a given table be unique
within the first 16 characters and strongly recommended that they be
unique within the first 8 characters.  If the names are unique within 8
characters then it is easier to construct a unique keyword name to
refer to each column (e.g., when using the 'Greenback Convention').
This also maximizes the portability of the FITS table into existing
data systems which may only match the first 8 characters when searching
for a particular column name in the FITS table.  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, therefore, in
general it is only strictly required that the names be unique within 16
characters.

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 16 (and
preferably the first 8) characters are unique.