STARLIST FORMATS

This document describes starlist formats supported by Lick's starlist reading program coords, a flexible parser that supports numerous formatting options at the 3-m and 1-m telescopes.

Contents: Standard Format | Comment Directive | Data Directive | Examples HOME
I. THE SIMPLEST CASE: STANDARD FORMAT
The standard format for a line, designating a single target, contains the following required fields in the order shown:
objectname  h m s  d m s  equinox 

All fields are normally separated by whitespace.  (A common mistake is to put spaces into the object's name.)   The position fields may optionally be separated by colons (h:m:s d:m:s).

If colons are not used to separate the fields, you can use decimal hours, degrees, or minutes in any RA or Dec entry. When coords sees a decimal point in one of these fields, it extracts the remaining fields from the fractional part. For example, the following lines are equivalent:

obj1a
12 34 56 1 2 3 2000.0
obj1b
12.58222222 1 2 3 2000.0
obj1c
12 34.9333333 1 2 3 2000.0
obj1d
12 34 56 1.034166667 2000.0
obj1e
12 34 56 1 2.05 2000.0

The standard format may be expanded to include optional fields:

objectname  h m s  d m s  equinox [key=val ...] [comment]

Optional fields are interpreted as zero or more (keyword)=(value) fields. Anything following a keyword/value pair, other than another keyword/value pair, is interpreted as comment text. The currently defined keyword/values are:

pmra=xxx Proper motion in RA, mas/yr (default 0.0).
pmdec=xxx Proper motion in dec, mas/yr (default 0.0).
pmepoch=xxx Epoch of proper motion (default same as equinox)
mag=xxx Magnitude (default 0.0).
?mag=xxx
?=xxx
?=any letter, e.g. Jmag or Vmag (default 0.0).
?=any letter, e.g. J or V (default 0.0).
pri=nnn Priority of object.

N.B. Older versions of coords required a magnitude to follow the equinox. Though discouraged, this is still allowed for backward compatibility using the following format:

objectname  h m s  d m s  equinox [mag] [key=val ...] [comment]

The rule is: if the equinox field is followed by a number, that number is interpreted as a magnitude. Therefore, if a comment follows the equinox field, and if that comment begins with a number, the comment will be misinterpreted as a magnitude. Specifying magnitude with the the mag keyword is preferred.

II. IGNORING JUNK: COMMENT DIRECTIVES
Comment lines and other "junk" lines that you wish coords to ignore, can be filtered from input files by using the Comment Directive, The Comment Directive is a line in the input file beginning with !Comment in the first column, followed by a list of grep-type patterns. Any line that matches one of these patterns is interpreted as a comment and discarded.

For example, the comment directive: !Comment {^#} {Object.*RA}, contains the two patterns ^# and Object.*RA. It tells coords, respectively, that any line beginning with # or any line containing Object ... RA is a comment and should be ignored.

Notes:

1. If a pattern contains whitespace, $, or [, you must enclose the pattern in braces.
2. A blank line is always a comment. You can't change this, and you don't need to include blank lines in your comment patterns.
3. The default comment rule !Comment {^[ \t]*#} matches any line that begins with optional whitespace followed by #.


III. MASSAGING INPUT: DATA DIRECTIVES
If data lines (non-comment lines) are not in coord's standard format, they can be made readable with the use of the Data Directive: a line in the input file beginning with !Data in the first column.

Bearing in mind that coords always requires object name, RA, Dec, and equinox for each entry, and that other data are optional, you can use the Data Directive to tell coords

  • the order in which data appear on each line
  • how to skip fields in the data that coords can't use
  • to supply values for required fields that aren't in your tabular data (e.g. you can specify equinox=2000.0 for all lines).

The Data directive consists of !Data followed by a list, each of whose values is in turn a one- or two-element list of the form:

    fieldname or {fieldname fieldformat}

The field names you can put in a !Data directive are:

Fieldname Description Notes
name object name
ra_h RA, hrs
ra_d RA, deg Unusual case: RA units are degrees.
ra_m RA, min
ra_s RA, sec
ra_hms RA, h:m:s See "special cases", below.
ra_dms RA, d:m:s Like ra_hms, but units are degrees.
dec_d dec, deg
dec_m dec, min
dec_s dec, sec
dec_dms dec, d:m:s See "special cases", below.
equinox - Can precede values with B or J to tell reference frame (FK4 or FK5), e.g. J2000.0. Default is FK4 if equinox <= 1975, else FK5.
mag magnitude Optional magnitude: if corresponding value is numeric, it gives the object's magnitude; if it isn't numeric, coords acts as if the mag fieldname was not present. Magnitude may be designated as mag=xxx, ?mag=[xxx], or ?=xxx, where ? represents a letter designation such as V or J. See table section I.
keyval various Matches 0 or more key=value entries (see below). Any fieldformat is ignored.
comment -

For example, name and {dec_d %s} are valid list elements. The fieldformat is a scanf format that will read the field value into a variable. Generally, all elements should be treated as simple strings (even for numeric fields), and thus a fieldformat like %s is the preferred format.

When the fieldname is keyval then coords will match 0 or more key=value entries embedded in each data line, where the key-val fields are:

mag=xxx Magnitude (default 0.0).
?mag=xxx
?=xxx
?=any letter, e.g. Jmag or Vmag (default 0.0).
?=any letter, e.g. J or V (default 0.0).
pmra=xxx Proper motion in RA, mas/yr (default 0.0).
pmdec=xxx Proper motion in dec, mas/yr (default 0.0).
pmepoch=xxx Epoch of proper motion (default same as equinox)
pri=nnn Priority of object.

You can use decimal hours, degrees, or minutes in any RA or Dec entry. When coords sees a decimal point in one of these fields, it extracts the remaining fields from the fractional part. For example, the following lines are equivalent:

obj1a
12 34 56 1 2 3 2000.0
obj1b
12.58222222 1 2 3 2000.0
obj1c
12 34.9333333 1 2 3 2000.0
obj1d
12 34 56 1.034166667 2000.0
obj1e
12 34 56 1 2.05 2000.0

Even if you are using decimal values in the data fields, you must still specify all three of the h,m,s or d,m,s fields in any !Data directive. Coords will recognize on its own whenever decimal data are present, and will then not expect to see minutes and/or seconds fields for that RA or Dec value.

If and only if coords is expecting to read an hours or degrees value from a field, and the field matches xx:mm:ss, then the minutes and seconds values are also read from the field.  (Note that both minutes and seconds are required: you cannot mix decimal minutes with a colon!)

Special Cases:

  • !Data without any following arguments restores default line processing.
  • The fieldname skip may appear any number of times, and it means that the corresponding data are ignored. This tells coords to skip over columns that aren't meaningful to coords.
  • If the format is missing, %s is assumed.
  • If the format is %n, where n is any integer (e.g. %10), coords reads a fixed-width field that is n characters wide. You can use this when your object names contain whitespace (see the examples below).
  • The format * stands for "rest of the line", and is replaced by the scanf format %[^\n].
  • If the fieldformat doesn't contain a % and isn't *, then it is a literal value for the field. This is useful to supply fixed-value fields that aren't present in the lines of data. For example, {equinox J2000.0} will set the equinox and reference frame.
  • A fieldformat cannot be used with ra_hms, ra_dms or dec_dms. That is because ra_hms is internally handled by replacing it with {ra_h %[^:]} {ra_m :%[^:]} {ra_s :%s} Similar substitutions are done for ra_dms and dec_dms.  Note that this format explicitly requires a colon between fields.
  • When matching dec_d, and the fieldformat isn't specified (or is simply %s), then the optional leading sign may be space-separated from the rest of the value, e.g. - 1 23 54. (Before the fieldformat is used, the sign is right-shifted to snuggle up against the next value.)
IV. EXAMPLES
1. All the standard cases described in section I, above, are handle by this format, which is used by coords as the default:
name ra_h ra_m ra_s dec_d dec_m dec_s equinox mag keyval {comment *}
2. Suppose the object names are in a 20-character fixed-width field and some of them contain whitespace, and the RA and Dec are in [xx:mm:ss.s] format. Then you can use this !Data directive:
{name %20} ra_hms dec_dms equinox mag keyval {comment *}
3. Suppose the equinox isn't given (yet is known to be 2000.0), and that the magnitude is in the column after the declination:
XXX92.412 00 55 16 +01 01 58  15.036  ...
the !Data should be
name ra_h ra_m ra_s dec_d dec_m dec_s mag {equinox 2000.0} {comment *}
4. Suppose the data are of the form
XX92.412 00:55:16 +01:01:58  yadda-yadda 15.036  ...
the !Data could be
name ra_hms dec_dms {epoch 2000.0} {skip %11} mag {comment *}