Centre de Donnees astronomiques de Strasbourg ___ Astronomical Catalogues at CDS Adopted Standards Version 1.4 September 12, 1994 Prepared by Francois Ochsenbein as modified by N. Paul M. Kuin (ADC) Contents -------- 1 The Question of Standards 3 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . 3 1.2 FITS. why . . . . . . . . . . . . . . . . . . . . . . 3 1.3 FITS. why not . . . . . . . . . . . . . . . . . . . 3 1.4 Proposed solution . . . . . . . . . . . . . . . . . . 4 1.5 Evolution of the document . . . . . . . . . . . . . . 5 2 The Catalogue Files & Directories 6 2.1 The Directory Tree . . . . . . . . . . . . . . . . . 6 2.2 File Naming Conventions . . . . . . . . . . . . . . 7 2.3 Index Files . . . . . . . . . . . . . . . . . . . . 8 3 Description Standards 10 3.1 Structure of the ReadMe File . . . . . . . . . . . . 10 3.2 Units . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1 Syntax of Units . . . . . . . . . . . . . . 13 3.2.2 Basic symbols . . . . . . . . . . . . . . . . 14 3.2.3 Multiples . . . . . . . . . . . . . . . . . . 14 3.3 Labels . . . . . . . . . . . . . . . . . . . . . . . 14 3.4 Data Checking . . . . . . . . . . . . . . . . . . . 16 3.4.1 Limits . . . . . . . . . . . . . . . . . . . 16 3.4.2 NULL values . . . . . . . . . . . . . . . . . 19 3.4.3 Order . . . . . . . . . . . . . . . . . . . 19 3.4.4 Notes . . . . . . . . . . . . . . . . . . . 19 3.5 Transformation to FITS . . . . . . . . . . . . . . . 22 1 2 4 The cdsclient package 24 4.1 Installation of cdsclient . . . . . . . . . . . . . . 24 4.2 findcat . . . . . . . . . . . . . . . . . . . . . . . 24 4.3 lscat . . . . . . . . . . . . . . . . . . . . . . . . 25 4.4 catcat . . . . . . . . . . . . . . . . . . . . . . . . 25 4.5 findacro . . . . . . . . . . . . . . . . . . . . . . . 26 4.6 findgsc . . . . . . . . . . . . . . . . . . . . . . . 26 4.7 simbib . . . . . . . . . . . . . . . . . . . . . . . 26 5 Selected "Manual Pages" 27 anafile (1) . . . . . . . . . . . . . . . . . . . . . . . . 27 tofits (1) . . . . . . . . . . . . . . . . . . . . . . . . 31 List of Tables ---------------- 2.1 Directory Tree of Catalogues at CDS . . . . . . . . . 6 3.1 Symbols used for Units . . . . . . . . . . . . . . . . 15 2.1 Directory Tree of Catalogues at CDS . . . . . . . . . 6 2.1 Directory Tree of Catalogues at CDS . . . . . . . . . 6 3.2 Multiple and submultiple symbols . . . . . . . . . . . 16 3.3 Conventions used for some labels . . . . . . . . . . . 17 3.4 Conventions used for label prefixes . . . . . . . . . 18 List of Figures ----------------- 3.1 The ReadMe file of a catalogue . . . . . . . . . . . . 11 3.2 A first alternative to write lengthy explanations . . 20 3.3 A second alternative to write lengthy explanations . . 21 3.4 The FITS extension header constructed from the ReadMe file of Figure 3.1 . . . . . . . . . . . . . . . . . 23 Chapter 1 ---------- The Question of Standards ---------------------------- 1.1 Introduction Many astronomical catalogues are now available in computer form, and the flow of incoming data sets has increased a lot since 1993, mainly due to the agreement with the Astronomy & Astrophysics Editors for the storage of published tables (see footnote 1). The question of a uniform description is raised as soon as we expect to use any of the catalogues in a transparent way, e.g. to ingest the data into a data-base, to load a table of a published paper into our image processing system, etc... 1.2 FITS: why FITS format(see footnote 2) is apparently the most popular data format for the ex- change of computer data in our discipline, and is endorsed by IAU. The documentation of FITS (Draft Standard NSDSSO 100-0.1), as well as software related to FITS, is maintained by NOST (NASA/Science Office of Standards and Technology) and can be copied via anonymous ftp on nssdca.gsfc.nasa.gov . There is therefore a strong motivation to distribute the astronomical catalogues in FITS: such tables or images can be loaded transparently in astronomical image processing systems like MIDAS or IRAF, allowing e.g. immediate plotting of observed data, usage of tabulated models, or statistical analysis. 1.3 FITS: why not FITS is well accepted as a transport format; it apparently is also being commonly used for data archiving (e.g. ESO, OGIP). However, we prefer ____________________ 1 See Editorial note of Astronomy & Astrophysics 266, E1 2 Flexible Image Transport Format Wells D.C., et al., Astron. Astrophys. Suppl. 44, 363, 1981; Grosbol P., et al., Astron. Astrophys. Suppl. 73, 359, 1988 3 4 CDS Standards for Astronomical Catalogues Version 1.4 not to store the data in this format, mainly because o the data stored at CDS are data published in the astronomical literature, and we want to be able to compare by eye the computer files with the published material; the FITS ascii table files have no carriage-return, and such tables are therefore not immediately printable. o The description in FITS of the table structure is well adapted for computer usage; however, an overview of the contents of a table - which parameters, and their meaning - is not pleasant to read by a human eye; o due to the fixed-length record structure, FITS files are generally larger than standard ascii files. o due to this structure of bulk files, no standard Unix tool like grep, sort, join, paste and other awk utility which contribute to make Unix so powerful can be applied to FITS files - even no editor can be used. 1.4 Proposed solution We do not want to keep several versions of the same file: it would eat up a lot of disk space, but mainly the existence of astronomical catalogues in several standards would inevitably generate conflicts and incompatibilities. In order to be able to use the various tools, we therefore chose to keep the astronomical catalogues as plain ascii files, and to store the description of the catalogue as a separate ascii file. This description file includes all the necessary information related to the catalogue: author(s), refer- ence(s) of the related published papers, brief summary, scientific keys, caption and accurate description of each table of the catalogue. This description file - the key of the catalogue - is especially impor- tant: it must be easily readable by a human eye, and simultaneously con- tain all the information required to generate FITS files: a client/server prototype, described in Chapter 4, has been developed for remote copies of the astronomical catalogues in a few formats, including FITS. This description file is also used for checking purposes: a standalone program named anafile (see section 5) is used in this context. The standard discussed in this document mainly addresses the tabular data. Some catalogs may include data in a non-tabular form. Examples are maps supporting positional data or imagery data. This kind of data should be described in the description file on the file level. The non- tabular data should be FITS compliant with the data format is described in the headers. The FITS header information may be separately archived as an ASCII file in order to make that information readily available, at the same time allowing a quick rebuild of the FITS files. Chapter 1. The Question of Standards 5 We are currently investigating the possibility of performing this transfor- mation directly in the ftpd server - the server which is used for remote copies, and by popular tools like Mosaic. 1.5 Evolution of the document The standards proposed here are developed in the following chapters. Some points in the proposed standards are not completely fixed and possible alternatives are indicated by a footnote(3) starting with an arrow. It is also planned to make available on the network some lengthy tables and related documents. o ftp://cdsweb.u-strasbg.fr/pub/cats/doc.tex: this document o http://cdsweb.u-strasbg.fr/Cats.html: list of catalogues and tables available at CDS o ftp://adc.gsfc.nasa.gov/pub/adc/docs/ADC_keywords.lis: List of ADC_Keywords o ftp://TBD: List of Labels recommended for table headings ______________________________ 3=> Example of a footnote describing suggested revisions or alternatives Chapter 2 ---------- The Catalogue Files & Directories ------------------------------------ 2.1 The Directory Tree Each catalogue available at CDS is made of several files stored in a directory of a Unix-like file system owned by cats. Table 2.1: Directory Tree of Catalogues at CDS ______________________________________________________________________________ I/number Astrometric Catalogues II/number Photometric Catalogues (except Radio) III/number Spectroscopic Catalogues IV/number Cross-Identifications V/number Combined Data VI/number Miscellaneous Catalogues VII/number Non-stellar Objects VIII/number Radio Catalogues ______________________________________________________________________________ J/abbr/Volume/first_page Publications ordered by Journals, with abbr: A+A = Astronomy & Astrophysics A+AS = Astronomy & Astrophysics Suppl. AJ = Astron. J. ApJ = Astrophys. J. ApJS = Astrophys. J., Suppl. MNRAS = Mon. Not. R. Astron. Soc. PASP = Publ. Astron. Soc. Pacific ______________________________________________________________________________ The directory naming conventions follow exactly the standards adopted at CDS: since more than 20 years, astronomical catalogues have been numbered in categories number I to VIII (see Table 2.1) reflecting the main scientific interest of the catalogue; within each such category, a catalogue is assigned a unique number simultaneously at the CDS and at NSSDC-ADC(1). The explosion of incoming catalogues from the beginning of 1993 due to the electronic publication (see Chapter 1) lead us to introduce the J category: within this category, the catalogue designation maps the reference of the published paper, e.g. J/A+AS/97/729 for the article published in Astronomy & Astrophysics Suppl. 97, page 729. 6 Chapter 2. The Catalogue Files & Directories 7 Within this new J section, there is therefore no need for an agreement for the numbering of catalogues between data centers; finding out where a catalogue is stored, knowing its reference, is straightforward. But catalogues have not to stay in this J section for ever: later, more "con- sistent" catalogues could be generated from one or several publications - long observation sets are frequently published in several papers. 2.2 File Naming Conventions All files making up the catalogue or publication are stored in its directory as described above. The description file introduced in Chapter 1, which contains the required information to be able to understand the origin and the contents of a catalogue, is named ReadMe()2; it may also be named Intro for historical reasons in the "classical" numbering of catalogues. The contents of this important file is described in chapter 3. The are a few other special files: o =obsolete=, if existing, means that the catalogue is obsolete - typically is an outdated version. The contents of this file indicates which catalogue can be used instead of the obsolete version. o =NOT_PUBLIC= means that the catalogue is not presently available - either in a proprietary state, or not yet properly documented. The existence of such a file is normally connected to a restricted access protection of the catalogue files. o .history - a "hidden" file - contains historical notes about the catalogues. These notes resume the transformations, problems encountered and mail exchanges with the authors, and are not normally publicly available. A few rules have been adopted to assign names to the data files: 1. as much as possible, filenames should be compatible with MS- DOS limitations: filename is written name.extension, with at most 8 characters for name and 3 characters for extension; only alphanumeric characters, plus the minus sign and the underscore, are allowed; and case is not significant. When this rule is not fol- lowed, we however require that two different filenames are unique _______________________________ 1 Astronomical Data Center at NASA Space Science Data Center 2=> An alternative name for this file could be 0readme to ensure that it would be listed before any other in the ascii sequence. *** The ADC does not support the leading zero on the ReadMe file name. We feel that ReadMe is too commonly used and the prefix 0 the readability of the file name. *** 8 CDS Standards for Astronomical Catalogues Version 1.4 in the first eight charaters so that they will never collapse when the corresponding files are copied to a MS-DOS disquette. 2. for files corresponding to published material, the names are consis- tent with the published paper, and we use tablen.extension to re- fer to the table numbered n in the published paper, fign.extension for the figure numbered n, etc. 3. if the rule above cannot be applied, we use mnemonic names like main or catalog for the main part of the catalogue, refs for the references, notes for the notes, etc... 4. When there is a large number of files, we frequently use filenames of the form fn.extension, n being a sequential number. 5. the extension is related to the format of the file, with the following conventions: (no suffix) for plain ascii (or text) files; the dot is also omitted. In this case a default of .doc will be assumed for the ReadMe and Intro file names; a default of .dat for all other file names without extension. .dat for files containing the data in plain ascii form. .doc for files containing the documentation in plain ascii form. .fits for FITS files (this extension is truncated to .fit on MS-DOS disquettes). .fih for FITS headers, i.e. the top part of FITS files containing the keywords with embedded newlines. The SIMPLE.fih file is an example of such a file containing standard FITS definitions. .ori for the original files, when modifications had to be performed and the original files have to be available .sty for style files related to TeX or LaTeX definitions. .tar for files in Tape ARchive format (Unix), allowing many files to be archived as a single file. .tex for files in plain TeX or in LaTeX. Files may also be Unix-compressed or Gnu-zip compressed; a .Z suffix is appended to the filenames described above in case of Unix compression (the uncompress Unix program has to be used), and a .gz or .z in case of gzip compression (the gunzip public-domain program has to be applied). Chapter 2. The Catalogue Files & Directories 9 2.3 Index Files A set of files summarizing the catalogues currently available at CDS is updated regularly (normally on a weekly basis): o cats.all: lists all catalogues (flat ascii) o cats.lis: provides only basic information about each catalogue o cats.tex: is the LaTeX version used for publication in the Bulletin d'Information du CDS o cats.dvi: is the dvi translation of cats.tex which can used for remote display e.g. via XMosaic o cats.new: contains the same information as cats.all, for cata- logues acquired during the last month; Note that a facility exists to query this index remotely: the findcat program, which is a part of the cdsclient package, described in Chapter 4. Chapter 3 ---------- Description Standards ---------------------- 3.1 Structure of the ReadMe File The Description File introduced in Chapter 1(1) - also sometimes named Intro in the "classical" numbering of catalogues - is aimed to provide all necessary information to locate the catalogue (authors, title, ref- erences, summary, etc...) and to interpret its contents by automatic procedures. An example of the ReadMe file of the catalogue J/A+AS/97/729 is given in Figure 3.1. 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 3.4.4). 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 au- thors' names are indented (at least two blanks), and the biblio- graphic reference is enclosed between angle brackets. The stan- dard SIMBAD/NED 19-byte bibliographical reference code(s)(2) is introduced by an equal sign, as a word without embedded blank of exactly 20 characters (with the equal sign). 3. The Keywords as published (introduced by Keywords: section header), and/or other keyword description, e.g. the ADC_Keywords: controlled set(3); 4. A short description of the contents, the purpose and remarks of special importance of the catalogue introduced by Abstract: and/or Description: section headers; 5. A list of the files making up the catalogue is introduced by the File Summary: section header. This list includes the following basic _______________________________ 1=> The alternative name 0readme is proposed in Chapter 1 2 see e.g. a description in the SIMBAD User's Guide, page 65 3 See section 1.5 on how to get this list. 10 Chapter 3. Description Standards 11 J/A+AS/97/729 O-Rich late-type star lightcurves 1-20um (Le Bertre 1993) ================================================================================ Oxygen-rich late-type star lightcurves in the 1-20microm. range. LE BERTRE T. =1993A&AS...97..729L ================================================================================ Keywords: circumstellar matter - stars: late-type - stars: mass loss - stars: asymptotic giant branch - supergiants - stars: variable Abstract: The results of a photometric monitoring in the wavelength range 1-20 um are presented for 37 oxygen-rich sources. The sample contains optically identified miras (13), M-type supergiants (3), type II OH/IR sources (20) and one unidentified object. Each source was observed on at least 13 occasions (up to 42) over a lapse of at least 1250 days (up to 2150) between 1984 and 1990 with the ESO 1-m telescope equipped with its standard infrared photometer File Summary: -------------------------------------------------------------------------------- File Name Lrecl Records Explanations -------------------------------------------------------------------------------- ReadMe 80 . This file appendix 58 793 JHKL'M of 37 sources -------------------------------------------------------------------------------- Byte-by-byte Description of file: appendix -------------------------------------------------------------------------------- Bytes Format Units Label Explanations -------------------------------------------------------------------------------- 1- 20 A20 --- Name ! Star designation 22- 28 I7 d JD [2445597/2448375] Date 30- 34 F5.2 mag J 1.24um 36- 40 F5.2 mag H 1.63um 42- 46 F5.2 mag K 2.19um 48- 52 F5.2 mag L' 3.79um 54- 58 F5.2 mag M 4.64um -------------------------------------------------------------------------------- ================================================================================ (End) [CDS] 30-Mar-1993 Figure 3.1: The ReadMe file of a catalogue 12 CDS Standards for Astronomical Catalogues Version 1.4 information for each file: its name, its record length (length of the longest line), the number of records, and a short title (caption). Specifications concerning the table ordering could be defined here, as a set of label names enclosed within square brackets(4). A typical example could be [RAh,RAm,RAs]+ 6. A description explaining which are the columns of the tables, how to get the values stored in these columns, and what is their mean- ing 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: (a) 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. (b) the Fortran Format as used by FITS which specifies how to interpret numbers or symbols(5); (c) the Unit in which the value is expressed; unit standards are detailed below (section 3.2). The symbol --- indicates unit- less values. (d) a label or column header. A few standard names and name building rules are detailed in section 3.3. (e) a short explanation of the contents of the column. This last field may also specify: o a set of valid characters for an alphabetical column, or limits for numeric columns: see section 3.4.1. o whether the column is ordered: see section 3.4.3 o whether blank (unspecified) numbers are allowed: see section 3.4.2 o a key to more detailed notes: see section 3.4.4 7. some other sections may exist when required, e.g. Acknowledge- ments:, Historical Notes:, References:, etc... The section headers should be left flushed. _______________________________ 4=>This extension is not yet a standard. The ordering (when only a single column is involved) can be specified in the Byte-by-byte Description as explained in section 3.4.3; in case two ordering are specified, the one in the File Summary section should prevail on the Byte-by-byte Description one. 5) the format could be preceded by an iteration factor to designate an array of values. Chapter 3. Description Standards 13 8. the very last line includes just the left-flushed word (End), the date of the last modification, and generally the name of the person who took care of the standardisation. 3.2 Units The unit in which physical parameters are expressed is a fundamental parameter which becomes especially important when data are used out- side 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"oms (A= 10-10 m), since the Angstroem is a non-standard unit. Another example is mW/m2 , the milliwatt per m2, which is identical to the obsolete erg/cm2/s. The standard adopted here differs from the OGIP ones(6) for the syntax of composite units (operator symbols), and in the usage of math func- tions and obsolete CGS units which are rejected here; the basic symbols however agree. Only simple power functions of physical units are accepted, which means that e.g. solMass to the power 3/2 (solar mass at a 3/2power) or log(K) (logarithm of Kelvin) cannot be a valid unit; in the latter case, the label has to specify that the log function is applied to a unit which is expressed in K. 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"om 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 factor|unit_expression and we will write the "number of pixels per A" as 10pix/nm, and neither pix/0.1nm nor pix/(0.1nm). The numerical factor may include the letter x for the multiplica- tion, as 1.5x10+11 to express the number 1:5 x 1011 _______________________________ 6 OGIP memo 93-001 about "Specification of Physical Units within OGIP FITS files" by Ian M. George & Lorella Angelini, August 1993 14 CDS Standards for Astronomical Catalogues Version 1.4 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 10 to the 21-st power. 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 3.2.2) eventually preceded by a multiple prefix (see section 3.2.3) Among several possible expressions of a unit, it is preferable to choose the shortest one; this leads also to prefer the division (/) to the multi- plication of the inverse, e.g. prefer km/s to km.s-1. 3.2.2 Basic symbols The basic symbols listed in Table 3.1 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 Table 3.2. 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 micro-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. paren- theses or other punctuation signs. Table 3.3 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(7). A parameter has frequently associated values, and we have adopted the rule of association with the one-letter underscore prefix: if a column is _______________________________ 7=> ADC plans to compile and perhaps put up a file accessible (see section 1.5) Chapter 3. Description Standards 15 Table 3.1: List of Units: (b) are basic SI units, (a) are IAU extensions, (c) are CDS extensions, and (e) are extensions used in physics. ______________________________________________________________________________ List Symbol Explanation Definition ______________________________________________________________________________ (c) --- Unitless value (c) % Unitless value, in percent 10-2 (a) a year (also yr) 365.25d = 31.5576 x 10+6s (b) A Ampere (a) AU astronomical unit 1.49598 x 10+11m (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) A.s (b) cd Candela (luminous intensity) (c) ct Count (events) (a) d day 24h = 86.4 x 10+3s (a) deg degree of arc pi/180 rad (e) eV electron-Volt 1.602177 x 10-19 J F Farad (electric capacitance) C/V (b) g gram 10-3 kg (a) h hour of time (sideral if 3600s appropriate) H Henry (inductance) Wb/A Hz Hertz (frequency) s-1 J Joule (energy) N.m (a) Jy Jansky 10-26 W/m2/Hz (b) K Kelvin lm lumen (luminous flux) cd.sr lx lux (illuminance) lm/m2 (b) m metre (a) mag magnitudes (a) mas millisecond of arc (pi/6.48) x 10-8 rad (a) min minute of time (sideral if appropriate) (b) mol mole N Newton (force) kg.m/s2 ohm Ohm (electric resistance) V/A Pa Pascal (pressure) N/m2 (a) pc parsec 3.0857 x 10+16m (c) pix pixel (image element) (b) rad radian (angle) (e) Ry Rydberg (energy) 13.60583 eV (b) s second of time S Siemens (electric conductance) A/V (c) solLum Solar luminosity 3.826 x 10+26 W (c) solMass Solar mass 1.989 x 10+30 kg (c) solRad Solar radius 6.9599 x 10+8 m (c) Sun Unit referring to the Sun (e.g. abundances) sr steradian (solid angle) T Tesla (magnetic field Wb/m2 intensity) V Volts (electric potential) W/A W Watt (power) J/s Wb Weber (magnetic flux) V.s (c) yr year (also a) 365.25d = 31.5576 x 10+6s ______________________________________________________________________________ 16 CDS Standards for Astronomical Catalogues Version 1.4 Table 3.2: Symbols used to express multiples and submultiples _____________________________________ _____________________________________ Symbol Explanation Value Symbol Explanation Value _____________________________________ _____________________________________ d deci 10-1 da deca 10 c centi 10-2 h hecto 10+2 m milli 10-3 k kilo 10+3 u micro 10-6 M mega 10+6 n nano 10-9 G giga 10+9 p pico 10-12 T tera 10+12 f femto 10-15 P peta 10+15 a atto 10-18 E exa 10+18 z zepto 10-21 Z zetta 10+21 y yocto 10-24 Y yotta 10+24 _____________________________________ _____________________________________ obviously associated to another one - typically mean errors or uncer- tainty flags - we use one of the underscore prefixes listed in Table 3.4. Usual mathematical functions may be specified in the label, with paren- theses 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 expla- nation 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 de- tailed in section 5. 3.4.1 Limits Limits in a column can be specified in the explanation column, with values enclosed within square brackets [ or ](8); the square bracket must be _______________________________ 8 The square brackets are not part of the EBCDIC character set; the angle brackets < > could eventually be used instead of the square brackets. Chapter 3. Description Standards 17 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 3.4.4). 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 Table 3.4); this feature can be specified as follows: Table 3.3: Conventions used for some labels _______________________________________________________________________________ Symbol Explanation Default Limit _______________________________________________________________________________ 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 (a) Right ascension expressed in decimal degrees [0, 360[ RArad Right ascension expressed in radians [0, 2pi[ 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 (b) Declination expressed in decimal degrees [-90, +90] DErad Declination expressed in radians [-pi/2,+pi/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 Sp Spectral type MType Morphological type _______________________________________________________________________________ _______________________________ a=> 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. b) 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. 18 CDS Standards for Astronomical Catalogues Version 1.4 Table 3.4: Conventions used for label prefixes ______________________________________________________________________________ Symbol Explanation Default Limits ______________________________________________________________________________ 2_label O2 value on parameter label >= 0 a_label aperture used for parameter label >= 0 e_label mean error (oe) on parameter label >= 0 f_label number of degrees of freedom on parameter label >= 0 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 _____________________________________________________________________ 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 also 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 accept- able 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] spec- ifies 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 Table 3.3 and Table 3.4. 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 . Chapter 3. Description Standards 19 3.4.2 NULL values A NULL or unspecified value is always indicated by setting all bytes of the column to blanks9. 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: 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 Figure 3.1, 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(10). 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: _______________________________ 9=> using out-of-range values to specify NULLs - typically numbers made of 9's only - is required by some FORTRAN users. 10=> An alternative way of defining the order is proposed in the File Summary part described in section 3.1 20 CDS Standards for Astronomical Catalogues Version 1.4 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) Figure 3.2: A first alternative to write lengthy explanations Chapter 3. Description Standards 21 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) Figure 3.3: A second alternative to write lengthy explanations 22 CDS Standards for Astronomical Catalogues Version 1.4 1. an * at the very beginning of the short explanation column indi- cates 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 illus- trated in Figure 3.2; 2. a parenthesed number representing a footnote number as the very last word of the short explanation column; the details are intro- duced at the end of the table by a Note (n): section header. An example of this way is illustrated in Figure 3.3 3.5 Transformation to FITS The data files can be automatically transformed into FITS: Figure 3.4 shows the ascii table extension header generated from the description file shown in Figure 3.1. Files can be copied directly in this format with the cdsclient routines described in Chapter 4. This set of programs also includes for instance an access to the 1.1 version of the Guide star catalogue (section 4.6) as well as a few other utilities related to the Catalogue Service or SIMBAD at CDS. We are also currently investigating the possibility of performing the transformation to FITS directly in the ftpd server _ the server which is used for remote copies. Chapter 3. Description Standards 23 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?) EXTNAME = 'appendix' / JHKL'M of 37 sources ======================================================================= TFIELDS = 7 / Number of data fields (columns) TBCOL1 = 1 / ============== Start column +0 TUNIT1 = '. ' / Unit: . 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 Figure 3.4: The FITS extension header constructed from the ReadMe file of Figure 3.1 Chapter 4 ---------- The cdsclient package ----------------------- A catalogue server has been installed on the computer where the as- tronomical catalogues are stored, at Internet node cdsarc.u-strasbg.fr = 130.79.128.5. This server is able to talk to a client routine running on some other Internet node running Unix. A few such clients are freely available as the compressed file cdsclient.tar.Z in the di- rectory /pub/cats of the CDS anonymous ftp account installed on the same node (cdsarc.u-strasbg.fr). This package consists in a small set of C routines used to create a general- purpose client named aclient, and of a set of shell scripts making use of aclient. 4.1 Installation of cdsclient The installation should be easy on Unix computers. 1. zcat csdclient.tar.Z | tar xvf - 2. make compiles the required sources in the current directory; 3. make install moves the varisous pieces to the standard directo- ries /usr/local/bin for the executables, /usr/man/manl for the manual pages. 4.2 findcat This program allows to find out a catalogue from an author's name, or a set or words appearing simultaneously in the title of the catalogue. It also lists the known details about a catalogue specified by its CDS/ADC number. Synopsis: __________________________________ | findcat [-l] word [word.....] | |_________________________________| A word may also be a catalogue number, e.g. 3111 or III/111, or the name of an author, e.g. VERON, or words related to the contents of the catalogue, like X-RAY. 24 Chapter 4. The cdsclient package 25 4.3 lscat This program displays a summary of the files making up a catalogue. Synopsis: ___________________________________ | lscat catalogue [catalogue...] | |__________________________________| 4.4 catcat This program connects to the cdsarc machine, and retrieves selected or all files making up a catalogue as standard ascii text (the default), in tar (tape archive) format, of in FITS format; the files may be compressed. Synopsis:______________________________________________________________ | catcat [-lines] [-tar[.Z] | -fits[.h|.Z]] catalogue[/file] | |_____________________________________________________________| The options are: o -lines specify how many lines from each file are to be displayed. The default is all lines o -tar: get all files of the catalogue in tar (tape archive) format. o -tar.Z: format should be compressed tar (files normally ending with the .Z suffix) o -fits: get the file in FITS format. In order to get on the termi- nal the appendix file of the catalogue J/A+AS/97/729 shown in Figure 3.1, the command is: catcat -fits J/A+AS/97/729/appendix while the command catcat -fits J/A+AS/97/729 gets all files making up the catalogue as a single FITS file. o -fits.Z: the FITS file is compressed before being sent. o -fits.h: get the FITS headers only as standard ascii records (i.e. with embedded newlines) The result is sent to the standard output; a redirection has therefore to be used. For instance, a copy of the files making up the catalogue J/A+AS/97/729 in the current directory make be executed as catcat -tar J/A+AS/97/729 | tar xvf - 26 CDS Standards for Astronomical Catalogues Version 1.4 For large catalogues, the compressed version may be faster. For instance, to get the annex file named tica of the Tycho Input Catalogue numbered I/197 in FITS format as your file named tica.fits: catcat -fits.Z I/197/tica | uncompress > tica.fits If we just want to list the Intro file of this catalogue on the terminal: catcat I/197/Intro 4.5 findacro This program allows to retrieve the meaning, references, etc... of catlogue designations from the Dictionary of the Nomenclature of Astroomical Objects(1). It provides the same results as what can be found on the free account info installed on the simbad computer (Internet node simbad.u-strasbg.fr = 130/.79.128.4) with a command starting by cati Synopsis: __________________________________ | findacro catalogue_acronym | |_________________________________ | 4.6 findgsc This program allows to query by coordinates the Guide Star Catalogue Version 1.1. Synopsis: __________________________________________________ | findgsc J2000_center [-r radius_in_arcmin] | |_________________________________________________ | 4.7 simbib This program allows to query the SIMBAD set of references: about 100,000 references used in the SIMBAD data-base, starting in 1950; these references contain the names of the authors and the titles. Synopsis: ______________________________________ | simbib [minimal_year] word.... | |_____________________________________| All SIMBAD references in which the set of specified words are simulta- neously found are listed. _______________________________ 1 Fernandez A., Lortet M.C., Spite F., 1983, Astron. Astrophys. Suppl. Ser. 52 N. 4; Lortet M.C., Spite F., 1986, Astron. Astrophys. Suppl. Ser. 64, 329; Lortet M.C., Borde S., Ochsenbein F., 1994, in preparation. Chapter 5 ---------- Selected "Manual Pages" ------------------------- A few programs which are readily available on the anonymous ftp ac- count are detailed here. anafile is a standalone program which is used to interpret a ReadMe or Intro file, and check whether the data conform to the description. aclient is the general-purpose client routine used in the various facilities of the cdsclient package (chapter 4) _____________________________________________________________________________ anafile (Rev. Oct-1994) analyze a file and print statistics. (1) _____________________________________________________________________________ Syntax anafile [-v] [-l] [-a] [-u] [-cc] [-f[x] format_file] [-w width] [file...] Description The anafile command analyses the beginning or the complete file(s), checks on request the conformity to a format, assigns a file class to each file, and lists on request the column (byte-per-byte) statistics. The possible file class values are: o ascii file standard ascii file, where no other control characters than tabs, carriage-return and line-feed can be found. o ascii mailable may include other control characters like bell or escape which can be sent over the network without problem. o ascii binary includes control characters which cannot be sent over the network, like Control-Q. (see also the -a option) o ascii bulk does not include any line-feed, which means that the file cannot be seen as a set of lines. (see -w option) o ebcdic EBCDIC (IBM-specific) file o fits FITS file (bulk file with all headers) o hdf FITS header (starting with SIMPLE or XTENSION) without the data part, and stored as a standard ascii file. o binary file which cannot be classified in one of the above categories. 27 28 CDS Standards for Astronomical Catalogues Version 1.4 Options Without any option, anafile examines the first 2880 bytes, and assigns the file class. -a lists the position (line and column numbers) of each character which leads to a classification as ascii binary or binary file. -cc generates a detailed list of the frequencies of every character in each column: the characters of each column are listed in order of their decreasing frequency. -fx format_file uses the contents of format_file to check the compliance of the file to the specified format. The x may be used for further options concerning this format file like computation of ranges, verifications against the CDS Standards, etc... (see the section Format File below). -l asks to examine the complete files to assign the file class, and lists the number of lines as well as the number of bytes of the longest line. -u lists the columns which are constant (i.e. have exactly the same contents) over all lines. This option may be used to check that e.g. that the decimal points are correctly aligned, or to find out the blank columns which could be removed with trcol(1). -v is a verbose option. -w width specifies the assumed column width for ascii bulk or ebcdic files; such files have no linefeed embedded, and the length of each line must be assumed. Format File A typical format file (specified via the -f option) contains the following: Byte-per-byte Description of file: hbc ------------------------------------------------------------------- Bytes Format Units Label Explanations ------------------------------------------------------------------- 2- 4 I3 --- HBC [1,423]+ HBC number. 5 A1 --- NEBUL [n] Nebulosity association flag. 6 A1 --- REMARK [*] Remark flag. 8- 18 A11 --- NAME [A-Z0-9@.+-]! Star name. 20- 56 A37 --- OTHER Other designation. 59- 60 I2 h RAh Hours of right ascension (1950.0). 62- 63 I2 min RAm Minutes of right ascension. 65- 69 F5.2 s RAs Seconds of right ascension. 71 A1 - DE- Sign of declination (1950.0). 72- 73 I2 deg DEd Degrees of declination. 75- 76 I2 arcmin DEm Minutes of declination. 78- 81 F4.1 arcsec DEs Seconds of declination. 83- 90 A8 --- REF References to the position. ------------------------------------------------------------------- Chapter 5. Selected "Manual Pages" 29 The format file is made of five columns: the byte position, the format,the units, the label and an explanation text. Such a file is interpreted by anafile , is reedited in a standard form (on the screen if the -v option is present, or the format file is rewritten with the -fw option), and is used for data check. Note also that special labels are understood by anafile (see Special Labels below). The explanation text may contain further restrictions concerning the range for numeric fields or the character set allowed for alphabetical field; refer to Validity Checks section below. Note that the byte position may be specified as relative from the end of the previous field when followed by the X letter, as it is in Fortran. The number preceding the X therefore represents the number of blanks between the two columns. With the -f. (a dot following the f) option, the input format file does not include the units column; the reedition fills this column with dashes - With the -f1 (a one following the f) option, the first column of the input format file contains only the starting byte of the column; the ending byte is derived from the format column. The reedition completes this column with the ending byte. With the -fr option, the actual ranges (minimal / maximal values) of each column are computed. With the -fs option, the format file is assumed to conform to the CDS Standards for Astronomical Catalogues; further compliance checks (presence of titles, correctness of units, etc...) of this format file are then performed. With the -fw option, the format file is rewritten according to standards. The format options may be combined, e.g. -f1.w asks to rewrite format file where no units and no ending columns were supplied. Special Labels Some labels are recognized and further checks are performed. The complete list with implied defaults are listed in the CDS Standards for Astronomical Catalogues. A few frequently used labels are: o Right ascension fields RAh, RAm and RAs o Declination sign DE- (only a sign or a blank is accepted) o Declination values DEd, DEm and DEs 30 CDS Standards for Astronomical Catalogues Version 1.4 o Positions in decimal degrees RAdeg (range [0; 360[) and DEdeg (range [-90; +90]) o Galactic positions GLON (range [0; 360[) and GLAT (range [-90; +90]) o Position angle PA Validity Checks The first word (i.e. set of characters followed by a blank) of the explanation of a column may specify validity checks to perform about: 1. the available range of the value in the column 2. the possibility of blank or NULL values 3. the order of the value within the table (increasing / decreasing value) For a numerical field, a range can be specified in the format file if th expla- nation text starts with a square bracket [ ] as in the HBC column in the above example. The opening bracket is [ if the lower value is included, and ] if the lower value is excluded - i.e. the standard mathematical conventions apply. Both lower and upper values are not required; for instance, the specification of any value lower than 100 (100 excluded) is specified by [,100[. Writing [] is acceptable when no range checking applies - e.g. to override the default range implied by the label (see Special Labels section above). For an alphabetical (i.e. A-format) field, the set of the allowed characters may be specified in the format file if the explanation text starts with a square bracket [: permitted characters are surrounded by square brackets [...], and the dash indicates a range (in the ascii sequence). The closing bracket is accepted as a character permitted in the set if it is specified first (i.e. []] means that only the closing bracket is acceptable); the dash is accepted when it is first or last character. On the above example, only n (or blank) is accepted in the NEBUL column, and uppercase letters, digits, and the symbols @ . + - in the NAME column. An exclamation mark ! following immediately the range or character-set spec- ification indicates that the field cannot be blank, i.e. cannot be filled with only blanks. In the above example, the Name field can never be blank. A question mark ? following immediately the range or character-set specifica- tion indicates that the field can be blank, i.e. can be filled with only blanks. The default concerning blank fields is: o numeric field: the column cannot be filled with blanks, unless the ? symbol exists; o alphabetic (A-format) field: the column can be filled with blanks; the ! means that a completely blank field can't exist. Chapter 5. Selected "Manual Pages" 31 The question mark may be followed immediated by a numeric value to desig- nate non-blank NULL values, e.g. ?=99.99 telling that values 99.99 indicate unknown values. The order within a column can be specified with the signs: + indicates strictly increasing values in the table; - indicates strictly decreasing values in the table; = , associated to + or -, indicates that the variation is not strict, i.e. the row number n + 1 may have a value larger than or equal to that of row n if += is specified. Returned Status The anafile command returns 0 in case of success. A non-zero status may in- dicate bad options or unreadable files; it is also returned when the format_file indicated by a -fs option does not conform to the CDS Standards for Astro- nomical Catalogues. See also awk(1) gawk(1) trcol(1) "CDS Standards for Astronomical Catalogues" _____________________________________________________________________________ tofits (Rev. Aug-1994) Transform a set of documented files into FITS. (1) _____________________________________________________________________________ Syntax tofits [-v] [-u[1|2]] [-fih] [-noh] [-w[.fih]] [-z|Z] [-nodata] [-d data_directory] [-i description_file] [-o output_file] [-s SIMPLEheader_file] [file...] Description The tofits command translates a set of files described according to the CDS Standards (see the CDS Standards for Astronomical Catalogues document) into FITS tables. The result may consist of either plain FITS files (bulk files including data description and the corresponding values), or of only the headers, i.e. the description of the data as plain ascii files; the latter files are normally named *.fih files. 32 CDS Standards for Astronomical Catalogues Version 1.4 The creation of the plain FITS files follows the following algorithm: o With the -fih option, from a set of FITS headers files (*.fih files) and of data files as follows: 1. the basic FITS header (on top of all tables) is specified via the -s option; its default name is SIMPLE.fih 2. for each table, the TABLE header and the data file, files named file.fih and file. The complete FITS creation for a set of n tables therefore requires 2n+1 files, the data tables plus n + 1 *.fih files. o Without the -fih option, the Documentation File (ReadMe) (see also anafile(1)) is used to generate the missing *.fih files. A full FITS generation may if necessary be driven by a special shell script stored in a file named .MakeFITS. Note that some files (e.g. tex files, postscript files) are normally not converted to FITS. Options Without any option, tofits uses the ReadMe file, data and *.fih files in the current directory and transforms all files described in ReadMe into a single FITS file displayed on the terminal. -d data_directory indicates the directory containing the relevant files (ReadMe, data files, *.fih files, etc). The default data_directory is the current directory. -help displays a detailed help. -fih tells that no ReadMe file is required, all descriptions do exist as *.fih files; the top header is named SIMPLE.fih, unless another name is specified via the -s option. -i description_file provides the non-standard (Intro or ReadMe) name of the Description file; -nodata asks to generate only FITS headers (similar to *.fih files); the data files are ignored. -noh asks not to generate the top (SIMPLE) header; this option is especially useful to append a new FITS table to an existing FITS data set. -o output_file designates the file replacing the default stdout (terminal). 33 CDS Standards for Astronomical Catalogues Version 1.4 -s SIMPLEheader_file provides an alternative name to SIMPLE.fih -u allows to select how to write the comments related to the units: the -u1 option comments each unit with its SI (Systeme International) value, while -u2 option comments each unit with both litteral and SI counterpart. -v is a verbose option. -w asks to write a new file for each FITS table; with this option, there are as many FITS files generated as data files, each being a complete FITS file including the top header, a table header and the corresponding data. The names of the files generated this way have a .fit extension. -w.fih asks to write a new file for each table header (generation of *.fih files). The names of the files generated this way have a .fih extension. -Z compresses the resulting files with the standard Unix compress(1) routine -z compresses the resulting files with the gzip(1) utility Files The file... specified on the command line represent the files which should be converted to FITS. The default is to convert all described files, i.e. all files included in the File Summary section of the ReadMe file, with the exception of the non-convertable files. The dot . as a file name asks to stop the conversion; this is useful if one wants to generate only the top header, as in tofits -nodata -i DescriptionFile . > SIMPLE.fih Note that if the file argument is a directory, it has the same effect as it were preceded by the -d flag. Non-converted files The extension of filenames is used to decide that a file should not be converted into FITS. Files with names ending by .fih, .fis, .tex, .dvi, .ps, .doc, .sty and .tar are not converted. 34 CDS Standards for Astronomical Catalogues Version 1.4 .MakeFITS script When a .MakeFITS file exists, it is called from tofits (via the Bourne shell /bin/sh) to generate all FITS files: this can be executed only when tofits is called without any file argument. This script may use (and change) the following numeric environment variables which are set by tofits before calling .MakeFITS: o toFITSd=0 to generate only the headers (option -nodata) o toFITSh=0 to skip the SIMPLE header (option -noh) o toFITSm=1 to use the FILEMARK extension (which separates two FITS files) o toFITSr=1 is the recursivity count, incremented each time tofits is called. The .MakeFITS script may (recursively) call tofits . Returned Status The tofits command returns 0 in case of success, and non-zero when errors are found. See also anafile(1) compress(1) gzip(1) "CDS Standards for Astronomical Catalogues"