Coords reads a starlist file and displays each object in the list with its RA, Dec, epoch, and magnitude (and optionally other parameters). Coords primary purpose is to select coordinates and send to the the telescope pointing control program, POCO. In addition, it can display the current hour angle (HA), zenith distance (ZD), parallactic angle (ParAng) and airmass (AM) of each object in the list. The list may be sorted by any of the displayed parameters for ease of locating a specific object or selecting based on a certain criteria (e.g. HA close to 0:00). Coords is started on any of the user computers by typing coords at the prompt. Upon startup you may be queried, "POCO is available. APF eostele is available." with options for connecting to POCO, APF, or None. If so, select the option of connecting to the telescope pointing control program (POCO). If you are connected to POCO, you may send the coordinates displayed in the "Catalog:" field to POCO by pressing the Send to POCO button. This is a particularly easy way to give the telescope operator the coordinates for the next object. Additionally, for certain instruments (Kast, Hamilton, ShARCS, Nickel Direct), you may send the selected object name to the data-taking software by pressing the Send Object Name button. Coords will, by default, load in the last file read. If you wish to load a new file, the New File... button first brings up a question whether you want to load a new file from disk or a URL. If you select File, a browser window allowing you to select and load a different file. If you select URL, an entry window will appear where you can type the URL of the file. Optionally you may put the file name or URL as an option when starting coords, for example to read a local file: coords /u/user/observers/egates/starlist_2021Jun15.txt or a file on-line: coords http://mtham.ucolick.org/egates/starlist_2021Jun15.txt You can select a target from the list by clicking on it, and its coordinates will appear in the "Catalog:" field. By clicking on Get Chart, you can get a sky chart of the selected object. There are currently three sources for sky charts. SkyView and STScI (default) give you a chart from the digital sky survey (15 arcminute field of view with a box denoting the central 3 arcminutes). The APM chart option gives you a plotted sky chart with a 5 arcmin field of view. You may sort the list by any of the following data: Line, Object, Right Ascension (RA), Declination (Dec), Hour Angle (HA), Zenith Distanc (ZD), Airmass (AM), Parallactic Angle (ParAng), Magnitude (mag), RA proper motion (pmra), Dec proper motion (pmdec), or Comment. The units for pmra and pmdec should be in milliarcsec/year. You may display additional information, calculated from the current sidereal time and target coordinates from the AddOns... button. Airmass, HA, ZD, and ParAng are all available from the AddOns menu.

Coords (Click for full-size image)

Listed below are the starlist formats supported by the coords program, a flexible parser that supports numerous formatting options at the 3-m and 1-m telescopes.

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).
exptime=xxx	Exposure time in seconds. If given, the parallactic angle (ParAng) will be calculated for the midpoint of the exposure.
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.

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

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}

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)
exptime=xxx	Exposure time in seconds. If given, the parallactic angle (ParAng) will be calculated for the midpoint of the exposure.
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:

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

1. All the standard cases described in section I, above, are handled 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 *}

5. If you have a Keck style target list you may add this line at the beginning so the file will be read in properly to the coords program:
   

   !Data {name %16} ra_h ra_m ra_s dec_d dec_m dec_s equinox keyval {comment *}

6. A star list may have multiple data statements to handle different types of objects, e.g. standard stars vs. science targets.
   

   !Data {name %20} ra_h ra_m ra_s dec_d dec_m dec_s equinox exptime {comment *}
   Feige 34            10 39 36.7 +43 06 09   2000.0  120 Primary standard
   BD+284211           21 51 11.0 +28 51 50   2000.0  120  Primary standard
   !Data {name %20} ra_h ra_m ra_s dec_d dec_m dec_s equinox {comment *}
   Mrk110              09 25 12.9 +52 17 10   2000.0  P1 PA=44  2x300s
   Mrk684              14 31 04.8 +28 17 14   2000.0  P2 PA=60  2x900s