Serving
the
Exoplanet
Science
Community

KI Tutorial: How to Prepare a Schedule File

What is a Schedule File?

The schedule file is a simple ASCII file which contains information about targets and calibrators to be observed by the KI. There is one line of information per target or calibrator, plus comment lines.

The format of the lines in the schedule file is described below, and has been adopted as the standard for exchanging this information between KI observers, the NExScI and the Keck Observatory.

Using this adopted format, KI observers send their NExScI contact scientist their list of targets and calibrators, which after being reviewed and checked at the NExScI, is incorporated into a nightly schedule file containing all observations to be made on a given night, and sent to WMKO for execution.

Please send your schedule file to your NExScI contact scientist in a simple email. In this email, you may also communicate your wishes about how the observation should be conducted (e.g. order in which to observe a given set of target and calibrators, how many observations -- a.k.a. scans -- are desired, etc). These suggestions may also be indicated in the comment lines of the schedule file itself, as indicated below.

It is crucial that all the information in your schedule file be accurate, if you have any questions about any of the fields, please contact your assigned contact scientist or visit the help desk.

Although a schedule file can be prepared by simply manually collecting all the required fields into the required format, we strongly recommend the use of the NExScI getCal software as it automatically searches the Hipparcos catalog for suitable calibrators given user-selectable sets of constraints, and generates its output in the schedule file format.

Format of Schedule Files

The following is an example of a section of a schedule file, which might contain information about KI observing of one of your targets:

## faint object - cycle through target and all the cals as many times as possible.
NGC4151      12  10  32.58  +39  24  20.6   0.000   0.000  11.0  8.7   0.00  J=10  ROLE=TRG  SPECTYP=Sa  PID=15 

HIP58918     12  04  53.852  +34  37  14.289  -0.359   0.018  10.7  8.6   0.86  ROLE=CAL  SPECTYP=K1V  DIAM=0.12  DIAMERR=0.1  CALFOR=NGC4151  D=4.5 

HDC105925    12  11  25.067  +43  33  39.788  -0.445   0.007  10.1  8.4   0.70  ROLE=CAL  SPECTYP=G6V  DIAM=0.11  DIAMERR=0.0  CALFOR=NGC4151  D=5.0 

HIP60286     12  21  44.538  +39  23  48.309  -0.244  -0.017  10.3  8.5   0.74  ROLE=CAL  SPECTYP=G8V  DIAM=0.11  DIAMERR=0.1  CALFOR=NGC4151  D=4.2 

Comment lines begin with the character #. You may insert as many comment lines as you wish.


Field Item Description
1
Designation Object Designation (string). No spaces are allowed.
2-4
RA (J2000) Object right ascension in hh mm ss.s format (J2000)
5-7
Dec (J2000) Object declination in +/-dd mm ss.s format (J2000)
8
PMra RA Proper motion (arcsec/yr)
9
PMdec Dec Proper motion (arcsec/yr)
10
V
Object V magnitude (mag)
11
K
Object K magnitude (mag)
12
(B-V)
Object B-V color (mag)


The following fields are formatted as "TAG=value", as listed below. Some of these tagged fields are required and some are optional:

  • The CALFOR tag gives the target name for which the source is a calibrator; required for calibrators. Ex.:
    CALFOR=HDC4676
  • The D tag gives the distance from the target to the calibrator; optional for calibrators. Ex.:
    D=8.4
  • The DIAM tag gives the angular diameter of the calibrator; required for calibrators. Ex.:
    DIAM=0.36
  • The DIAMERR tag gives the angular diameter error of the calibrator; required for calibrators. Ex.:
    DIAMERR=0.120
  • The N tag gives the N-band magnitude of the source, requested using the --Nband and/or --IRAS options (see getCal Command-Line Options ); optional for both targets and calibrators. Ex.:
    N=3.8
  • The L tag gives the L-band magnitude of the source, requested using the --Lband (see getCal Command-Line Options ); optional for both targets and calibrators. Ex.:
    L=3.8
  • The LPRIME tag gives the L'-band ("L-prime") magnitude of the source, requested using the --Lprime (see getCal Command-Line Options ); optional for both targets and calibrators. Ex.:
    LPRIME=3.9
  • The PID tag gives a placeholder for the "project ID" required by other software; required for targets. Ex.:
    PID=?
  • The PLX tag gives the parallax of the source; optional for both targets and calibrators. Ex.:
    PLX=0.02751
  • The ROLE tag gives the "role" of the source in this getCal run, either "target" (TRG) or "calibrator" (CAL); required for both targets and calibrators. Ex.:
    ROLE=TRG
  • The SPECTYP tag gives the spectral type of the source; required for both targets and calibrators. Ex.:
    SPECTYP=F8V
This information may also be found in the getCal reference manual.

Rules on source names

Source names must have no spaces, punctuations or control characters. For sources with more than one name, please be consistent in your use of names throughout your schedule file. Maintaining this consistency among different runs will also help you identify your sources when you retrieve your data.

Tips on Choosing Calibrators

The fringe visibility measured on a target must be calibrated for instrumental and atmospheric terms using observations of stars of known visibility. Calibrator stars must therefore be either unresolved by the KI (visibility = 1.0) or of known angular size. Because the instrumental and atmospheric conditions change during the night, it is necessary to measure calibrators frequently, typically interleaved with the target observations. Since it is in general difficult to estimate accurate angular sizes for stars, it is best to use unresolved stars as calibrators whenever possible.

How do I know when a star is unresolved by KI?

A star is unresolved to KI if it gives a visibility which is indistinguishable from 1.0, given the errors in the measurement. In general, the visibility that one would measure on a star of a certain diameter depends on the star geometry, declination, hour angle, and wavelength of observation. However, we can estimate a maximum calibrator size as follows, this estimate can be safely used to guide the selection of unresolved calibrators: Assume a 5% measurement error, a maximum projected baseline given by the KI physical baseline length (about 85 meters), and K-band observations; one can easily calculate that a star of uniform disk angular diameter of about 1 mas or smaller would appear unresolved.

Other criteria must be carefully considered when selecting calibrators for your observing program. In summary, calibrators must be:

  1. Close in the sky to target (preferably within 10 degrees).
  2. Within 3 mags of near-infrared brightness (J,H,K) of target; this is due to the limited dynamic range of the KI science and angle-tracker detectors.
  3. As close to visual magnitude of target as possible, in order to insure similar response of AO system.
  4. Unresolved, as indicated above, or of well known angular diameter. This also implies that binary stars must not be used as calibrators.
  5. Preferably not (or minimally) variable.
  6. On the same North/South side of the sky as the target, in order to avoid long Keck telescope slews.
  7. Avoid the area of telescope inaccessibility near zenith i.e. avoid source declinations of 19.8 degrees (the Keck latitude) +- 3 degrees.

How many calibrators do I need?

In principle, a single good calibrator is sufficient. However, because at the resolution of the KI many stars are unknown binaries, one should provide a minimum of 3 calibrators per target (although calibrators can be shared among nearby targets). If one of the calibrators has already been observed at KI and is known to be unresolved, a minimum of 2 calibrators should be provided.

Using getCal to Choose Calibrators and Compose Schedule Files

The criteria described above for selecting calibrators are all possible input constraints to the getCal program (and its graphical interface gcGui). Moreover, getCal estimates calibrator angular diameters, both from simple stellar model tables and from fits to spectrophotometry data; and warns for multiplicity and variability based on the Hipparcos catalog. Finally, getCal can easily retrieve and use 2MASS photometry, and outputs its results in the format used in schedule files. For all those reasons, getCal is the prefered method for searching calibrators and composing schedule files. Please refer to the getCal manual for a complete description of its many features and some illustrative examples.

If you are using getCal installed on your own machine, you may want to set the getCal defaults appropriately, see getCal environment variables for details.

Provide Additional Information on your Targets

We strongly encourage that you provide your NExScI contact scientist with finding charts for those sources for which there is potential for source confusion (faint object in crowded filed). The prefered field-of-view for these charts is that of the Keck telescopes acquisition camera: 2x2 arcmins.

In addition, please also include any relevant finding notes for a given target in your schedule file, as comment fields.

If you are aware of any other peculiarities about your targets, please also include the appropriate comments in your schedule file. Examples of properties that may impact the efficiency of your KI observations are: source confusion (as described above), spatial extension on scales larger than about 0.05 arcsecs in the visible or near-infrared (will impact the performance of the adaptive optics and angle tracker sub-systems), and variabily (if you know that your target is variable, please include a comment on what you know about the likely minimum and maximum magnitudes in the appropriate band, visible and/or near-infrared).

As a KI principal investigator, you share with your NExScI contact scientist responsibility for planning your observation ahead of time as well as possible, in order to make efficient use of your awarded time. Please follow the guidelines above in order to insure good communication with your contact scientist about the details of your observing program. If instead of being expected and planned for, special difficulties arise during observing, it is likely that efficiency and therefore the time spent on your targets will be significantly reduced.

Return to KI Support Page


RMG - Sept 22 2003; revised July 2009