The Description File introduced in Chapter intro(Alternative: The alternative name 0readme is proposed in Chapter intro)
is aimed to provide all necessary information
to locate the catalogue (authors, title, references, summary, etc...) and to
interpret its contents by automatic procedures.
An example of the ReadMe file of the catalogue I/221
is given in ReadMe.
The description file contains severals sections; as a general rule,
only section headers are left flushed while the text is indented
— with the noticeable exceptions of the title,
the file names in the File Summary section,
and of Note headers (section Notes).
No line in this description file can exceed 80 characters;
it is suggested to limit the textual parts to 70 characters,
such that a conversion to FITS could keep the text as COMMENT
cards.
The description file contains the following parts:
First line: catalogue designation, an abbreviated title
followed within round brackets by the last name of the first author,
a + sign if there are multiple authors, and the year —
this information has to be condensed in a single line of 80
characters or less;
Full title(s), authors, and reference(s) of the catalogue.
Each title is left-adjusted (no indentation);
the line(s) containing the authors' names are indented
(at least two blanks), and the bibliographic
reference is enclosed between angle brackets.
The standard SIMBAD/NED/ADS 19-byte bibliographical reference
code(s) named BibCode(
see e.g.a description in the SIMBAD User's Guide, page 65,
or on the WWW page
http://cds.unistra.fr/simbad/refcode.html)
is introduced by an equal sign, as a word without embedded blank
of exactly 20 characters (with the equal sign).
The Keywords
There are three categories of keywords:
Keywords: introduces the list of keywords
as in the printed publication
ADC_Keywords introduces the list of
data-related keywords, out of a
controlled set. Unlike the Keywords: set
which is generally related to the scientific goal of
a paper, the ADC_Keywords are stricly related
to the tabular material collected in the paper.
Mission_Name:
for data originated from satellite mission, this
header precedes the satellite name.
Whatever the category, multiple keywords are separated by a
semicolon (;) or a dash 9-) embedded in blanks.
A short description of the contents, the purpose and remarks
of special importance
of the catalogue introduced by
Description: and/or
Abstract:
section headers;
(optional) The list of observed objets introduced by Objects:,
in the case where no data table contains the list of
the astronomical objects observed or studied, as
in the study of a high-resolution spectrum of a single star.
The structure for this list must follow the following template:
Objects: \makebox[2em][c]
-----------------------------------------------— \makebox[3.2em][c]
RA (equinox) DE
\makebox[1.5em][c]
Name(s) \makebox[2em][c]
-----------------------------------------------— \makebox[2em][c]
hh mm ss.s ±dd mm ssName1 =
Name2... \makebox[2em][c]
-----------------------------------------------—
The header line (the one with RA, DE, and the equinox)
should be aligned with the data, in order to give a measure
of the starting byte of the object designations (names).
A list of the files making up the catalogue is introduced
by the File Summary: section header. This list includes
the following basic information for each file:
its name, its record length (length of the longest line),
the number of records, and a short title (caption).
(optional) The list of related catalogues, data sets
or services are introduced by the See also: header.
In this section, each catalog or service starts on a new line,
and is followed by a colon embedded in blanks, e.g.:
See also: \makebox[1.5em][c]
J/A+AS/97/729 : O-rich stars in 1-20um range \makebox[1.5em][c]
http://machine/description.html : Detailed Description of
the experiment
(optional) Due to the frequent difficulties
encountered the the nomenclature of astronomical objects,
a dedicated section introduced by
by the Nomenclature Notes: header
provides the necessary explanations in the peculiar conventions
used in this matter.
A description explaining which are the columns of the
tables, how to get the values stored in these columns,
and what is their meaning is introduced by the
Byte-by-byte Description of file: section header.
This description is presented as a five-column table
with the following elements:
the starting (from 1) and ending byte of a column,
separated by a dash -;
this dash is however not required for
a single-byte column .
the à la FITS Format which specifies
how to interpret numbers or symbols, composed of
a A, I, F or E letter,
indicating to intrepret the data as Ascii text,
Integer number, Floating-point number
with a fixed number of decimals, or a floating-point
number written in Exponential notation
followed by a number indicating the width of
the column in bytes,
eventually followed by a dot and a number
indicating the number of decimal digits
(for F and E notations)
This format could be preceded by an iteration factor
to designate an array of values all written with the
same format.
the Unit in which the value is expressed;
unit standards are detailed below (section units).
The symbol — indicates unitless values,
and the square brackets [unit]
indicates values tabulated as decimal logarithmic values.
a label or column header. A few standard names
and name building rules are detailed in section labels.
a short explanation of the contents of the column.
This last field may also specify:
a set of valid characters
for an alphabetical column, or limits for numeric columns:
see section limits.
some other sections may exist when required, e.g.
History; introduces notes about the modification
history,
Acknowledgements: etc...
(optional) The list of references is introduced
by the References: header; the 19-character BibCode
is used when possible,
to enable an automatic link
to the existing Abstract Services like ADS.
the very last line includes just the left-flushed word
(End) with
the name of the person who took care of the standardisation, and
the date of the last modification.
3.2 Units
The unit in which physical parameters are expressed is a fundamental
parameter which becomes especially important when
data are used outside a specialized field of science —
and astronomical computer data are obvious candidates for a usage
outside astronomy.
Special care has been taken to try to use the standard SI units,
and to convert if necessary the unit to such standards:
for instance, we use the string
0.1nm to express Angströms (Å=10–10m),
since the Angström is a non-standard unit.
Another example is mW/m2 , the milliwatt per m2,
which is identical to the CGS erg/cm2/s unit, which is not
used outside our discipline.
The standard adopted here differs from the OGIP ones (
OGIP memo 93-001 about ``Specification of Physical Units within OGIP FITS files"
by Ian M. George & Lorella Angelini, August 1993) for
the syntax of composite units (operator symbols),
and in the usage of math functions and obsolete CGS units
which are rejected here;
the basic symbols however agree.
Only simple power functions or decimal logarithm of physical units are
accepted, which means
that e.g. solMass3/2 (solar mass at a 3/2 power)
cannot be a valid unit;
[solMass] indicates logModot unit, i.e. a value representing
solar masses expressed on a logarithmic scale.
3.2.1 Syntax of Units
The syntax of the unit expression is summarized by the following rules:
[Rule] 1:
any unit is described by a single word — no space is allowed.
For instance, the Angström is coded 0.1nm, and never 0.1 nm;
the kilometer-per-second is coded km/s, or km.s-1,
but never km / s or km s-1.
[Rule] 2: the only allowed numerical factor is at the
very beginning of the Unit string. The
structure of the unit is therefore
factorunit_expression
and we will write the ``number of pixels per Å" as
10pix/nm, and neither pix/0.1nm nor pix/(0.1nm).
The numerical factor may include the letter x
for the multiplication, as 1.5x10+11 to express the number
1.5×1011
[Rule] 3: The operators to express a compound unit are
[/] for the division — as in km/s
[.] for the multiplication (the dot is however
understood as a decimal point in the
leading numerical factor) —
as in kW.h
[] nothing for a power — as m2 for m2
or 10+21 for 1021.
Note that + or – signs are not operators, but represent
the leading sign of numeric values.
[Rule] 4: a simple (non-compound) unit is made of a
basic unit symbol (see section basic) eventually preceded
by a multiple prefix (see section multiple)
Among several possible expressions of a unit, it is
preferable to choose the shortest one; this leads also to prefer
the division (/) to the multiplication of the inverse,
e.g. prefer km/s to km.s-1.
The basic symbols listed in Unit include basic
standard SI units (b), the extensions listed
by the IAU style book marked (a), other frequent physical extensions (e),
and a few further extensions used at CDS (c).
3.2.3 Multiples
Multiple and submultiple symbols
Symbols used to express multiples and submultiples
Symbol
Explanation
Value
d
deci
10–1
c
centi
10–2
m
milli
10–3
u
micro (µ)
10–6
n
nano
10–9
p
pico
10–12
f
femto
10–15
a
atto
10–18
z
zepto
10–21
y
yocto
10–24
Symbol
Explanation
Value
da
deca
10
h
hecto
102
k
kilo
103
M
mega
106
G
giga
109
T
tera
1012
P
peta
1015
E
exa
1018
Z
zetta
1021
Y
yotta
1024
The standard SI multiple and submultiple prefixes can be used;
these are summarized in multiple.
Note that a single prefix can only be attached to a
unit symbol, which means that e.g. mmas must not be used
to designate a µ-arc-second, but rather uarcsec.
3.3 Labels
Conventions used for some labels
\textwidth
Symbol
Explanation
Default Limits
RAh
Part of the right ascension expressed in hours
[0,24[
RAm
Part of the right ascension expressed in minutes
[0,60[
RAs
Part of the right ascension expressed in seconds
[0,60[
RAdeg
(Alternative: RAhms could be envisaged for a right ascension expressed
in sexagesimal with no embedded blanks and leading zeroes, RAbhms
for sexagesimal values with embedded blanks.
Such extensions would however require special interpretation by
FITS readers.
)
Right ascension expressed in decimal degrees
[0,360[
RArad
Right ascension expressed in radians
[0,2π[
DE-
Sign of declination
[+-]
DEd
Part of the declination expressed in degrees
[0,90]
DEm
Part of the declination expressed in arc minutes
[0,60[
DEs
Part of the declination expressed in arc seconds
[0,60[
DEdeg
(Alternative: DEdms could be envisaged for a declination expressed
in sexagesimal with no embedded blanks and leading zeroes, DEbdms
for sexagesimal values with embedded blanks; questions similar to the
RAhms note have to be addressed.
)
Declination expressed in decimal degrees
[–90,+90]
DErad
Declination expressed in radians
[–π/2,+π/2]
ELON
ecliptic longitude
[0,360[
ELAT
ecliptic latitude
[0,360[
GLON
galactic longitude
[0,360[
GLAT
galactic latitude
[0,360[
plx
Parallax
pmRA
Proper motion in Right Ascension
pmDE
Proper motion in Declination
pmX
Proper motion along X direction
Diam
Diameter
>=0
PA
Position Angle, normally North to East
[0,360[
Rad
Radius
>=0
RV
Radial velocity
Sep
Separation
>=0
SpType
Spectral type
MType
Morphological type
Remember that a label is always a single word: it cannot
contain any embedded blank. Other characters are in principle
accepted, e.g. parentheses or other punctuation signs.
label is not an exhaustive list of all possible column labels;
it merely represents the standards adopted for the most common
columns headings — like the positions in the sky(Alternative: The VIZIER service at https://vizier.cds.unistra.fr
contains all definitions of all colums; these definitions
are stored in the fmd (field meta-data)
table which can be queried
like any of the tables accessible in VIZIER.
).
Conventions used for label prefixes
Symbol
Explanation
Default Limits
a_label
aperture used for
parameter label
>=0
E_label
mean error (upper limit)
on parameter label
>=0
e_label
mean error (σ)
on parameter label
>=0
f_label
flag
on parameter label
l_label
limit flag
on parameter label
[<>]
m_label
multiplicity index
on parameter label to resolve ambiguities
n_label
note (remark)
on parameter label
o_label
number of observations
on parameter label
>=0
q_label
quality
on parameter label
r_label
reference (source) for parameter label
u_label
uncertainty flag
on parameter label
[ :]
w_label
weight of parameter label
>=0
x_label
unit in which parameter label is
expressed
A parameter has frequently associated values, and we have adopted
the rule of association with the one-letter underscore prefix:
if a column is obviously associated to another one — typically
mean errors or uncertainty flags — we use one of the
underscore prefixes listed in prefix.
Usual mathematical functions may be specified in the label,
with parentheses or a dot; for instance, the logarithm of the effective
temperature could be labelled log(Te) or log.Te.
3.4 Data Checking
The first word (i.e. set of characters followed by a blank)
of the explanation of a column
may specify validity checks to be performed about:
the available range of the value in the column
the possibility of having unspecified or NULL
values
the order of the values within the table
(increasing or decreasing order)
The three different checks have to be specified in this order:
range, NULL, order, without any embedded blank.
All these checks are performed by the standalone program anafile
detailed in section anafile.
3.4.1 Limits
Limits in a column can be specified in the explanation column,
with values enclosed within square brackets [ or ](The square brackets are not part of the EBCDIC character set;
the angle brackets < > could eventually be used instead of the
square brackets.
); the square bracket must be the first
character of the explanation if present.
The only
exception arises when an asterisk is present before the first square
bracket to indicate the presence of extended notes (see section Notes).
For an alphabetic column (A-format),
the limits describe the valid character set,
i.e. the list of valid characters in the column. As an example, an
uncertainty column labelled u_lab with an A1 format
may only contain a blank, a question mark or a colon (which is different
from the default shown in prefix); this feature can be specified
as follows:
3 A1 --- u_lab [ :?] Uncertainty flag on parameter lab
The dash sign (-) may be used to specify consecutive characters,
e.g. [A-F] for any character of the set {A,B,C,D,E,F}.
For a numeric column, the limits can be specified with two
numbers separated by a slash or a comma and enclosed in square brackets.
The inclusion or non-inclusion of the limits as acceptable values
follow the standard mathematical conventions,
i.e. an opening ] bracket means that the lower value is excluded,
a closing ] bracket that the upper value is included.
As an example, the following specifies a parameter
350 < λ< 650 :
75- 80 F6.2 nm lambda ]350,650[ Wavelength
Both limits are not required: to express that a value has to be strictly
positive, use the expression ]0,]; the expression
[,0] specifies a negative or null value.
Writing [] is acceptable
when no range checking applies; this writing is required
if a not-NULL or a sorting order has to be specified.
When specified, limiting numbers should represent actual limits,
and not the
range of all possible values which can be inferred from the format
(e.g. [-999,9999] for an I4 number).
Some labels have implicit limits, listed in the column Limits
of label and prefix. These defaults
are overridden (for numeric columns only) by the
limits specified within square brackets in the description file :
writing e.g.[] as the first word of the explanation of a column
labelled GLON removes the condition
0 <=GLON < 360.
3.4.2 NULL values
A NULL or unspecified value is always indicated by setting
all bytes of the column to blanks(Alternative: using out-of-range values to specify NULLs
— typically numbers made of 9's only —
is required by some FORTRAN users.
).
The range or character set specification may be followed by the characters
[!] (exclamation mark) indicates that a NULL value
is forbidden (i.e.the column can never be blank)
[?] (question mark) indicates that a NULL value
is allowed (i.e.the column may be blank).
When the ? is followed by the = sign and a numeric value
without intervening space, the value is the alternative NULL
value and is equivalent to the FITS TABLES extension TNULL keyword,
e.g. ?=99.99
The default rule is the following:
NULL value is allowed for an alphabetic column
(A-format);
NULL value is not allowed for a numeric column
The column Name of ReadMe, which cannot be NULL,
illustrates how to override (with the !)
the default of an alphabetic column.
3.4.3 Order
Following the range, it is also possible to specify that this column
is increasing or decreasing throughout the table(Alternative:
An alternative way of defining the order is proposed in the
File Summary part described in section ReadMe
). If n is the
row number, the conventions are:
[+] the value in the column is strictly increasing,
val(n+1) > val(n)
[+=] the value in the column is increasing:
val(n+1) >=val(n)
[–] the value in the column is strictly decreasing:
val(n+1) < val(n)
[–=] the value in the column is decreasing:
val(n+1) <=val(n)
3.4.4 Notes
Lengthy explanations can hardly be inserted in the
Byte-by-byte Description table;
such explanations are easier to read when they are
grouped at the end of the description table.
Two options are presently proposed:
an * at the very beginning of the short explanation
column indicates the existence of a note; this note is introduced
at the end of the table by a
Note on label: section header.
An example of this way is illustrated in Note-star;
a parenthesed number representing a footnote number as the
very last word of the short explanation column;
the details are introduced at the end of the table by a
Note (n): section header.
An example of this way is illustrated in Note-num
3.5 Transformation to FITS
The data files can be automatically transformed into FITS:
FITS shows the ascii table extension header generated
from the description file shown in ReadMe.
Files can be copied directly in this format with the cdsclient
routines described in Chapter client.
This set of programs also includes for instance
an access to the 1.1 version of the Guide star catalogue (section gsc)
as well as a few other utilities related to the Catalogue Service
or SIMBAD at CDS.
The transformation into FITS can also be performed directly
in the ftpd server at CDS —
the server which is used for remote copies.