3.1  Structure of the ReadMe File

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.

I/221               The Magellanic Catalogue of Stars - MACS (Tucholke+ 1996)
================================================================================
The Magellanic Catalogue of Stars - MACS
     Tucholke H.-J., de Boer K.S., Seitter W.C.
    <Astron. Astrophys. Suppl. Ser., 119, 91-98 (1996)>
    <The Messenger 81, 20 (1995)>
    =1996A&AS..119...91T =1995Msngr..81...20D
================================================================================
ADC_Keywords: Magellanic Clouds ; Positional data

Description:
    The Magellanic Catalogue of Stars (MACS) is based on scans of ESO
    Schmidt plates and contains about 244,000 stars covering large areas
    around the LMC and the SMC. The limiting magnitude is B<16.5m and the
    positional accuracy is better than 0.5" for 99% of the stars. The
    stars of this catalogue were screened interactively to ascertain that
    they are undisturbed by close neighbours.


File Summary:
--------------------------------------------------------------------------------
 FileName    Lrecl    Records    Explanations
--------------------------------------------------------------------------------
ReadMe          80          .    This file
lmc.dat         52     175779    The Large Magellanic Cloud
smc.dat         52      67782    The Small Magellanic Cloud
--------------------------------------------------------------------------------

Byte-by-byte Description of file: lmc.dat smc.dat
--------------------------------------------------------------------------------
   Bytes Format  Units   Label    Explanations
--------------------------------------------------------------------------------
   1- 12  A12    ---     MACS     Designation
  14- 15  I2     h       RAh      Right Ascension J2000 , Epoch 1989.0 (hours)
  17- 18  I2     min     RAm      Right Ascension J2000 (minutes)
  20- 25  F6.3   s       RAs      Right Ascension J2000 (seconds)
      27  A1     ---     DE-      Declination J2000 (sign)
  28- 29  I2     deg     DEd      Declination J2000 , Epoch 1989.0 (degrees)
  31- 32  I2     arcmin  DEm      Declination J2000 (minutes)
  34- 38  F5.2   arcsec  DEs      Declination J2000 (seconds)
      40  I1     ---     Npos     Number of positions used
  42- 46  F5.2   mag     Mag      []?=99.00 Instrumental Magnitude
                                        (to be used only in a relative sense)
      48  I1     ---     PosFlag  [0/1] Position Flag   (0: ok,
                                        1: internal error larger than 0.5")
      50  I1     ---     MagFlag  [0/1] Megnitude Flag  (0: ok,
                                        1: bad photometry or possible variable)
      52  I1     ---  BochumFlag *[0] Bochum Flag
--------------------------------------------------------------------------------
Note on BochumFlag: 1 if in Bochum catalog of astrophysical information
    on bright LMC stars) (yet empty)
--------------------------------------------------------------------------------

Author's address:
    Hans-Joachim Tucholke    <tucholke@astro.uni-bonn.de>

================================================================================
(End)            Hans-Joachim Tucholke [Univ. Bonn]                  20-Nov-1995

The ReadMe file of a catalogue

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:

  1. 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;
  2. 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://cdsweb.u-strasbg.fr/simbad/refcode.html) is introduced by an equal sign, as a word without embedded blank of exactly 20 characters (with the equal sign).
  3. The Keywords There are three categories of keywords: Whatever the category, multiple keywords are separated by a semicolon (;) or a dash 9-) embedded in blanks.
  4. A short description of the contents, the purpose and remarks of special importance of the catalogue introduced by Description: and/or Abstract: section headers;
  5. (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 ss   Name1 = 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).

  6. 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).
  7. (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

  8. (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.
  9. 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:
    1. 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 .
    2. 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.
    3. 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.
    4. a label or column header. A few standard names and name building rules are detailed in section labels.
    5. 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.
      • whether the column is ordered: see section order
      • whether blank (unspecified) numbers are allowed: see section NULL
      • a key to more detailed notes: see section Notes
  10. some other sections may exist when required, e.g. History;  introduces notes about the modification history, Acknowledgements:  etc...
  11. (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.
  12. 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:

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.

3.2.2  Basic symbols

Symbols used for Units

Basic Unit Symbols (see section basic)
 
Symbol Explanation Definition
(c) Unitless value (c) % Unitless value, in percent 10–2 (a) a year (also yr) 365.25d = 31.5576×106s (b) A Ampere (a) AU astronomical unit 1.49598×1011m (a) arcmin minute of arc 1/60 deg (a) arcsec second of arc 1/60 arcmin (e) barn barn (cross-section) 10–28 m2 (c) bit binary information unit (computer storage) (c) byte byte (computer storage) 8 bit C Coulomb (electric charge) As (b) cd Candela (luminous intensity) (c) ct Count (events) D Debye 1/3×10–29 Cm (a) d day 24h = 86.4×103s (a) deg degree of arc π/180 rad (e) eV electron-Volt 1.602177×10–19 J F Farad (electric capacitance) C/V (b) g gram 10–3 kg (a) h hour of time (sideral if appropriate) 3600s H Henry (inductance) Wb/A Hz Hertz (frequency) s–1 J Joule (energy) Nm (a) Jy Jansky 10–26 W/m2/Hz (b) K Kelvin lm lumen (luminous flux) cdsr lx lux (illuminance) lm/m2 (b) m metre (a) mag magnitudes (a) mas millisecond of arc (π/6.48)×10–8 rad (a) min minute of time (sideral if appropriate) (b) mol mole N Newton (force) kgm/s2 Ohm (Ω) Ohm (electric resistance) V/A Pa Pascal (pressure) N/m2 (a) pc parsec 3.0857 ×1016m (c) pix pixel (image element) (b) rad radian (angle) (e) Ry Rydberg (energy) 1/2 (2πe2/hc)2mec2 = 13.60583 eV (b) s second of time S Siemens (electric conductance) A/V (c) solLum Solar luminosity 3.826×1026 W (c) solMass Solar mass 1.989×1030 kg (c) solRad Solar radius 6.9599×108 m (c) Sun Unit referring to the Sun (e.g. abundances) sr steradian (solid angle) T Tesla (magnetic field intensity) Wb/m2 V Volts (electric potential) W/A W Watt (power) J/s Wb Weber (magnetic flux) Vs (c) yr year (also a) 365.25d = 31.5576×106s

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 http://vizier.u-strasbg.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:

  1. the available range of the value in the column
  2. the possibility of having unspecified or NULL values
  3. 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).

  1. 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}.

  2. 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

The default rule is the following:

  1. NULL value is allowed for an alphabetic column (A-format);
  2. 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:

3.4.4  Notes

Byte-by-byte Description of file: table1
--------------------------------------------------------------------------------
   Bytes Format  Units   Label    Explanations
--------------------------------------------------------------------------------
   1-  5  A5     ---     Cluster  Abell cluster designation
   7- 22  A16    ---     Name    *Galaxy name
  24- 25  I2     h       RAh      Right Ascension 1950 (hours)
  27- 28  I2     min     RAm      Right Ascension 1950 (minutes)
  30- 33  F4.1   s       RAs      Right Ascension 1950 (seconds)
      35  A1     -       DE-      Declination 1950 (sign)
  36- 37  I2     deg     DEd      Declination 1950 (degrees)
  39- 40  I2     arcmin  DEm      Declination 1950 (minutes)
  42- 43  I2     arcsec  DEs      Declination 1950 (seconds)
  47- 51  F5.2   mag     B(0)     []? Integrated magnitude
      52  A1     ---     n_B(0)  *[RMCPHK] Origin of B(0)
  55- 59  I5     km/s    RV       Velocity
  62- 64  I3     km/s    e_RV     Mean error on RV
--------------------------------------------------------------------------------
Note on Name:
    Names with RA given with five digits are normally from
    Zwicky catalogues; the other (with four digits in RA,
    starting or not with the letter A) are anonymous
    galaxies.
Note on n_B(0):
    C = CCD photometry (CfA redshift survey 1992)
    H = Zwicky magnitude split by observers
    K = Markarian catalogue of galaxies (1967)
    M = MCG (Vorontsov-Velyaminov et al. 1962-68)
    P = observer's eye estimate
    R = RC1 (de Vaucouleurs & de Vaucouleurs 1964)
--------------------------------------------------------------------------------

A first alternative to write lengthy explanations

Byte-by-byte Description of file: table1
--------------------------------------------------------------------------------
   Bytes Format  Units   Label    Explanations
--------------------------------------------------------------------------------
   1-  5  A5     ---     Cluster  Abell cluster designation
   7- 22  A16    ---     Name     Galaxy name (1)
  24- 25  I2     h       RAh      Right Ascension 1950 (hours)
  27- 28  I2     min     RAm      Right Ascension 1950 (minutes)
  30- 33  F4.1   s       RAs      Right Ascension 1950 (seconds)
      35  A1     -       DE-      Declination 1950 (sign)
  36- 37  I2     deg     DEd      Declination 1950 (degrees)
  39- 40  I2     arcmin  DEm      Declination 1950 (minutes)
  42- 43  I2     arcsec  DEs      Declination 1950 (seconds)
  47- 51  F5.2   mag     B(0)     []? Integrated magnitude
      52  A1     ---     n_B(0)   [RMCPHK] Origin of B(0) (2)
  55- 59  I5     km/s    RV       Velocity
  62- 64  I3     km/s    e_RV     Mean error on RV
--------------------------------------------------------------------------------
Note (1): Names with RA given with five digits are normally from
    Zwicky catalogues; the other (with four digits in RA, starting or
    not with the letter A) are anonymous galaxies.
Note (2):
    C = CCD photometry (CfA redshift survey 1992)
    H = Zwicky magnitude split by observers
    K = Markarian catalogue of galaxies (1967)
    M = MCG (Vorontsov-Velyaminov et al. 1962-68)
    P = observer's eye estimate
    R = RC1 (de Vaucouleurs & de Vaucouleurs 1964)
--------------------------------------------------------------------------------

A second alternative to write lengthy explanations

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:

  1. 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;

  2. 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

XTENSION= 'TABLE   '           / Ascii Table Extension
BITPIX  =                    8 / Character data
NAXIS   =                    2 / Simple 2-D matrix
NAXIS1  =                   58 / Number of bytes per record
NAXIS2  =                  793 / Number of records
PCOUNT  =                    0 / Get rid of random parameters
GCOUNT  =                    1 / Only one group (isn't it obvious?)
TFIELDS =                    7 / Number of data fields (columns)
EXTNAME = 'appendix'           / JHKL'M of 37 sources
         =======================================================================
TBCOL1  =                    1 / ============== Start column +0
TFORM1  = 'A20     '           / Fortran Format
TTYPE1  = 'Name    '           / ! Star designation
TBCOL2  =                   22 / ============== Start column +21
TUNIT2  = 'd       '           / Unit: day
TFORM2  = 'I7      '           / Fortran Format
TTYPE2  = 'JD      '           / [2445597/2448375] Date
TAMIN2  =              2445597 / Allowed minimal value
TAMAX2  =              2448375 / Allowed maximal value
TBCOL3  =                   30 / ============== Start column +29
TUNIT3  = 'mag     '           / Unit: magnitude
TFORM3  = 'F5.2    '           / Fortran Format
TTYPE3  = 'J       '           / 1.24mum
TBCOL4  =                   36 / ============== Start column +35
TUNIT4  = 'mag     '           / Unit: magnitude
TFORM4  = 'F5.2    '           / Fortran Format
TTYPE4  = 'H       '           / 1.63mum
TBCOL5  =                   42 / ============== Start column +41
TUNIT5  = 'mag     '           / Unit: magnitude
TFORM5  = 'F5.2    '           / Fortran Format
TTYPE5  = 'K       '           / 2.19mum
TBCOL6  =                   48 / ============== Start column +47
TUNIT6  = 'mag     '           / Unit: magnitude
TFORM6  = 'F5.2    '           / Fortran Format
TTYPE6  = 'L''     '           / 3.79mum
TBCOL7  =                   54 / ============== Start column +53
TUNIT7  = 'mag     '           / Unit: magnitude
TFORM7  = 'F5.2    '           / Fortran Format
TTYPE7  = 'M       '           / 4.64mum
         =======================================================================
END

The FITS extension header constructed from the ReadMe file of ReadMe

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.