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

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://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).
3. 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.
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

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 m², which is identical to the CGS erg/cm²/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. solMass^3/2 (solar mass at a 3/2 power) cannot be a valid unit; [solMass] indicates logM_odot unit, i.e. a value representing solar masses expressed on a logarithmic scale.

3.2.1  Syntax of Units

• [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×10¹¹

• [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 m² or 10+21 for 10²¹.
  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.

3.2.2  Basic symbols

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

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

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

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

• [!] (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:

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

• [+] 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

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)
--------------------------------------------------------------------------------

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)
--------------------------------------------------------------------------------

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